REST Endpoints¶

Detailed documentation for all REST API endpoints.

PV Endpoints¶

Search PVs¶

GET /v1/pvs

Search for PVs with optional filters.

Query Parameters:

Parameter	Type	Description
`query`	string	Search term (matches address or description)
`tag_ids`	array	Filter by tag IDs
`limit`	integer	Max results (default: 100)

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "setpoint_address": "QUAD:LI21:201:BDES",
      "readback_address": "QUAD:LI21:201:BACT",
      "description": "Quadrupole magnet",
      "tags": [
        {"id": "...", "name": "Magnet"}
      ]
    }
  ]
}

Search PVs (Paginated)¶

GET /v1/pvs/paged

Search PVs with cursor-based pagination.

Query Parameters:

Parameter	Type	Description
`query`	string	Search term
`tag_ids`	array	Filter by tag IDs
`limit`	integer	Page size (default: 100)
`cursor`	string	Continuation token

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": {
    "items": [...],
    "next_cursor": "eyJpZCI6IjU1MGU4...",
    "has_more": true
  }
}

Create PV¶

POST /v1/pvs

Create a new PV.

Request Body:

{
  "setpoint_address": "TEST:PV:SETPOINT",
  "readback_address": "TEST:PV:READBACK",
  "config_address": null,
  "device": "Test Device",
  "description": "Test PV for documentation",
  "abs_tolerance": 0.01,
  "rel_tolerance": 0.001,
  "tag_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "setpoint_address": "TEST:PV:SETPOINT",
    "readback_address": "TEST:PV:READBACK",
    ...
  }
}

Bulk Create PVs¶

POST /v1/pvs/multi

Create multiple PVs in a single request.

Request Body:

{
  "pvs": [
    {
      "setpoint_address": "PV:1",
      "description": "First PV"
    },
    {
      "setpoint_address": "PV:2",
      "description": "Second PV"
    }
  ]
}

Update PV¶

PUT /v1/pvs/{id}

Update an existing PV.

Path Parameters:

Parameter	Type	Description
`id`	UUID	PV ID

Request Body:

{
  "description": "Updated description",
  "abs_tolerance": 0.02
}

Delete PV¶

DELETE /v1/pvs/{id}

Delete a PV.

Path Parameters:

Parameter	Type	Description
`id`	UUID	PV ID

Snapshot Endpoints¶

List Snapshots¶

GET /v1/snapshots

List all snapshots.

Query Parameters:

Parameter	Type	Description
`limit`	integer	Max results
`offset`	integer	Skip N results

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": [
    {
      "id": "...",
      "title": "Morning snapshot",
      "comment": "Before tuning",
      "created_by": "operator",
      "created_at": "2024-01-15T10:30:00Z",
      "pv_count": 1500
    }
  ]
}

Create Snapshot¶

POST /v1/snapshots

Create a new snapshot (asynchronous operation).

Request Body:

{
  "title": "Morning snapshot",
  "comment": "Before beam tuning",
  "created_by": "operator",
  "pv_ids": ["...", "..."],
  "tag_ids": ["..."],
  "use_cache": true
}

Field	Type	Description
`title`	string	Snapshot name
`comment`	string	Optional description
`created_by`	string	Creator identifier
`pv_ids`	array	Specific PVs to include
`tag_ids`	array	Include PVs with these tags
`use_cache`	boolean	Read from Redis cache (fast) or EPICS (fresh)

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": {
    "job_id": "770e8400-e29b-41d4-a716-446655440002"
  }
}

Poll /v1/jobs/{job_id} for progress and completion.

Get Snapshot¶

GET /v1/snapshots/{id}

Get a snapshot with all its values.

Path Parameters:

Parameter	Type	Description
`id`	UUID	Snapshot ID

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": {
    "id": "...",
    "title": "Morning snapshot",
    "values": [
      {
        "pv_name": "QUAD:LI21:201:BDES",
        "setpoint_value": 42.5,
        "readback_value": 42.48,
        "status": 0,
        "severity": 0
      }
    ]
  }
}

