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 thin, typed wrappers over this API. 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
Section titled “Base URL and paths”https://api.getrunstate.comEvery 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 work queue a mailbox, a concurrency pool a permit, and a shared quota an allowance.
Authentication
Section titled “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, 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. 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
Section titled “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 Claims, shared tasks and takeover.
Errors
Section titled “Errors”Every error uses one envelope:
{ "error": { "code": "CLAIM_HELD", "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
Section titled “Your first request”curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/scopes" \ -H "Authorization: Bearer $RUNSTATE_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{}'The response is the new run, with its id. Pass that id as scopeId to claims, messages, tasks and the other resources below.
Resource groups
Section titled “Resource groups”| Group | What it covers | Operations |
|---|---|---|
| Runs (scopes) | Create, inspect, cancel and complete runs. The API calls a run a scope. | 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. | 8 |
| Shared quotas (allowances) | Fixed-window shared quotas with durable FIFO waiting. The API calls them allowances. | 8 |
| Concurrency pools (permits) | Capacity counters (permits) and the leased grants taken from them. | 6 |
| Work limits | Bounds on outstanding admitted work under a run. | 2 |
| Budgets | Exact-decimal spend budgets: reserve, settle, void. | 6 |
| 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. | 5 |
| Timers | Durable wakeups. | 5 |
| 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
Section titled “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 (the marketing site’s access form). 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.