REST API¶

Overview¶

Analog Cloud exposes a versioned REST API under /api/v1. The API is the single mode of interaction with the system: both AnalogCloudClient and the analogcli package go through it. Because the API is described by an OpenAPI-compatible specification (linked below), third-party clients can interface with Analog Cloud just as easily.

Live documentation¶

The deployed server serves the OpenAPI UI at /api/docs (Swagger UI) and /api/redoc (ReDoc). For anabrid's production deployment of Analog Cloud, this is reachable at https://redac.anabrid.com/api/docs.

Authentication¶

Every request to /api/v1/* must carry a Bearer token:

Authorization: Bearer <api_key>

Missing, disabled, or unknown keys are answered with 403 Forbidden. For run-task creation, the server additionally checks device access for the user (403 on denial) and hourly / daily rate limits for the device class (429 when exceeded). Limits are set by operators in the auth.yml file — contact your operator if you need to bump your limits.

Endpoint groups¶

For more detailed information and data types, please refer to the API documentation linked above.

/system¶

/users¶

/devices¶

/tasks¶

Task search¶

POST /api/v1/tasks/search searches your own tasks with filters and pagination. All body fields are optional; an omitted filter is unconstrained, while an empty list matches nothing.

Filtering combines values with OR within a field and AND across fields. The window defaults to the last 24 hours when from/to are omitted and may span at most 90 days; a wider window is rejected with 422. Unknown body fields are also rejected with 422 (the schema is extra=forbid).

The response is a paginated envelope, TaskSearchResponse:

class TaskSearchResponse(BaseModel):
    items: list[TaskSearchItem]  # task summary + user_id
    total: int                   # full count of matching tasks, ignoring limit/offset
    limit: int
    offset: int
    next_offset: int | None      # offset + limit if more remain, else null

Non-versioned endpoints¶

Common types and workflows¶

All task creation endpoints return the same shape:

class TaskCreatedResponse(BaseModel):
    id: UUID
    type: "compile" | "run"
    state: TaskStateEnum  # always "queued" at creation
    created_at: datetime

Task state values are queued, inprogress, succeeded, failed, and cancelled; the last three are terminal. Errors use a consistent body of {"detail": "<message>"}.

Analog Cloud is a distributed system made up of a server (accepting and processing HTTP requests), a database (holding task data), a queue per registered device (a list of pending jobs to be processed), and workers that perform the actual processing of tasks. Different components may be deployed to different physical machines, but this is transparent from an API-only perspective. It is, however, useful to understand how tasks are processed in order to understand why a job might take a long time or fail:

For Developers: Generating clients¶

The OpenAPI document served at https://redac.anabrid.com/api/docs / https://redac.anabrid.com/api/redoc (with raw JSON at https://redac.anabrid.com/openapi.json, assuming anabrid's production setup) is suitable as input to any standard OpenAPI client generator. analogcli is the reference Python client; equivalent clients in other languages can be produced from the same schema.