API reference¶

Private beta

Sistemo Cloud is not open for signups yet, and the SDK packages below are not published until it is. Request an invite — the source is public on GitHub meanwhile.

The REST API is the actual product — the SDKs are thin wrappers over it. Use it directly from any language.

Base URL¶

https://api.sistemo.io

Default base URL is Cloud. For a self-hosted control plane, set SISTEMO_BASE_URL.

Authentication¶

Send your API key as a Bearer token on every request:

curl https://api.sistemo.io/v1/machines \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

See Authentication for scopes (read vs full) and how to create keys.

Conventions¶

JSON request and response bodies (Content-Type: application/json).
Timestamps are RFC 3339 / ISO 8601 UTC (2026-06-23T17:30:43Z).
IDs are UUIDs.
Errors use HTTP status codes + a JSON body { "detail": "...", "code": "..." }. See Errors.
Idempotency — pass an Idempotency-Key header on POST /v1/machines to safely retry creates.

Endpoints at a glance¶

Group	Endpoints
Machines	`GET/POST /v1/machines`, `GET /v1/machines/{id}`, `POST …/stop`, `…/start`, `DELETE …`
Exec	`POST /v1/machines/{id}/exec`
Volumes	`GET/POST /v1/volumes`, `POST …/attach`, `…/detach`, `DELETE …`
Snapshots	`POST/GET …/snapshots`, `GET /v1/snapshots`, `POST …/restore`, `DELETE …`
Images	`GET /v1/images`
API keys	`GET/POST/DELETE /v1/api-keys` (dashboard session only)

Rate limits¶

Mutating routes are rate-limited per account; exec has its own limit. On 429, back off and retry (see Errors).