# Superbot API

> One OpenAI- and Anthropic-compatible gateway, plus the account behind it: scoped caller keys, custom endpoints, usage and spend, teams and devices.

Base URL: `https://api.superbot.gg/v1` for OpenAI- and Anthropic-compatible clients alike; set OPENAI_BASE_URL and ANTHROPIC_BASE_URL to it. The dialect is read from each request, and answers come back in the dialect you dialed. Set `model: "superbot"` to run your agent; `superbot-omni`: Superbot agent, run on your computer.

A request that declares its own tools, the way Codex, Claude Code and Cursor do, is answered by the superbot model driving those tools: its tool calls come back in your dialect for your client to run. So is a call that caps its reply at 512 tokens or fewer, and a call that asks for structured output (a JSON object or a JSON schema), whose reply is the model’s output alone. Any other request is answered by your agent, and outside superbot’s own apps a card it draws comes back as plain markdown: a choice as a list, sources as a Sources: list. Send `x-superbot-mode: agent` to have your agent answer whatever the request carries; its cards then arrive as cards, not converted to plain markdown.

Auth: a caller key (`sbc_…`) goes in `Authorization: Bearer sbc_…` or `x-api-key: sbc_…`. Each key holds scopes; an operation lists the scopes it needs, and a key without one answers 403 `insufficient_scope`. Account routes also take a signed-in session.

Headers: x-superbot-route (byo, credits or auto), x-superbot-mode (model or agent), x-superbot-engine (omni, the only engine a caller key may pin), x-superbot-session (names the conversation; 1-59 word chars).

Conversations: When your agent answers a call, superbot keeps its memory of the chat on the server, one thread per conversation. A call answered by the model alone, such as one that declares its own tools, keeps no such thread: the messages your client sends are the conversation. Name a conversation with the `x-superbot-session: <id>` header: letters, digits, `_` and `-`, at most 59 characters. Every call that sends the same id continues the same thread, even when your client does not resend the earlier messages. With no header, superbot reads the conversation id your client already sends: `prompt_cache_key`, `metadata.session_id`, `metadata.conversation_id`, a Responses `conversation` or an Anthropic `metadata.user_id`. Codex and Claude Code send these themselves, so the agent keeps each of their chats apart. With none of them, superbot keys the conversation on its first message, the first one the user wrote and not the reminder blocks a client wraps around it, so two chats that open with the same words share a thread. Name a session when that matters. The OpenAI `user` field is not a conversation id, and neither is a Responses `previous_response_id`. A call that sends `x-superbot-mode: agent` is treated as one of superbot’s own apps: it reads only the header, and without one it shares a single thread per key.

Errors: every account-route refusal is `{"error", "message", "doc_url", "request_id"}` plus `param` when one field is at fault. Gateway refusals come in your dialect. Status: 400 invalid request; 401 unknown key; 402 budget or credits spent (`byo_url` on the body; a credit refusal’s `error.message` names the billing page to add credits); 403 revoked key, insufficient_scope, model_not_allowed, no_vendor_credential, no_custom_upstream; 404 unknown resource; 409 conflicting state; 429 per-key bucket; 499 caller gone; 5xx the upstream’s own status, passed through in your dialect, except that a 502 or 504 Superbot itself answers to a call made with a caller key or the account key reaches you as 503 with the same body and the header `x-superbot-origin-status` naming the 502 or 504 (the CDN in front of the API replaces the body of a 502 or 504, never a 503); a provider’s own status and the model router’s own typed error keep theirs. When that status is your OWN vendor credential’s answer (a BYO or custom-endpoint dial), the response also carries `x-superbot-error-origin: vendor` and `error.origin: "vendor"` with `error.vendor_status` (the vendor’s status); a refusal without them is the gateway’s own. Every gateway error object also carries `error.source`, where the problem is: `request` (your request or conversation, e.g. too long for the model: shorten or compact it), `client` (your client’s key or setup), `account` (credits, plan or limits), `superbot` or `model_server` (ours: retry), `provider` (an account you connected). Match on `code`, `type` and `source`, not on `message`.

