Resource Model

What the entities mean is the data model's job. This page is their HTTP shape: where each resource lives, how it's identified, and the conventions every representation follows.

Resources#

Resource	Lives at	Domain meaning
Program	/programs	Program
Program run	/runs, also nested as /programs/{program_id}/runs	Program run
Quality report	/runs/{run_id}/quality-report	Quality report
Captured frame	/sensor/frames/{frame_id}	Frame
Webhook	/webhooks	Webhooks
Webhook delivery	/webhook-deliveries, listed per webhook	One attempt-tracked event delivery

Program runs are the one resource with two homes: /runs lists across all programs (the right entry point for sync loops), and /programs/{program_id}/runs scopes to one program. Both return the same shape.

Identifiers#

Every primary id — run_id, program_id, frame_id, webhook_id, delivery_id — is a UUIDv7 string: globally unique and time-ordered, so ids sort by creation time. Treat them as opaque strings; the time-ordering is a useful property, not an interface to parse. Ids are permanent — a run_id identifies its program run forever, which is what makes it the natural idempotency key in your own store.

Two ids are different: robot_id and sensor_id are short operator-chosen names from the cell's configuration, not UUIDs.

Summary vs. detail#

List endpoints return summaries — enough to drive a table or a sync decision. Fetching a single resource returns the full detail; for a program run that adds per-step results, the event log, and the webhook deliveries it triggered. Don't expect every field of the detail in a list item.

Representation conventions#

• Timestamps are ISO 8601 in UTC with explicit offset — 2026-06-11T14:30:45.123456+00:00. Fields that haven't happened yet are null (started_at on a pending program run, completed_at until it's terminal).
• links — programs and program runs carry a links object of related hrefs (self, program, …). Some links point at endpoints outside the documented public surface; build against documented paths, and treat links as navigation hints rather than a contract.
• metadata is a free-form JSON object on programs and program runs, carrying what the cell's operator attached — your field names, not Cheetah's.