API reference

Every endpoint the gateway serves, grouped by how it authenticates. The base URL is https://api.buildsable.com/v1.

This page is written by hand; openapi.json is generated from the router and is the one that cannot drift. If a route is in the spec and not here, the spec is right and this page is stale — tell us. Last reconciled against the live spec on 2026-09-14: every path it lists appears below. One path is listed the other way round — POST /v1/terminal/run is in the spec but not mounted on the production deployment, because the spec describes the build and that route is behind a flag.

There are four ways a request authenticates:

• Public routes take no credential. They are per-IP rate limited.
• API-key routes take a sk-sable_ key as Authorization: Bearer (see Authentication). These are the routes an agent calls.
• Session routes take a sess_ Sign-In With Ethereum bearer session and are the account-management surface behind the dashboard.
• Admin routes take the operator SABLE_ADMIN_TOKEN. The whole group is unmounted (returns 404) when no token is configured.

Every billable response carries a signed, metadata-only receipt you can verify without trusting Sable.

Machine-readable spec

The gateway describes itself. An OpenAPI 3.1 document covering every wired endpoint — paths, methods, auth scheme, request and response schemas, the x-sable-* receipt headers, and the 402 x402 accepts shape — is served straight off the API:

curl https://api.buildsable.com/openapi.json

The same document is at https://api.buildsable.com/v1/openapi.json for clients pinned to the version prefix, and it is generated from the router itself.

What the spec is checked for, and what it is not

Be precise about how much that document is worth, because the honest answer is "the route list, not the payloads". A test parses main.rs and fails the build when the two disagree, but only on the things it actually compares:

• Checked. Every mounted (path, method) appears in the spec, and every documented one is mounted — neither can drift. Each operation has a summary, a declared auth scheme, a unique operationId, a declared response for success, a declaration for every path parameter it names, and $refs that all resolve.
• Not checked. Whether a declared response schema matches the JSON a handler actually serializes. Nothing compares the two, so a schema here can be wrong. A batch of them was: thirty list operations declared a bare array while the gateway served a named-key envelope, and they were corrected in the document rather than in the handlers, because the served shape is the one clients already depend on. See List shapes for the envelope each list returns.

So generate a client from it, but check a generated list type against one live response before you ship. Request bodies and single-object responses are the parts you can lean on; list envelopes are the part to verify. Where the two ever disagree the served shape is the one that is real — we will not silently change a served shape to match a document.

npx @openapitools/openapi-generator-cli generate \
  -i https://api.buildsable.com/openapi.json \
  -g typescript-fetch -o ./sable-client

A few notes for generators. Paths carry their own /v1, so the declared server is the bare origin — don't add the prefix twice. A handful of literal segments overlap a template (/v1/receipts/shared/{id} beside /v1/receipts/{id}/share, /v1/evals/monitors beside /v1/evals/{id}, /v1/services/directory and /v1/services/manage/{key} beside /v1/services/{slug}); the gateway resolves these by preferring the literal segment, and those names are reserved, but a strict generator may want them pinned. Groups that a deployment has not configured — the admin surface, /metrics, passkeys — are described here even where they are unmounted and return 404.

For hand-written integrations you usually want the OpenAI or Anthropic SDK pointed at the base URL instead; see SDKs and Quickstart.

List shapes and pagination

Around forty-five endpoints return a list, and they do not all return it the same way. There is no rule that predicts which shape an endpoint uses — the conventions accumulated as the surface grew, and changing a served shape now would break callers who already parse it, so this section documents what is actually served rather than pretending to a consistency that is not there. Read it before you write a parser.

The three envelopes

1. Bare array. The body is the array. There is nowhere to put a cursor or a total, which is why nothing here paginates.

[{ "id": "key_…" }, { "id": "key_…" }]

GET /v1/keys · /v1/webhooks · /v1/webhooks/:id/deliveries · /v1/nodes · /v1/auth/wallets · /v1/auth/sessions · /v1/auth/passkeys · /v1/orgs · /v1/orgs/:id/members · /v1/orgs/:id/invites · /v1/billing/deposits · /v1/services/manage/:slug/calls · /v1/usage/sandboxes · /v1/sandboxes/sessions · /v1/sandboxes/snapshots

2. OpenAI list object. {"object": "list", "data": [...]}, used where the endpoint is OpenAI-compatible and a client SDK expects that literal shape.

{ "object": "list", "data": [{ "id": "file-…" }], "has_more": false }

GET /v1/models · /v1/images/models · /v1/videos/models · /v1/files · /v1/batches · /v1/videos/generations. Only /v1/batches carries has_more; the others omit it.

3. Named-key envelope. The array sits under a key named for the resource, alongside whatever context that endpoint owes you — a cap, a count, a trust statement.

{ "calls": [{ "id": "call_…" }], "count": 3, "cap": 500, "trust_model": "…" }

Everything else, keyed as follows:

What paginates

Four endpoints paginate. Every other list in this document returns one page and stops — see What truncates for where each one stops.

A cursor is opaque: pass the next_cursor you were given back as ?cursor=, verbatim, and stop when it comes back null. Do not parse one, and do not construct one — the four encode three different things inside it (/v1/usage/events and the two post boxes each carry a composite key, with a different separator each; /v1/billing/ledger carries a bare row id), and those encodings are internal. /v1/billing/ledger refuses an unparseable cursor with a 400 rather than silently restarting at page one, because quietly handing an auditor a different slice of the same money trail is the worse failure.

What truncates

Every other list endpoint returns at most one page and says nothing about it. There is no has_more, no next_cursor, and no total: a response of exactly N rows may be the whole answer or the first N of many, and only the cap below tells you which. Where an endpoint enforces a per-account cap at creation time, the cap is also the ceiling on the list, so you always have everything; those are marked complete.

If you need a complete record of metered activity or of money, use GET /v1/usage/events and GET /v1/billing/ledger: they are the two surfaces that paginate precisely because they are the two an auditor reconciles against, and a truncated audit trail is worse than no audit trail.

Public

No authentication.

Auth bootstrap

Public. This is how a wallet gets a session in the first place.

API-key auth

Bearer sk-sable_.... The metered surface an agent calls.

Sable-specific body fields

/v1/chat/completions, /v1/embeddings, /v1/messages, and /v1/responses accept extra body fields alongside the standard OpenAI or Anthropic shape:

• sable_privacy_tier: override the key's privacy tier for one call.
• sable_region: pin the serving region.
• sable_scrub: true redacts secret and PII shapes from the outbound prompt in-frame before egress.
• sable_run_id: chain this request's receipt into a named agent run. Also accepted on /v1/sandboxes.
• sable_context: declare the retrieved context (RAG documents) this call was given. The gateway fingerprints each item and stamps a verifiable context attestation on the receipt, proving the inputs without storing them. Accepted on /v1/messages too.

Unknown OpenAI-shape fields pass through to the upstream unchanged.

Session auth

Bearer sess_... from Sign-In With Ethereum. The account-management surface behind the dashboard.

Admin

Bearer $SABLE_ADMIN_TOKEN. The whole group is unmounted and returns 404 when no admin token is configured; a wrong token returns 401.

Operator metrics

Bearer $SABLE_METRICS_TOKEN, and served at the root, not under /v1 — a scraper is infrastructure, not an API consumer. Unmounted (404) when no metrics token is configured; a wrong token returns 401. Aggregate only: no per-account series and no request content. See Observability.