Lists: `limit` (1-100, default 20) with `after_id` or `before_id`; the page is `{"object": "list", "data", "has_more", "first_id", "last_id"}`, and `Link: rel="next"` names the next page.

Keys: a caller key (`sbc_…`) holds only the scopes you mint it with. The one account key (`sbk_…`) covers the whole account; the model routes take a caller key and refuse the account key.
No key yet: [auth.md](https://superbot.gg/auth.md) signs a user in with one emailed code and hands an agent an `sbk_…` token. The token works on `/mcp` and `/answer`; the same guide shows the one request that mints the caller key the `/v1` model routes take.

MCP endpoints: `/mcp` on this origin is the one-tool superbot connector, signed in with OAuth or an `mcp_` connector key.
`/v1/mcp` on this origin serves your own relay MCP tools over JSON-RPC. It takes the `sbk_…` key, or a caller key that holds `mcp:invoke`. It is not in the OpenAPI document.

## Reference

- [OpenAPI 3.1](https://superbot.gg/docs/openapi.json): the canonical machine description of every operation below
- [OpenAPI 3.2](https://superbot.gg/docs/openapi-3.2.json): the same operations with nested navigation tags and streamed-event schemas
- [API catalog](https://superbot.gg/.well-known/api-catalog): RFC 9727 linkset naming both descriptions and the docs
- [Developer overview](https://superbot.gg/developers.md): the base URL, keys, rate limits, the error codes and what a caller key can never do

## Gateway

- [Gateway reference](https://superbot.gg/developers/gateway.md): OpenAI- and Anthropic-shaped model calls, answered in the dialect you dialed.
- [Read a turn](https://superbot.gg/developers/gateway/getTurn.md): GET /v1/turns/{session}; scopes turns:read
- [Re-attach to a turn’s stream](https://superbot.gg/developers/gateway/streamTurn.md): GET /v1/turns/{session}/stream; scopes turns:read
- [Create a chat completion](https://superbot.gg/developers/gateway/createChatCompletion.md): POST /v1/chat/completions; scopes gateway:invoke
- [Create a response](https://superbot.gg/developers/gateway/createResponse.md): POST /v1/responses; scopes gateway:invoke
- [Create a message](https://superbot.gg/developers/gateway/createMessage.md): POST /v1/messages; scopes gateway:invoke
- [Estimate input tokens](https://superbot.gg/developers/gateway/countMessageTokens.md): POST /v1/messages/count_tokens; any live key
- [List models](https://superbot.gg/developers/gateway/listModels.md): GET /v1/models; any live key

## Usage & spend

- [Usage & spend reference](https://superbot.gg/developers/usage.md): What your keys and account spent: per request, per day, bucketed and across apps.
- [Get usage over a window](https://superbot.gg/developers/usage/getUsage.md): GET /v1/usage; scopes usage:read
- [List usage per request](https://superbot.gg/developers/usage/listUsageRequests.md): GET /v1/usage/requests; scopes usage:read
- [Get usage per UTC day](https://superbot.gg/developers/usage/getUsageDaily.md): GET /v1/usage/daily; scopes usage:read
- [Get usage bucketed and grouped](https://superbot.gg/developers/usage/getUsageBreakdown.md): GET /v1/usage/breakdown; scopes usage:read
- [Export usage rows](https://superbot.gg/developers/usage/exportUsage.md): GET /v1/usage/export; scopes usage:read
- [Get the credit balance](https://superbot.gg/developers/usage/getCredits.md): GET /v1/credits; scopes billing:read
- [Get AI spend across apps](https://superbot.gg/developers/usage/getSpend.md): GET /v1/spend; scopes usage:read
- [Get a usage report](https://superbot.gg/developers/usage/getUsageReport.md): GET /v1/usage/report; scopes usage:read

## Keys

- [Keys reference](https://superbot.gg/developers/keys.md): Mint, list, edit and revoke scoped caller keys.
- [List caller keys](https://superbot.gg/developers/keys/listKeys.md): GET /v1/keys; scopes keys:read
- [Create a caller key](https://superbot.gg/developers/keys/createKey.md): POST /v1/keys; scopes keys:write
- [Get the calling key](https://superbot.gg/developers/keys/getCurrentKey.md): GET /v1/keys/whoami; any live key
- [Update a caller key](https://superbot.gg/developers/keys/updateKey.md): PATCH /v1/keys/{id}; scopes keys:write
- [Revoke a caller key](https://superbot.gg/developers/keys/revokeKey.md): DELETE /v1/keys/{id}; scopes keys:write
- [Rotate a caller key](https://superbot.gg/developers/keys/rotateKey.md): POST /v1/keys/{id}/rotate; scopes keys:write

## Endpoints

- [Endpoints reference](https://superbot.gg/developers/endpoints.md): Custom OpenAI- or Anthropic-compatible endpoints and @mention aliases.
- [List custom endpoints](https://superbot.gg/developers/endpoints/listUpstreams.md): GET /v1/upstreams; scopes endpoints:read
- [Add a custom endpoint](https://superbot.gg/developers/endpoints/createUpstream.md): POST /v1/upstreams; scopes endpoints:write
- [Update a custom endpoint](https://superbot.gg/developers/endpoints/updateUpstream.md): PATCH /v1/upstreams/{slug}; scopes endpoints:write
- [Remove a custom endpoint](https://superbot.gg/developers/endpoints/deleteUpstream.md): DELETE /v1/upstreams/{slug}; scopes endpoints:write
- [Re-probe a custom endpoint](https://superbot.gg/developers/endpoints/probeUpstream.md): POST /v1/upstreams/{slug}/probe; scopes endpoints:write
- [List @mention aliases](https://superbot.gg/developers/endpoints/listAliases.md): GET /v1/aliases; scopes endpoints:read
- [Set an @mention alias](https://superbot.gg/developers/endpoints/setAlias.md): PUT /v1/aliases/{token}; scopes endpoints:write
- [Delete an @mention alias](https://superbot.gg/developers/endpoints/deleteAlias.md): DELETE /v1/aliases/{token}; scopes endpoints:write
- [Get a service’s OpenAPI document](https://superbot.gg/developers/endpoints/getServiceDocument.md): GET /docs/services/{service_id}.json; no credential

## Teams

- [Teams reference](https://superbot.gg/developers/teams.md): Teams, their members and their invites.
- [Export a team’s audit log](https://superbot.gg/developers/teams/exportTeamAuditLog.md): GET /v1/org/{id}/audit; scopes teams:read
- [List teams](https://superbot.gg/developers/teams/listTeams.md): GET /v1/teams; scopes teams:read
- [Create a team](https://superbot.gg/developers/teams/createTeam.md): POST /v1/teams; scopes teams:write
- [Get a team](https://superbot.gg/developers/teams/getTeam.md): GET /v1/teams/{team_id}; scopes teams:read
- [Update a team](https://superbot.gg/developers/teams/updateTeam.md): PATCH /v1/teams/{team_id}; scopes teams:write
- [Delete a team](https://superbot.gg/developers/teams/deleteTeam.md): DELETE /v1/teams/{team_id}; scopes teams:write
- [List team members](https://superbot.gg/developers/teams/listTeamMembers.md): GET /v1/teams/{team_id}/members; scopes teams:read
- [Change a member’s role](https://superbot.gg/developers/teams/updateTeamMember.md): PATCH /v1/teams/{team_id}/members/{user_id}; scopes teams:write
- [Remove a team member](https://superbot.gg/developers/teams/removeTeamMember.md): DELETE /v1/teams/{team_id}/members/{user_id}; scopes teams:write
- [List pending team invites](https://superbot.gg/developers/teams/listTeamInvites.md): GET /v1/teams/{team_id}/invites; scopes teams:read
- [Invite someone to a team](https://superbot.gg/developers/teams/createTeamInvite.md): POST /v1/teams/{team_id}/invites; scopes teams:write
- [Revoke a team invite](https://superbot.gg/developers/teams/revokeTeamInvite.md): DELETE /v1/teams/{team_id}/invites/{code}; scopes teams:write
- [Resend a team invite](https://superbot.gg/developers/teams/resendTeamInvite.md): POST /v1/teams/{team_id}/invites/{code}/resend; scopes teams:write
- [Accept a team invite](https://superbot.gg/developers/teams/acceptTeamInvite.md): POST /v1/team_invites/{code}/accept; scopes teams:write

## Devices

- [Devices reference](https://superbot.gg/developers/devices.md): The devices paired to your account.
- [Run a job on an agent computer](https://superbot.gg/developers/devices/createAgentJob.md): POST /v1/devices/{device_id}/jobs; scopes devices:write
- [Read an agent computer job](https://superbot.gg/developers/devices/getAgentJob.md): GET /v1/devices/{device_id}/jobs/{job_id}; scopes devices:read
- [Stream an agent computer terminal](https://superbot.gg/developers/devices/streamAgentTerminal.md): GET /v1/devices/{device_id}/terminals/{terminal_id}/stream; scopes devices:read
- [Preview an agent computer code](https://superbot.gg/developers/devices/previewAgentPair.md): GET /v1/pair/{user_code}; any live key
- [Approve an agent computer code](https://superbot.gg/developers/devices/approveAgentPair.md): POST /v1/pair/{user_code}/approve; any live key
- [Decline an agent computer code](https://superbot.gg/developers/devices/denyAgentPair.md): POST /v1/pair/{user_code}/deny; any live key
- [List devices](https://superbot.gg/developers/devices/listDevices.md): GET /v1/devices; scopes devices:read
- [Get a device](https://superbot.gg/developers/devices/getDevice.md): GET /v1/devices/{device_id}; scopes devices:read
- [Rename a device](https://superbot.gg/developers/devices/updateDevice.md): PATCH /v1/devices/{device_id}; scopes devices:write
- [Unlink a device](https://superbot.gg/developers/devices/deleteDevice.md): DELETE /v1/devices/{device_id}; scopes devices:write

## Runs

- [Runs reference](https://superbot.gg/developers/runs.md): Cloud agent runs: start one on a project, follow its events, cancel it, and get a signed webhook when it settles.
- [List cloud runs](https://superbot.gg/developers/runs/listRuns.md): GET /v1/runs; scopes runs:read
- [Start a cloud run](https://superbot.gg/developers/runs/createRun.md): POST /v1/runs; scopes runs:write
- [Find the project for a repository](https://superbot.gg/developers/runs/listRunProjects.md): GET /v1/runs/projects; scopes runs:read
- [Get a cloud run](https://superbot.gg/developers/runs/getRun.md): GET /v1/runs/{run_id}; scopes runs:read
- [Follow a run’s events](https://superbot.gg/developers/runs/listRunEvents.md): GET /v1/runs/{run_id}/events; scopes runs:read
- [Cancel a cloud run](https://superbot.gg/developers/runs/cancelRun.md): POST /v1/runs/{run_id}/cancel; scopes runs:write
- [Steer a running cloud run](https://superbot.gg/developers/runs/sendRunMessage.md): POST /v1/runs/{run_id}/messages; scopes runs:write

## Optional

- [Full reference](https://superbot.gg/docs/llms-full.txt): every operation above as one markdown file
- [Client setup](https://superbot.gg/clients.md): the base URL, caller key and model ids each client expects
- [Site index](https://superbot.gg/llms.txt): the rest of the site for agents