API Reference
Every operation on the public integration surface — parameters, responses, and schemas, generated from the cheetah-service OpenAPI spec.
API Reference
Every operation on the public integration surface, generated from cheetah-service's served spec (/openapi-public.json) — this page cannot drift from the API. Base URL, access, and usage patterns are on the Open REST API page; shared conventions live in API concepts.
Any operation can also return the standard error envelope — including 422 for invalid parameters — documented in Errors and retries.
Program runs#
Observe-only during beta: list, fetch, reconcile. Patterns — polling, the updated_since sync loop — are on the Open REST API page.
GET /runs#
Program runs across all programs, newest first, as lightweight summaries. The entry point for incremental sync — filter with updated_since.
| Parameter | In | Type | Description |
|---|---|---|---|
program_id |
query | string | null | Filter by program ID |
status |
query | string | null | Filter by status |
serial_number |
query | string | null | Filter by part serial number |
updated_since |
query | string (date-time) | null | Only return program runs updated after this ISO 8601 timestamp. Useful for incremental updates after an initial full load. |
limit |
query | integer, default 50, ≥ 1, ≤ 1000 |
|
offset |
query | integer, default 0, ≥ 0 |
Returns: 200 ProgramRunSummaryListResponse
GET /runs/active#
The currently executing program run, if any.
Returns: 200 ActiveRunResponse
GET /runs/{run_id}#
Full detail for one program run: per-step results, the event log, and the webhook deliveries it triggered.
| Parameter | In | Type | Description |
|---|---|---|---|
run_id |
path | string |
Returns: 200 ProgramRunResponse
Programs#
GET /programs#
List programs, newest first.
| Parameter | In | Type | Description |
|---|---|---|---|
robot_id |
query | string | null | Filter by robot ID |
limit |
query | integer, default 100, ≥ 1, ≤ 1000 |
|
offset |
query | integer, default 0, ≥ 0 |
Returns: 200 ProgramListResponse
GET /programs/{program_id}#
One program: its steps, run configs, and metadata.
| Parameter | In | Type | Description |
|---|---|---|---|
program_id |
path | string |
Returns: 200 ProgramResponse
GET /programs/{program_id}/runs#
Program runs of one program, newest first, as lightweight summaries.
| Parameter | In | Type | Description |
|---|---|---|---|
program_id |
path | string | |
serial_number |
query | string | null | Filter by part serial number |
updated_since |
query | string (date-time) | null | Only return program runs updated after this ISO 8601 timestamp. Useful for incremental updates after an initial full load. |
limit |
query | integer, default 100, ≥ 1, ≤ 1000 |
|
offset |
query | integer, default 0, ≥ 0 |
Returns: 200 ProgramRunSummaryListResponse
Quality report#
GET /runs/{run_id}/quality-report#
The quality report for a program run — the QC outcome with every quality check evaluated. quality_report is null until checks exist for the program run.
| Parameter | In | Type | Description |
|---|---|---|---|
run_id |
path | string |
Returns: 200 QualityReportResponse
Run files#
The consolidated manifest of every file a program run produced — CL sweep CSVs, frame files, co-processor outputs. Field semantics, retention behavior, and backfill caveats are on the Open REST API page.
GET /runs/{run_id}/files#
All files a program run produced, as FileMetadata entries. Files whose bytes were removed by retention stay listed with deleted_at set.
| Parameter | In | Type | Description |
|---|---|---|---|
run_id |
path | string |
Returns: 200 array of FileMetadata
GET /runs/{run_id}/files/{name}#
Download one file by its manifest name. 404 for a name not in the manifest; 410 Gone when the entry exists but the bytes were removed by retention.
| Parameter | In | Type | Description |
|---|---|---|---|
run_id |
path | string | |
name |
path | string |
Returns: 200 file download (application/octet-stream)
Raw capture data#
Frame ids come from the program-run detail (results.frame_ids, or each capture_frame step’s result.frame_id).
GET /sensor/frames/{frame_id}#
Metadata for one captured frame: capture timestamp, dimensions, the robot’s pose at capture, and file size.
| Parameter | In | Type | Description |
|---|---|---|---|
frame_id |
path | string |
Returns: 200 CapturedFrameResponse
GET /sensor/frames/{frame_id}/files#
Which file formats exist for a frame. Formats appear as processing completes — a missing format is a 404 on its download endpoint.
| Parameter | In | Type | Description |
|---|---|---|---|
frame_id |
path | string |
Returns: 200 FrameFileInfo
GET /sensor/frames/{frame_id}/file.ply#
Filtered point cloud (outliers removed), as PLY.
| Parameter | In | Type | Description |
|---|---|---|---|
frame_id |
path | string |
Returns: 200 file download (application/x-ply)
GET /sensor/frames/{frame_id}/file.raw.ply#
Unfiltered raw point cloud, as PLY.
| Parameter | In | Type | Description |
|---|---|---|---|
frame_id |
path | string |
Returns: 200 file download (application/x-ply)
GET /sensor/frames/{frame_id}/file.png#
Height-map image, as PNG.
| Parameter | In | Type | Description |
|---|---|---|---|
frame_id |
path | string |
Returns: 200 file download (image/png)
GET /sensor/frames/{frame_id}/file.luminance.png#
Luminance image, as PNG.
| Parameter | In | Type | Description |
|---|---|---|---|
frame_id |
path | string |
Returns: 200 file download (image/png)
GET /sensor/frames/{frame_id}/file.npy#
Raw sensor data, as a NumPy .npy array.
| Parameter | In | Type | Description |
|---|---|---|---|
frame_id |
path | string |
Returns: 200 file download (application/octet-stream)
GET /runs/{run_id}/steps/{step_index}/cl_sweep.csv#
Measurement series for a CL-sweep step, as CSV (columns: timestamp, channel_1, channel_2, …). Steps are 1-indexed.
| Parameter | In | Type | Description |
|---|---|---|---|
run_id |
path | string | |
step_index |
path | integer |
Returns: 200 file download (text/csv)
Webhooks#
The scripting surface for what Webhooks covers end to end — most teams register endpoints in cheetah-ui and use these for automation and delivery forensics.
GET /webhooks#
List registered webhooks.
Returns: 200 array of WebhookResponse
POST /webhooks#
Register a webhook. The response includes has_secret; the secret itself is never echoed back.
Body: CreateWebhookRequest
Returns: 201 WebhookResponse
GET /webhooks/{webhook_id}#
One webhook’s configuration.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_id |
path | string |
Returns: 200 WebhookResponse
PATCH /webhooks/{webhook_id}#
Update a webhook. Omitted fields are left unchanged.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_id |
path | string |
Body: UpdateWebhookRequest
Returns: 200 WebhookResponse
DELETE /webhooks/{webhook_id}#
Delete a webhook. Its past deliveries remain readable.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_id |
path | string |
Returns: 204 no body
POST /webhooks/{webhook_id}/test#
Send a synthetic WebhookTest event to the endpoint inline and return the delivery result.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_id |
path | string |
Returns: 200 TestWebhookResponse
GET /webhooks/{webhook_id}/deliveries#
Delivery log for one webhook, newest first. Page backwards with before.
| Parameter | In | Type | Description |
|---|---|---|---|
webhook_id |
path | string | |
limit |
query | integer, default 50, ≥ 1, ≤ 200 |
|
before |
query | string (date-time) | null |
Returns: 200 array of WebhookDeliveryResponse
GET /webhook-deliveries/{delivery_id}#
One delivery, with its full per-attempt history.
| Parameter | In | Type | Description |
|---|---|---|---|
delivery_id |
path | string |
Returns: 200 WebhookDeliveryDetailResponse
POST /webhook-deliveries/{delivery_id}/retry#
Re-send a non-delivered delivery immediately, as a single inline attempt. The retry reuses the same event_id, so a deduplicating receiver handles it safely; an already-delivered delivery is returned unchanged.
| Parameter | In | Type | Description |
|---|---|---|---|
delivery_id |
path | string |
Returns: 200 WebhookDeliveryDetailResponse
System#
GET /health#
Unified service health: 200 when every required component is up, 503 when one is down. The body itemizes per-component status.
Returns: 200 SystemStateResponse
Schemas#
Response and request models referenced above. Timestamps are ISO 8601 UTC; identifiers are UUIDv7 strings (see the resource model).
ActiveRunResponse#
Response for active program run query.
| Field | Type | Description |
|---|---|---|
active |
boolean | |
run (optional) |
ProgramRunResponse | null |
CapturedFrameResponse#
Response with captured frame details.
| Field | Type | Description |
|---|---|---|
id |
string | |
session_id |
string | |
sequence_number |
integer | |
frame_type |
string | |
file_path |
string | |
file_size_bytes |
integer | null | |
width |
integer | null | |
height |
integer | null | |
joint_positions |
array of number | null | |
tcp_position |
object | null | |
capture_timestamp |
string (date-time) | |
metadata |
object | null | |
created_at |
string (date-time) |
ComponentStatus#
Health of a single dependency component. id is set only for multi-instance components (robots, sensors) and distinguishes one instance from another of the same kind. Singletons (postgres, influxdb, loki, psu, ...) leave it as None.
| Field | Type | Description |
|---|---|---|
status |
"healthy" | "degraded" | "down" | "estopped" |
|
id (optional) |
string | null | |
detail (optional) |
string | null |
CreateWebhookRequest#
| Field | Type | Description |
|---|---|---|
name |
string | |
url |
string | |
subscribed_events |
array of string | |
on_failure_mode (optional) |
WebhookOnFailureMode |
|
secret (optional) |
string | null | |
enabled (optional) |
boolean |
FileMetadata#
Metadata for a file produced by a program run. Files removed from disk (e.g. by session deletion) keep their entry with deleted_at set — the record persists even when the bytes do not.
| Field | Type | Description |
|---|---|---|
name |
string | Filename, unique within the program run |
type |
string | File category: pointcloud | image | array | measurement | report |
content_type |
string | MIME type |
size_in_bytes (optional) |
integer | null | |
description (optional) |
string | null | |
href |
string | Download URL for this file |
step_index (optional) |
integer | null | 1-indexed program step that produced this file, if any |
frame_id (optional) |
string | null | Sensor frame this file belongs to, if any |
created_at |
string (date-time) | |
updated_at |
string (date-time) | |
deleted_at (optional) |
string (date-time) | null |
FrameFileInfo#
Information about available frame files.
| Field | Type | Description |
|---|---|---|
frame_id |
string | |
session_id |
string | |
available_formats |
array of string | |
files |
object |
Link#
A hypermedia link.
| Field | Type | Description |
|---|---|---|
href |
string | URL of the linked resource |
method (optional) |
string | HTTP method to use |
ProgramLinks#
Links for a program resource.
| Field | Type | Description |
|---|---|---|
self |
Link |
|
runs |
Link |
|
start_run |
Link |
|
update |
Link |
|
delete |
Link |
ProgramListResponse#
Response listing programs.
| Field | Type | Description |
|---|---|---|
programs |
array of ProgramResponse |
|
total |
integer | |
limit |
integer | |
offset |
integer |
ProgramResponse#
Response with program details.
| Field | Type | Description |
|---|---|---|
id |
string | |
name |
string | |
description (optional) |
string | null | |
robot_id (optional) |
string | null | |
sensor_id (optional) |
string | null | |
co_processor (optional) |
string | null | |
status |
string | |
steps |
array of ProgramStep |
|
run_configs (optional) |
array of RunConfig |
|
run_count (optional) |
integer | |
metadata (optional) |
object | null | |
created_at |
string (date-time) | |
updated_at |
string (date-time) | |
links (optional) |
ProgramLinks | null |
ProgramRunResponse#
Response with program run details.
| Field | Type | Description |
|---|---|---|
id |
string | |
program_id |
string | |
status |
string | |
trace_id (optional) |
string | null | |
serial_number (optional) |
string | null | |
revision (optional) |
integer | |
metadata (optional) |
object | |
progress |
RunProgressResponse |
|
steps (optional) |
StepsDetailResponse | null |
|
started_at (optional) |
string (date-time) | null | |
completed_at (optional) |
string (date-time) | null | |
error_message (optional) |
string | null | |
results (optional) |
object | null | |
event_log (optional) |
array of RunEventLogEntry | null |
|
webhook_deliveries (optional) |
array of WebhookDeliverySummary | null |
|
files (optional) |
array of FileMetadata | null |
|
created_at |
string (date-time) | |
updated_at |
string (date-time) | |
links (optional) |
RunLinks | null |
ProgramRunSummaryListResponse#
Response listing program run summaries.
| Field | Type | Description |
|---|---|---|
runs |
array of ProgramRunSummaryResponse |
|
total |
integer | |
limit |
integer | |
offset |
integer |
ProgramRunSummaryResponse#
Lightweight program run summary for list views. Excludes heavy fields: steps, event_log, results, trace_id.
| Field | Type | Description |
|---|---|---|
id |
string | |
program_id |
string | |
program_name |
string | |
status |
string | |
serial_number (optional) |
string | null | |
revision (optional) |
integer | |
metadata (optional) |
object | |
progress |
RunProgressResponse |
|
started_at (optional) |
string (date-time) | null | |
completed_at (optional) |
string (date-time) | null | |
error_message (optional) |
string | null | |
created_at |
string (date-time) | |
updated_at |
string (date-time) | |
links (optional) |
RunLinks | null |
ProgramStep#
A single step in a program.
| Field | Type | Description |
|---|---|---|
type |
StepType |
Type of step to execute |
name (optional) |
string | null | Optional name for this step |
params (optional) |
object | Step parameters |
enabled (optional) |
boolean | Whether this step will execute during a program run |
group_id (optional) |
string | null | |
group_name (optional) |
string | null | |
section_id (optional) |
string | null | |
section_name (optional) |
string | null |
QualityCheckModel#
A single quality check result.
| Field | Type | Description |
|---|---|---|
name |
string | |
status |
string | |
message (optional) |
string | null | |
value (optional) |
number | null | |
delta (optional) |
number | null | |
threshold (optional) |
number | null | |
metadata (optional) |
object |
QualityReportModel#
Session-level quality rollup.
| Field | Type | Description |
|---|---|---|
status |
string | |
checks |
array of QualityCheckModel |
|
summary (optional) |
string | null |
QualityReportResponse#
Dedicated response for the quality report endpoint.
| Field | Type | Description |
|---|---|---|
run_id |
string | |
quality_report (optional) |
QualityReportModel | null |
RunConfig#
A named program run configuration with preset metadata.
| Field | Type | Description |
|---|---|---|
name |
string | Display name for this configuration |
metadata (optional) |
object |
RunEventLogEntry#
A single event in the program run's event log.
| Field | Type | Description |
|---|---|---|
timestamp |
string (date-time) | |
event_type |
string | |
data |
object |
RunLinks#
Links for a program run resource.
| Field | Type | Description |
|---|---|---|
self |
Link |
|
program |
Link |
|
cancel (optional) |
Link | null |
|
websocket (optional) |
Link | null |
RunProgressResponse#
Progress information for a program run.
| Field | Type | Description |
|---|---|---|
total_steps |
integer | |
completed_steps |
integer | |
current_step (optional) |
integer | null |
StepStatusResponse#
Status of a single step in a program run.
| Field | Type | Description |
|---|---|---|
index |
integer | |
type |
string | |
name (optional) |
string | null | |
status |
string | |
started_at (optional) |
string (date-time) | null | |
completed_at (optional) |
string (date-time) | null | |
result (optional) |
object | null | |
error (optional) |
string | null |
StepType#
Supported program step types.
Values: "start_session" · "move_robot" · "capture_frame" · "end_session" · "wait" · "cl_sweep" · "move_motor" · "iv4_program" · "srl_read"
StepsDetailResponse#
Detailed steps breakdown.
| Field | Type | Description |
|---|---|---|
completed |
array of StepStatusResponse |
|
in_progress (optional) |
StepStatusResponse | null |
|
pending |
array of StepStatusResponse |
SystemStateResponse#
Unified service health: top-level rollup plus per-component status. Top-level status rolls up as follows: - any required component "down" -> "down" (-> HTTP 503) - otherwise any non-"healthy" component -> "degraded" (-> HTTP 200) - all "healthy" -> "healthy" (-> HTTP 200) The set of required components is owned by the rollup logic in core/system_state.py, not declared here.
| Field | Type | Description |
|---|---|---|
status |
"healthy" | "degraded" | "down" |
|
components |
object |
TestWebhookResponse#
| Field | Type | Description |
|---|---|---|
delivered |
boolean | |
status_code |
integer | null | |
error |
string | null | |
delivery_id |
string |
UpdateWebhookRequest#
| Field | Type | Description |
|---|---|---|
name (optional) |
string | null | |
url (optional) |
string | null | |
subscribed_events (optional) |
array of string | null | |
on_failure_mode (optional) |
WebhookOnFailureMode | null |
|
secret (optional) |
string | null | |
enabled (optional) |
boolean | null |
WebhookDeliveryAttemptResponse#
One HTTP attempt against the partner endpoint.
| Field | Type | Description |
|---|---|---|
attempt_number |
integer | |
started_at |
string (date-time) | |
completed_at |
string (date-time) | null | |
status_code |
integer | null | |
response_body |
string | null | |
response_headers |
object | null | |
error |
string | null |
WebhookDeliveryDetailResponse#
Full delivery record including per-attempt history. Returned by GET /webhook-deliveries/{id} and the manual-retry endpoint. attempt_history is ordered most-recent-first so the UI can render the latest exchange at the top without re-sorting.
| Field | Type | Description |
|---|---|---|
id |
string | |
webhook_id |
string | |
program_run_id |
string | null | |
event_name |
string | |
on_failure_mode |
WebhookOnFailureMode |
|
status |
WebhookDeliveryStatus |
|
attempts |
integer | |
last_status_code |
integer | null | |
last_error |
string | null | |
next_retry_at |
string (date-time) | null | |
delivered_at |
string (date-time) | null | |
payload |
object | |
created_at |
string (date-time) | |
updated_at |
string (date-time) | |
attempt_history |
array of WebhookDeliveryAttemptResponse |
WebhookDeliveryResponse#
Delivery row as returned by the list endpoint. payload is the literal JSON envelope that was POSTed to the partner (frozen at row creation, replayed verbatim on retries). Per-attempt response bodies are NOT included here — they can be heavy. Use the detail endpoint (GET /webhook-deliveries/{id}) for attempt_history.
| Field | Type | Description |
|---|---|---|
id |
string | |
webhook_id |
string | |
program_run_id |
string | null | |
event_name |
string | |
on_failure_mode |
WebhookOnFailureMode |
|
status |
WebhookDeliveryStatus |
|
attempts |
integer | |
last_status_code |
integer | null | |
last_error |
string | null | |
next_retry_at |
string (date-time) | null | |
delivered_at |
string (date-time) | null | |
payload |
object | |
created_at |
string (date-time) | |
updated_at |
string (date-time) |
WebhookDeliveryStatus#
Lifecycle of a single webhook delivery.
Values: "pending" · "delivered" · "failed" · "exhausted" (legacy — only on deliveries from before background retries were removed)
WebhookDeliverySummary#
Compact webhook delivery entry attached to a program run for UI banners.
| Field | Type | Description |
|---|---|---|
id |
string | |
webhook_id |
string | |
webhook_name |
string | |
event_name |
string | |
status |
string | |
on_failure_mode |
string | |
attempts |
integer | |
last_error (optional) |
string | null |
WebhookOnFailureMode#
Policy for handling webhook delivery failures.
Values: "IGNORE" · "WARN" · "FAIL_PROGRAM"
WebhookResponse#
| Field | Type | Description |
|---|---|---|
id |
string | |
name |
string | |
url |
string | |
subscribed_events |
array of string | |
on_failure_mode |
WebhookOnFailureMode |
|
enabled |
boolean | |
has_secret |
boolean | |
created_at |
string (date-time) | |
updated_at |
string (date-time) |