Delete Snapshot¶

DELETE /v1/snapshots/{id}

Delete a snapshot and all its values.

Restore Snapshot¶

POST /v1/snapshots/{id}/restore

Restore snapshot values to EPICS (asynchronous operation).

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": {
    "job_id": "880e8400-e29b-41d4-a716-446655440003"
  }
}

Compare Snapshots¶

GET /v1/snapshots/{id}/compare/{id2}

Compare two snapshots and show differences.

Query Parameters:

Parameter	Type	Description
`tolerance`	float	Difference threshold (default: uses PV tolerances)

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": {
    "snapshot1_id": "...",
    "snapshot2_id": "...",
    "differences": [
      {
        "pv_name": "QUAD:LI21:201:BDES",
        "value1": 42.5,
        "value2": 43.2,
        "diff": 0.7,
        "diff_percent": 1.6
      }
    ],
    "total_pvs": 1500,
    "different_count": 23
  }
}

Tag Endpoints¶

GET /v1/tags

List all tag groups with their tags.

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": [
    {
      "id": "...",
      "name": "Area",
      "description": "Machine areas",
      "tags": [
        {"id": "...", "name": "LI21"},
        {"id": "...", "name": "LI22"}
      ]
    }
  ]
}

POST /v1/tags

Create a new tag group.

Request Body:

{
  "name": "Subsystem",
  "description": "Device subsystems",
  "tags": [
    {"name": "Magnet"},
    {"name": "BPM"},
    {"name": "Feedback"}
  ]
}

GET /v1/tags/{id}

Get a tag group with all its tags.

PUT /v1/tags/{id}

Update a tag group.

DELETE /v1/tags/{id}

Delete a tag group and all its tags.

Job Endpoints¶

Get Job Status¶

GET /v1/jobs/{id}

Get the status and progress of a background job.

Path Parameters:

Parameter	Type	Description
`id`	UUID	Job ID

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": {
    "id": "...",
    "type": "CREATE_SNAPSHOT",
    "status": "IN_PROGRESS",
    "progress": 45,
    "data": {
      "processed": 675,
      "total": 1500
    },
    "result_id": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:15Z"
  }
}

Job Status Values:

Status	Description
`PENDING`	Job created, waiting for worker
`IN_PROGRESS`	Worker is processing
`COMPLETED`	Successfully finished
`FAILED`	Error occurred
`RETRYING`	Automatic retry in progress

Health Endpoints¶

Overall Health¶

GET /v1/health

Check overall API health.

Database Health¶

GET /v1/health/db

Check database connectivity.

Redis Health¶

GET /v1/health/redis

Check Redis connectivity.

Monitor Status¶

GET /v1/health/monitor/status

Check PV monitor process health.

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": {
    "healthy": true,
    "last_heartbeat": "2024-01-15T10:30:00Z",
    "pv_count": 40000,
    "connected_count": 39850
  }
}

Circuit Breaker Status¶

GET /v1/health/circuits

Check circuit breaker status by IOC prefix.

Response:

{
  "errorCode": 0,
  "errorMessage": null,
  "payload": {
    "circuits": {
      "QUAD:LI21": {"state": "CLOSED", "failures": 0},
      "BPM:LI22": {"state": "OPEN", "failures": 5}
    }
  }
}

REST Endpoints¶

PV Endpoints¶

Search PVs¶

Search PVs (Paginated)¶

Create PV¶

Bulk Create PVs¶

Update PV¶

Delete PV¶

Snapshot Endpoints¶

List Snapshots¶

Create Snapshot¶

Get Snapshot¶

Delete Snapshot¶

Restore Snapshot¶

Compare Snapshots¶

Tag Endpoints¶

List Tag Groups¶

Create Tag Group¶

Get Tag Group¶

Update Tag Group¶

Delete Tag Group¶

Job Endpoints¶

Get Job Status¶

Health Endpoints¶

Overall Health¶

Database Health¶

Redis Health¶

Monitor Status¶

Circuit Breaker Status¶