Reference

REST API

Provision, start, stop and observe instances and run generations over HTTPS. Mirrors the CLI one for one.

Basics

Item	Value
Base URL	https://www.clockingcloud.com/v1
Authentication	`Authorization: Bearer <api key>`. See Authentication.
Request bodies	`application/json`, or `application/yaml` for instance definitions.
Responses	`application/json`, UTF-8. Timestamps are RFC 3339 in UTC.
Versioning	The version is in the path. Within v1, fields may be added but never removed or repurposed.

Smoke test

curl https://www.clockingcloud.com/v1/balance \
  -H "Authorization: Bearer $CLOCKINGCLOUD_API_KEY"

Instances

Method and path	Description
POST /instances	Create or update from a JSON or YAML definition (same as `clockingcloud deploy -f`). Returns 200 with the instance.
GET /instances	List instances. Supports `state`, `limit` and `cursor`.
GET /instances/{name}	Get one instance.
PATCH /instances/{name}	Change `scale`, `idle_timeout` or `env`.
POST /instances/{name}/start	Start. Returns 202.
POST /instances/{name}/stop	Stop and release GPUs. Returns 202.
DELETE /instances/{name}	Delete the definition. Volumes are kept.
GET /instances/{name}/logs	Server-sent events with `follow=true`, otherwise JSON lines. Supports `since` and `grep`.
GET /instances/{name}/metrics	Metrics as JSON. Add `format=prometheus` for text exposition.

Provision from CI/CD

curl -X POST https://www.clockingcloud.com/v1/instances \
  -H "Authorization: Bearer $CLOCKINGCLOUD_API_KEY" \
  -H "Content-Type: application/yaml" \
  --data-binary @clockingcloud.yaml

Response

{
  "name": "product-shots",
  "model": "z-image-turbo",
  "state": "running",
  "gpu": "h100",
  "gpus": 1,
  "scale": { "min": 0, "max": 8 },
  "replicas": 2,
  "idle_timeout": "60s",
  "created_at": "2026-10-25T14:02:11Z",
  "updated_at": "2026-10-25T14:02:11Z"
}

Start and stop

curl -X POST https://www.clockingcloud.com/v1/instances/product-shots/start \
  -H "Authorization: Bearer $CLOCKINGCLOUD_API_KEY"

curl -X POST https://www.clockingcloud.com/v1/instances/product-shots/stop \
  -H "Authorization: Bearer $CLOCKINGCLOUD_API_KEY"

Generations

Method and path	Description
POST /runs	Start a generation. Set `instance` to use a deployed instance, or `model` for a one-off run. Returns 202 with a run.
GET /runs/{id}	Get status and, when complete, signed output URLs.
DELETE /runs/{id}	Cancel a queued or running generation.
GET /runs/{id}/trace	Per-stage seconds and cost.

Request

curl -X POST https://www.clockingcloud.com/v1/runs \
  -H "Authorization: Bearer $CLOCKINGCLOUD_API_KEY" \
  -H "Idempotency-Key: 6f1d2c3e-order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "instance": "product-shots",
    "input": {
      "prompt": "a ceramic mug on a linen table",
      "width": 1024,
      "height": 1024,
      "seed": 42
    }
  }'

Response (202)

{
  "id": "req_01JA7X9K2M",
  "state": "queued",
  "instance": "product-shots",
  "created_at": "2026-10-25T14:05:00Z"
}

Run states are queued, running, succeeded, failed and canceled. Output URLs on a succeeded run are signed and expire after one hour. Output is also written to any mounted volume. Poll GET /runs/{id}, or write results to a volume and read them from there.

Other resources

Method and path	Description
GET /models	The model catalog.
GET /volumes, POST /volumes, DELETE /volumes/{name}	Create a Global Volume (`size_gb` 10 to 10000) or connect a bucket (`uri`).
GET /ssh-keys, POST /ssh-keys, DELETE /ssh-keys/{id}	Manage public keys.
GET /secrets, PUT /secrets/{name}, DELETE /secrets/{name}	List names, set or delete. Values are write-only.
GET /balance	Remaining credit in cents.
GET /usage	Spend by `instance`, `model` or `gpu`. Supports `since` and `by`.
GET /api-keys, POST /api-keys, DELETE /api-keys/{id}	Manage API keys. The secret is returned only on creation.

Conventions

Idempotency

Send an Idempotency-Key header (up to 128 characters) on any POST. Repeating a request with the same key within 24 hours returns the original response instead of doing the work twice, so a network retry never double-charges.

Pagination

List endpoints return { "data": [...], "next_cursor": "..." }. Pass cursor to continue and limit (1 to 100, default 25) to size pages. next_cursor is null on the last page.

Rate limits

Each API key may make 600 requests per minute. Responses include RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Exceeding the limit returns 429 with a Retry-After header in seconds. Back off exponentially and honor it.

Errors

Every error uses one shape. See Errors for the full code list.

Error response (402)

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your balance is $0.00. Add credit to start instances.",
    "request_id": "req_01JA7XAB3C",
    "doc_url": "https://clockingcloud.com/docs/errors#insufficient_credits"
  }
}

Something unclear or missing? Email hello@clockingcloud.com.