HTTP API overview

Base URL, authentication, idempotency, the error envelope and every resource group of the runstate HTTP API, generated from the OpenAPI document.

Both SDKs are built on this API; each operation below lists the SDK call that uses it. Use it directly from any language, or to see exactly what an SDK call sends. Every page in this section is generated from openapi.yaml (OpenAPI 3.1.0, contract version 0.1.0), the same document the API serves at https://api.getrunstate.com/openapi.yaml.

Base URL and paths

https://api.getrunstate.com

Every coordination endpoint lives under /v1/spaces/{spaceId}. A space is a project or environment in your organization; copy its id from the console at app.getrunstate.com. The API calls a run a scope, a queue a mailbox, a slot pool a permit, a limit an allowance, sleep a timer and together a barrier.

Authentication

Send an API key from the console as a bearer token on every request:

Authorization: Bearer <RUNSTATE_API_KEY>

Each key carries permissions, and each operation below lists the one it needs. coordination_read reads runs, tasks, queues, events and resources. coordination_write does the runtime work: runs, once records, claims, sending and receiving, tasks, taking pool and quota units, reserving and settling budget, barrier arrivals and timers. resource_config creates queues, pools, quotas, budgets, barriers, work limits and webhook destinations, and changes space limits. usage_read reads usage, limits, diagnostics and webhook delivery history. The PUT .../by-name/{name} operations look resources up with coordination_read and also need resource_config to create one. A key without the permission an operation needs gets FORBIDDEN. See API keys and permissions.

A key used outside the spaces it is allowed for gets FORBIDDEN. An id that belongs to another organization gets NOT_FOUND, so ids never leak across tenants.

Idempotency

Operations marked Idempotency-Key header: required reject requests without the header (VALIDATION_FAILED). Send a fresh unique value per logical operation and reuse it when you retry that same operation: within 24 hours the stored response is replayed instead of doing the work twice. Reusing a key with a different request body returns IDEMPOTENCY_CONFLICT. Both SDKs send a fresh key on every non-GET request and reuse it across their own transport retries.

Task submission has a second, longer-lived layer: the task key. See Shared tasks.

Errors

Every error uses one envelope:

{ "error": { "code": "SCOPE_CANCELLED", "message": "…", "requestId": "…" } }

Branch on code, never on message. The full list of codes, their HTTP statuses and what retries them is on Errors & retries.

Your first request

curl -X PUT "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/runs/nightly" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

The response is the active run named nightly (created if there wasn’t one), with its id. Pass that id as scopeId to once records, tasks and the other resources below. Every process that uses the same name joins the same run.

Resource groups

Group	What it covers	Operations
Runs (scopes)	Join, create, inspect, stop and finish runs. The API calls a run a scope.	6
Once	Work done once per run, with the result stored for every caller.	5
Claims	Exclusive, leased ownership of a named key inside a run.	5
Tasks	Durable, joinable tasks with one recorded result, plus resource-aware admission.	8
Work queues (mailboxes)	Work queues and inboxes (mailboxes), and settling the messages delivered from them.	9
Shared quotas (allowances)	Fixed-window shared quotas with durable FIFO waiting. The API calls them allowances.	9
Concurrency pools (permits)	Capacity counters (permits), the leased grants taken from them, and their waiting line.	9
Work limits	Bounds on outstanding admitted work under a run.	2
Budgets	Exact-decimal spend budgets: reserve, settle, void.	7
Task groups	Collective completion: decide once when N results are accepted, the first is accepted, or all members finish.	9
Barriers	Wait-for-all rendezvous points.	6
Timers	Durable wakeups.	6
Events, watch & webhooks	The event journal, reconnectable long-poll watch, and webhook destinations.	4
Diagnostics, usage & limits	Read-only diagnostic views, usage counters and per-space limits.	7

Not covered here

The OpenAPI document also describes /console/v1/... endpoints (used by the console with a signed-in session, not API keys) and /public/v1/preview-requests and /public/v1/plan-requests (the marketing site’s access and paid-plan forms). They are not part of the developer API and are omitted from this reference. Organization, space and API-key management is done in the console and is not part of the public API today.