# HTTP API overview > Base URL, authentication, idempotency, the error envelope and every resource group of the runstate HTTP API, generated from the OpenAPI document. Source: https://docs.getrunstate.com/api/ 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`](https://docs.getrunstate.com/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 ```text 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](https://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 Send an API key from the console as a bearer token on every request: ```http Authorization: Bearer ``` 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](https://docs.getrunstate.com/configuration/#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 [Claims, shared tasks and takeover](https://docs.getrunstate.com/guides/work-once/#shared-tasks). ## Errors Every error uses one envelope: ```json { "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](https://docs.getrunstate.com/errors/). ## Your first request ```bash 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 | Group | What it covers | Operations | | --- | --- | --- | | [Runs (scopes)](https://docs.getrunstate.com/api/runs/) | Create, inspect, cancel and complete runs. The API calls a run a scope. | 5 | | [Claims](https://docs.getrunstate.com/api/claims/) | Exclusive, leased ownership of a named key inside a run. | 5 | | [Tasks](https://docs.getrunstate.com/api/tasks/) | Durable, joinable tasks with one recorded result, plus resource-aware admission. | 8 | | [Work queues (mailboxes)](https://docs.getrunstate.com/api/work-queues/) | Work queues and inboxes (mailboxes), and settling the messages delivered from them. | 8 | | [Shared quotas (allowances)](https://docs.getrunstate.com/api/quotas/) | Fixed-window shared quotas with durable FIFO waiting. The API calls them allowances. | 8 | | [Concurrency pools (permits)](https://docs.getrunstate.com/api/pools/) | Capacity counters (permits) and the leased grants taken from them. | 6 | | [Work limits](https://docs.getrunstate.com/api/work-limits/) | Bounds on outstanding admitted work under a run. | 2 | | [Budgets](https://docs.getrunstate.com/api/budgets/) | Exact-decimal spend budgets: reserve, settle, void. | 6 | | [Task groups](https://docs.getrunstate.com/api/task-groups/) | Collective completion: decide once when N results are accepted, the first is accepted, or all members finish. | 9 | | [Barriers](https://docs.getrunstate.com/api/barriers/) | Wait-for-all rendezvous points. | 5 | | [Timers](https://docs.getrunstate.com/api/timers/) | Durable wakeups. | 5 | | [Events, watch & webhooks](https://docs.getrunstate.com/api/events/) | The event journal, reconnectable long-poll watch, and webhook destinations. | 4 | | [Diagnostics, usage & limits](https://docs.getrunstate.com/api/diagnostics/) | 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` (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.