Skip to content

API Reference

Squirrel Backend provides a REST API for managing EPICS PVs, snapshots, and tags.

Base URL

All API endpoints are prefixed with /v1/.

  • Local Development: http://localhost:8000/v1/
  • Docker: http://localhost:8080/v1/

Interactive Documentation

When the server is running, interactive API documentation is available at:

Response Format

All responses follow a standard format:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": { ... }
}
Field Type Description
errorCode integer 0 for success, non-zero for errors
errorMessage string Error description (null on success)
payload object Response data

Error Codes

Code Meaning
0 Success
1 Validation error
2 Not found
3 Database error
4 EPICS error
5 Internal error

Endpoint Summary

PV Endpoints (/v1/pvs)

Method Endpoint Description
GET /v1/pvs Search PVs (simple)
GET /v1/pvs/paged Search PVs with pagination
POST /v1/pvs Create single PV
POST /v1/pvs/multi Bulk create PVs
PUT /v1/pvs/{id} Update PV
DELETE /v1/pvs/{id} Delete PV

Snapshot Endpoints (/v1/snapshots)

Method Endpoint Description
GET /v1/snapshots List snapshots
POST /v1/snapshots Create snapshot (async)
GET /v1/snapshots/{id} Get snapshot with values
DELETE /v1/snapshots/{id} Delete snapshot
POST /v1/snapshots/{id}/restore Restore to EPICS
GET /v1/snapshots/{id}/compare/{id2} Compare two snapshots

Tag Endpoints (/v1/tags)

Method Endpoint Description
GET /v1/tags List tag groups
POST /v1/tags Create tag group
GET /v1/tags/{id} Get tag group with tags
PUT /v1/tags/{id} Update tag group
DELETE /v1/tags/{id} Delete tag group

Job Endpoints (/v1/jobs)

Method Endpoint Description
GET /v1/jobs/{id} Get job status and progress

Health Endpoints (/v1/health)

Method Endpoint Description
GET /v1/health Overall health
GET /v1/health/db Database connectivity
GET /v1/health/redis Redis connectivity
GET /v1/health/monitor/status PV monitor health
GET /v1/health/circuits Circuit breaker status

WebSocket (/ws)

Real-time PV value streaming.

Pagination

Paginated endpoints use continuation tokens (not offset-based):

{
  "items": [...],
  "next_cursor": "abc123",
  "has_more": true
}

To get the next page:

GET /v1/pvs/paged?cursor=abc123

Authentication

Currently, the API does not require authentication. This may change in future versions.

Rate Limiting

No rate limiting is currently enforced. For production deployments, consider adding rate limiting at the load balancer level.

Detailed Documentation