01 · Workspaces
Workspaces
Provision, fetch, and tear down isolated dev environments.
POST/v1/workspacescreate
GET/v1/workspaces/:idfetch
§ 01 / 06
API · v1 · OpenAPI 3.1REST · JSON · SSE
Every endpoint,
typed end-to-end.
REST + JSON over TLS, described by an OpenAPI 3.1 document checked into the same repo as the server code. Every release regenerates the TypeScript, Python, Go, and Rust SDKs from that spec — by definition in sync.
Bearer-token auth, Idempotency-Key on every non-idempotent write, signed webhooks for delivery, async run start with SSE for receipts. The same surface the workspace, the CLI, and the review tooling all read from. No private endpoints, no undocumented headers.
Coverage at a glance
0
0
0.00 %
0 ms
specopenapi 3.1 · 142 ops
transporthttps · sse · webhooks
authbearer · idempotency-key
regionsus-east-1 · eu-west-1 · ap-southeast-2
§ 02 / 06
Authentication · base URL
One header.
One host per env.
Bearer-token auth on the wire, Idempotency-Key on the writes, one host per environment. The same shape every example, sample, and SDK call uses internally — no SDK-only conveniences hidden behind the curtain.
Every request carries a bearer token in the Authorization header. Tokens come in two scopes — org-scoped for service-to-service traffic minted from the tenant settings panel, and user-scoped for human-in-the-loop flows minted from the workspace.
Non-idempotent endpoints — every POST that allocates real work — accept an Idempotency-Key header. Reuse the same key within 24 hours and the API returns the original 2xx body, byte-identical, without re-executing the side effect. Use a UUID per logical operation; don't reuse keys across distinct requests.
Every response carries an x-exai-receipt header pointing back to the run that produced it — every action is auditable from a single id, every retry is collapsible from a single key.
$ curl -X POST \ https://api.exai.cloud/v1/runs \ -H "Authorization: Bearer sk_live_8a3f..." \ -H "Idempotency-Key: 550e8400-e29b-41d4-a716..." \ -H "Content-Type: application/json" \ -d '{"plan_id":"pln_abc"}'
Production
https://api.exai.cloud/v1
shared multi-tenant · auto-scaled
TLS 1.3 · IPv4 · IPv6
Staging
https://api.staging.exai.cloud/v1
shared sandbox · resets weekly
synthetic data · rate-limited
Dedicated tenant
https://api.<tenant>.exai.cloud/v1
single-tenant · region-pinned
VPC-peered · BYO KMS
§ 03 / 06
Resource areas · the whole map
Eight resources.
One surface.
The eight areas below mirror the eight teams behind the product. If you are wiring runs from a CI service, read Orchestrator. If you are streaming audit into Splunk, read Audit. Cross-references are inline; nothing is buried in a tree.
02 · Composer
Composer
Plan-diff-apply review flow against a working tree.
POST/v1/composer/planrequest a plan
POST/v1/composer/applyapply hunks
03 · Builder
Builder
Drive prompt-to-app generation runs end-to-end.
POST/v1/builder/runsstart a build
GET/v1/builder/runs/:idfetch state
04 · Orchestrator
Orchestrator
Run typed DAGs of agents with replayable checkpoints.
POST/v1/runsstart DAG
GET/v1/runs/:id/checkpointslist snapshots
05 · Agents
Agents
Browse the registry and register custom typed agents.
GET/v1/agentslist
POST/v1/agents/customregister
06 · Templates
Templates
Reusable starting points for workspaces and DAGs.
GET/v1/templateslist
POST/v1/templates/:slug/forkfork
07 · Audit
Audit
Query the receipted event log and stream into your SIEM.
GET/v1/audit/eventsquery
POST/v1/audit/streamsconfigure SIEM
08 · Webhooks
Webhooks
Subscribe to typed events and inspect signed deliveries.
POST/v1/webhooksregister
GET/v1/webhooks/deliverieslist deliveries
§ 04 / 06
Rate limits · idempotency
A bucket per org.
A key per write.
The API is shaped to be retried. Token-bucket rate limits are measured at the gateway; idempotency is enforced at the service. Headers tell you exactly where you stand without a probe call.
Limits are token-bucket per-org and per-key, refilled continuously. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset so a polite client never has to guess. When the bucket empties the API returns 429 with a Retry-After integer in seconds — back off exactly that long, no more, no less.
Long-running endpoints are async by design. A run start returns 202 Accepted with a poll URL and a server-sent-events stream — you never block on the response, you never time out a TCP connection waiting on a 30-hour DAG.
Idempotency-Key is required on every non-idempotent write. Reuse within 24 hours collapses to a single side effect; the original 2xx body is replayed byte-identical. Different body, same key, within the window? You get a 409 conflict and nothing is executed.
Default
1,000 req / min
Per-org token-bucket. Refills continuously. Counted at the gateway, not at the service.
Burst
5,000 req / min · 30s
Per-key burst window. Drains down to default after 30 seconds. Headers report the live floor.
Long-running
POST /v1/runs · async
Run starts return 202 with a poll URL. Stream the receipt via SSE or webhook — never block on the response.
Idempotency
24h dedupe window
Idempotency-Key on POST collapses retries to a single side effect. Replays return the original 2xx body.
§ 05 / 06
Errors · signed webhooks
Ten codes.
One signature shape.
Errors are the same JSON envelope across the surface — code, name, message, receipt. Webhooks are signed with HMAC-SHA256 over a canonical request, verifiable in three lines of any language.
codenamemeaning
400invalid_requestMalformed JSON, unknown field, or missing required parameter.
401unauthorizedBearer token is missing, expired, or revoked.
402payment_requiredPlan ceiling reached or invoice past due.
403forbidden_roleToken authenticated but lacks the role for this resource.
404not_foundResource id resolves but is outside your tenant scope.
409conflictIdempotency-Key reused with a different request body.
422validation_failedSchema valid, semantics rejected (e.g. plan id from another tenant).
429rate_limitedToken-bucket exhausted. Retry after the Retry-After window.
500internal_errorUnhandled server fault. Receipt id returned for support triage.
503provider_unavailableUpstream model gateway degraded. Fail-closed by policy.
# incoming headers Webhook-Id: whk_01HV9C… Webhook-Timestamp: 1715212847 Webhook-Signature: v1=4f3ad28e… # canonical request to sign canonical = "${id}.${timestamp}.${body}" # verify (node) const sig = crypto .createHmac("sha256", secret) .update( canonical) .digest("hex"); if ( !crypto.timingSafeEqual( Buffer.from("v1=" + sig), Buffer.from(headerSig))) throw new Error("invalid signature");
§ 06 / 06
The API · final cut
Open the spec.
Generate the SDK.
142 endpoints across eight resources. Bearer-token auth on every request, Idempotency-Key on every write, signed webhooks on every delivery. Generated SDKs in TypeScript, Python, Go, and Rust — regenerated from the same OpenAPI 3.1 document on every release.
TypeScript
@exai/sdk · v1.4.0
Python
exai-sdk · 1.4.0
Go
github.com/exai/sdk-go
Rust
exai-sdk · 0.9 · community