API reference
Every endpoint the gateway serves, grouped by how it authenticates. The base
URL is https://api.buildsable.com/v1.
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 asAuthorization: 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 (returns404) when no token is configured.
Every billable response carries a signed, metadata-only receipt you can verify without trusting Sable.
Public
No authentication.
| Method | Path | Notes |
|---|---|---|
| GET | / | Service banner JSON. |
| GET | /healthz | Liveness check. Returns ok. |
| GET | /v1/models | Model catalog under stable Sable ids, with per-Mtok pricing. Models pinned to an unconfigured provider are omitted. |
| GET | /v1/images/models | Image-generation model catalog with per-image pricing. Empty until an image provider is enabled on the deployment. |
| GET | /v1/nodes | Node registry: the gateway, attested TEE backends, and genuinely enrolled fleet nodes. See node agent contract. |
| POST | /v1/nodes/heartbeat | Node-key auth (nk-sable_ bearer). The fleet's 60s heartbeat with capability and endpoint refresh. |
| GET | /v1/status | Recorded gateway health and uptime, plus confidential and sandbox posture blocks when those backends are configured. |
| GET | /v1/attestation | Live verified TEE attestation, or verified:false with a sanitized error. See privacy tiers. |
| GET | /v1/billing/plans | Sable Pro plan catalog: fees, retention, limits, per-feature flags. |
| GET | /v1/billing/methods | How to pay: treasury address, chains, USDT contracts, confirmations, plus a Solana block when configured. See paying with USDT. |
| GET | /v1/receipts/pubkey | The secp256k1 receipt-signer address and scheme. |
| POST | /v1/receipts/verify | Verify a {receipt, signature} (EIP-191). Returns {valid, recovered_address, payload}. |
| GET | /v1/receipts/shared/:id | A receipt its owner explicitly shared, viewable at /r/{request_id}. |
| GET | /v1/receipts/:id/badge.svg | A live SVG verification badge for a receipt, embeddable via a plain <img>. |
| GET | /v1/passport | Public agent directory: minted passports ranked by verified runs, then receipts. Provable activity, not a trust score. |
| GET | /v1/passport/:handle | Public agent passport lookup by handle. |
| GET | /v1/explorer | Public proof-explorer feed: aggregate proof counts plus recent owner-shared receipts, passports, and on-chain anchors. |
| GET | /v1/vault/chain/:id | Content-free hash chain for a vault asset id, recomputable by anyone. |
| GET | /v1/vault/anchors/:id | An anchor batch: root, ordered event hashes, and Solana signature. |
| GET | /v1/vault/view/:token | Read a vault asset through a scoped view key. |
| POST | /v1/relay-access/:secret | Open a Relay by its link secret. Body {pin?}; expired, revoked, or capped links answer 404 uniformly. |
| POST | /v1/relay-access/:secret/objects/:id | Fetch one relay file's content. View-only relays serve only image/* and text/*. |
| POST | /v1/assistant | Keyless "Ask Sable" assistant. Persists nothing and mints no receipt. |
Auth bootstrap
Public. This is how a wallet gets a session in the first place.
| Method | Path | Notes |
|---|---|---|
| POST | /v1/auth/nonce | Returns a {nonce} (EIP-4361, 5-minute TTL) to sign. |
| POST | /v1/auth/verify | Verify a SIWE message and signature. Returns a sess_ token. See Authentication. |
API-key auth
Bearer sk-sable_.... The metered surface an agent calls.
| Method | Path | Notes |
|---|---|---|
| POST | /v1/chat/completions | OpenAI-shape chat completions. Supports stream:true. |
| POST | /v1/embeddings | OpenAI-shape embeddings. |
| POST | /v1/messages | Anthropic Messages API. Translates and delegates to the chat handler. |
| POST | /v1/sandboxes | Metered sandbox code execution. Accepts stream:true and an optional Idempotency-Key header. |
| POST | /v1/mcp | Remote MCP server, JSON-RPC tools. |
| POST | /v1/keys/delegate | Parent-key-authed: mint a bounded delegated sub-key mid-run. |
| GET | /v1/credit | Key-authed balance including held and spendable credit: an agent's runway. |
| POST | /v1/memory/collections | Create a Sable Memory collection: a metered, sealed knowledge base. |
| GET | /v1/memory/collections | List your memory collections. |
| DELETE | /v1/memory/collections/:id | Delete a collection and its sealed chunks. |
| POST | /v1/memory/collections/:id/documents | Chunk, embed, and store a document. Billed as embedding usage. |
| POST | /v1/memory/collections/:id/search | Semantic search a collection; returns the top matching chunks. |
| PUT | /v1/state/:key | Set durable agent state. Body {value, namespace?}; sealed at rest. |
| GET | /v1/state/:key | Read one state value. ?namespace= selects the namespace. |
| GET | /v1/state | List state keys in a namespace (no values). |
| DELETE | /v1/state/:key | Delete one state value. |
| POST | /v1/agents/:id/messages | Deliver a message to another of your agents' mailboxes. Account-scoped. |
| GET | /v1/agents/:id/messages | Read an agent's mailbox. ?consume=true marks read; ?unread_only=. |
| POST | /v1/pay/requests | Mint a signed payment request invoice. Non-custodial; EVM chains. |
| GET | /v1/pay/requests/:id | Fetch a payment request and its status. |
| POST | /v1/pay/requests/:id/settle | Verify the on-chain transfer and return a signed settlement receipt. Body {tx_hash}. |
| POST | /v1/images/generations | OpenAI-shape image generation, metered per image with a signed receipt. Where enabled. |
Sable-specific body fields
/v1/chat/completions, /v1/embeddings, and /v1/messages 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:trueredacts 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/messagestoo.
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.
| Method | Path | Notes |
|---|---|---|
| POST | /v1/keys | Mint an API key with optional scopes. Plaintext returned once. |
| GET | /v1/keys | List keys (prefixes and metadata only) with subtree spend. |
| DELETE | /v1/keys/:id | Revoke a key, cascading over its delegated subtree. |
| POST | /v1/keys/:id/rotate | Mint a scope-identical replacement; the old key expires after a grace window. |
| POST | /v1/keys/:id/unfreeze | Lift an automatic circuit-breaker freeze on a key. |
| POST | /v1/mandates | Create a signed, bounded spending mandate that mints a constrained sub-key. |
| GET | /v1/mandates | List the account's mandates. |
| DELETE | /v1/mandates/:id | Revoke a mandate. |
| POST | /v1/mandates/:id/proof | Mint a publicly-verifiable authorization certificate for a mandate. |
| POST | /v1/passport | Mint a signed agent passport from the agent's own provable history. |
| POST | /v1/agents | Deploy a hosted agent: seal the code, mint its bounded key, schedule it. Max 20 per account. |
| GET | /v1/agents | List hosted agents with schedule, last run, and run count. |
| POST | /v1/agents/:id/trigger | Run a hosted agent now. Returns the full sandbox response once; output is never stored. |
| POST | /v1/agents/:id/gate | Enable or disable a hosted agent. Body {enabled: bool}. |
| DELETE | /v1/agents/:id | Delete a hosted agent: revokes its key and destroys the sealed code. |
| POST | /v1/ghost/sessions | Start a Ghost: an ephemeral scoped key whose metadata is purged at destruction. Key shown once. |
| GET | /v1/ghost/sessions | List ghost sessions. |
| GET | /v1/ghost/sessions/:id | One ghost session, including seconds_remaining. |
| POST | /v1/ghost/sessions/:id/extend | Extend a ghost. Total lifetime capped at 24 hours. |
| POST | /v1/ghost/sessions/:id/destroy | Destroy a ghost now: revoke its key, purge its metadata. |
| POST | /v1/relays | Create a Relay: sealed temporary share. One-time share_url returned once. |
| GET | /v1/relays | List your relays (metadata only: status, access counts, sizes). |
| POST | /v1/relays/:id/revoke | Revoke a relay: destroys the ciphertext immediately. |
| GET | /v1/runs | List per-run receipt hash chains. |
| GET | /v1/runs/:id | One run: its chained, individually-signed receipts. |
| POST | /v1/runs/:id/proof | A signed run proof: head hash, receipt count, total cost, span, anchor. |
| POST | /v1/runs/:id/audit | A signed, content-free compliance audit pack for the whole run. |
| GET | /v1/receipts/:id | Re-fetch a stored receipt by request id or usage-event id. |
| POST | /v1/receipts/:id/share | Opt a receipt into public fetchability. |
| DELETE | /v1/receipts/:id/share | Opt a receipt back out of public fetchability. |
| GET | /v1/usage | Aggregate lifetime usage for the dashboard. |
| GET | /v1/usage/stream | SSE feed of new metering events for the account. |
| GET | /v1/usage/events | Raw metering ledger with filters, keyset cursor, and ?format=csv export. |
| POST | /v1/usage/statement | Mint a signed spend statement for a period. See AgentFinOps. |
| GET | /v1/usage/sandboxes | Sandbox run history (metadata only). |
| GET | /v1/usage/sandboxes/:id | One sandbox run. |
| GET | /v1/billing/balance | Credit position including held and spendable. |
| POST | /v1/billing/deposits | Verify an on-chain USDT transfer and credit it. Idempotent. See paying with USDT. |
| GET | /v1/billing/deposits | Deposit history. |
| POST | /v1/billing/deposits/refresh | Re-check every pending deposit. |
| GET | /v1/billing/ledger | Append-only credit ledger behind the balance. |
| GET | /v1/billing/alerts | The account's balance_low webhook threshold. |
| PUT | /v1/billing/alerts | Set the balance_low threshold (null = deployment default). |
| GET | /v1/billing/subscription | Current Sable Pro plan, period end, auto-renew, balance. |
| POST | /v1/billing/subscription | Subscribe or change plan. Paid plans debit the monthly fee from the prepaid balance; 402 if it cannot cover it. |
| POST | /v1/billing/subscription/cancel | Cancel auto-renew; the plan drops to Free at period end. |
| POST | /v1/reports/sla | A signed SLA report: recorded uptime telemetry in the verifiable receipt envelope. |
| POST | /v1/evals | Create an eval suite: cases with assertions against a model. |
| GET | /v1/evals | List eval suites. |
| DELETE | /v1/evals/:id | Delete an eval suite. |
| POST | /v1/evals/:id/run | Run the suite against its model (real, metered inference); returns pass rate and regression flag. |
| GET | /v1/evals/:id/runs | Run history with pass rate over time. |
| POST | /v1/webhooks | Create a webhook; secret returned once. |
| GET | /v1/webhooks | List webhooks. |
| DELETE | /v1/webhooks/:id | Disable a webhook. |
| GET | /v1/webhooks/:id/deliveries | Last 50 delivery attempts. |
| POST | /v1/webhooks/:id/test | Fire a synthetic webhook_test event at this webhook. |
| GET | /v1/auth/me | The {account_id, wallet_address} for the bearer session. |
| POST | /v1/auth/logout | Invalidate the current session. |
| GET | /v1/auth/sessions | List the account's live sessions. |
| POST | /v1/auth/logout-all | Invalidate every session (the leaked-token remedy). |
| GET | /v1/auth/wallets | List wallets linked to the account. |
| POST | /v1/auth/wallets | Link an additional wallet (SIWE proof of the new wallet). |
| DELETE | /v1/auth/wallets/:addr | Unlink a wallet. Refuses the last one. |
| POST | /v1/vault/assets | Register a private vault asset; sensitive fields sealed at rest. |
| GET | /v1/vault/assets | List the caller's assets. |
| GET | /v1/vault/assets/:id | Asset detail plus its hash chain. |
| GET | /v1/vault/assets/:id/holders | Issuer-only cap table: every holder and decrypted position. |
| POST | /v1/vault/assets/:id/close | Issuer-only, irreversible: chains asset_closed; transfers refuse thereafter. |
| POST | /v1/vault/assets/:id/distribute | Issuer-only: record a pro-rata payout to holders. Does not move principal. |
| POST | /v1/vault/assets/:id/nav | Record a NAV or reserves attestation and return a signed proof. |
| POST | /v1/vault/assets/:id/view-grant | Mint a scoped view key for an asset. |
| GET | /v1/vault/assets/:id/view-grants | List an asset's view grants. |
| DELETE | /v1/vault/view-grants/:id | Revoke a view grant. |
| GET | /v1/vault/portfolio | Decrypted-for-owner totals and recent activity. |
| GET | /v1/vault/distributions | Distribution history. |
| POST | /v1/vault/transfers | Private, value-conserving position transfer to another account's wallet. |
| GET | /v1/vault/transfers | Transfer history. |
| POST | /v1/vault/proofs | Mint a signed selective-disclosure statement, verifiable via /v1/receipts/verify. |
| POST | /v1/nodes/enroll | Enroll a fleet node under the account; one-time nk-sable_ key reveal. See node agent contract. |
| POST | /v1/nodes/:id/:gate | Owner gate: :gate is disabled or draining, body {set: bool}. |
Admin
Bearer $SABLE_ADMIN_TOKEN. The whole group is unmounted and returns 404
when no admin token is configured; a wrong token returns 401.
| Method | Path | Notes |
|---|---|---|
| GET | /v1/admin/metrics | Demand-gate numbers: paying accounts, spend by window, events by kind, and billing_enforced. |
| POST | /v1/admin/accounts/suspend | The abuse kill switch. Body {account_id, suspended, reason}. |
| POST | /v1/admin/denylist | Refuse one reported payload by its full sha256. Stores no content. |
| POST | /v1/admin/nodes/enroll | Enroll a house node under the dedicated house-ops account. |