developers

Base URL

One URL serves every client. The dialect is read from each request.

export OPENAI_BASE_URL="https://api.superbot.gg/v1"
export OPENAI_API_KEY="sbc_…"
export ANTHROPIC_BASE_URL="https://api.superbot.gg/v1"
export ANTHROPIC_API_KEY="sbc_…"

Auth and scopes

Mint a caller key on the account page. The format is GitHub’s: sbc_, then 32 base64url characters, _ and 6 checksum characters, so a typo dies before the hash lookup. Send it as Authorization: Bearer sbc_… (any client’s default) or x-api-key: sbc_…. The API returns the plaintext once, at mint; the api console can copy a key minted since 2026-10-05 again from its Endpoint card, so roll an older key.

There are two kinds of key: a caller key (sbc_), which holds only the scopes you mint it with, and the one account key (sbk_), which covers the whole account; the model routes take a caller key and refuse the account key. The account key is not narrowed by scopes, and rotating it on the account page stops every client that uses the old key.

Every key carries a route (byo, credits or auto) and a mode (model or agent), and a request can override both:

curl -H "x-superbot-route: byo" -H "x-superbot-mode: agent" \
  -H "x-superbot-session: my-thread" -H "x-superbot-engine: omni" \
  "$ANTHROPIC_BASE_URL/messages" …

Route byo is served by the account’s own linked provider logins, the ChatGPT, Claude or Grok subscription connected on the account page, and is not billed to credits. Those logins are the account holder’s personal vendor subscriptions, not a commercial API allocation. The vendor terms that govern them (OpenAI’s, Anthropic’s, xAI’s) cover personal use, not resale or serving third parties. A byo key handed to someone else spends the key owner’s subscription under terms that were not written for it. Point other people at credits, which serves the operator’s own metered allocation and bills per token, and keep byo for the account’s own clients and machines.

Set model: "superbot" for the agent: your whole superbot (skills, rules, MCP entries, device tools) through a plain client. That is for when no Helper is running, so a phone gets the full agent too, and tool activity streams as status lines.

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.

Set model: "superbot-omni": Superbot agent, run on your computer. Or keep the default model and send x-superbot-engine: omni on an agent call. Only omni is settable by a caller key: a caller key that sends any other x-superbot-engine value is ignored, not refused.

Scopes

Each key holds scopes, and an operation names the ones it needs; a key without one answers 403 insufficient_scope. Mint with one of three presets: Models, Read-only query or Full access. A key minted before scopes existed holds the Gateway preset, and a signed-in session is not narrowed by scopes.

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.

Pagination

List routes take limit (1 to 100, default 20) with after_id or before_id. A page is {"object": "list", "data", "has_more", "first_id", "last_id"}. The Link: rel="next" header names the next page.

Errors

Account routes refuse with one envelope: error (the code below), message, doc_url (this table’s row) and request_id, plus param when one field is at fault. The gateway routes refuse in your dialect, OpenAI’s error.type/message envelope or Anthropic’s type: error one. They also answer 402 when the key’s budget or credits are spent (byo_url on the body). They answer 499 when the caller hung up (the agent turn keeps running). They answer 5xx with the upstream's own status, passed through in your dialect. A 502 or 504 that Superbot itself answers to a call made with a caller key or the account key reaches you as 503, the body unchanged, with x-superbot-origin-status naming the 502 or 504 it was (the CDN in front of the API replaces the body of a 502 or 504 and passes a 503). A provider's own status and the model router's own typed error keep theirs. When a status is your own vendor credential's answer (a BYO or custom-endpoint dial) the response also carries the header x-superbot-error-origin: vendor and origin: "vendor" with vendor_status inside the error object; 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), client (your client's key or setup), account (credits, plan or limits), superbot or model_server (ours: retry), or provider (an account you connected).

Rate limits

1200 requests/min per key, in a fixed-minute bucket, with x-ratelimit-remaining and x-ratelimit-reset on the 429. A keyed request is not counted against any per-IP bucket. Each key also carries its own daily and monthly token budgets.

Spend is metered per key on every dial, and the answer rows carry key_id and key_label. Incognito keys flag their rows (properties: {"incognito": true}) and skip the prompt and reply text.

Withheld

A caller key does what its scopes allow and nothing more. Minting keys and editing endpoints, teams and devices each need their write scope. A team key never holds more than gateway:invoke, usage:read, billing:read and teams:read. No scope unlocks these:

• Vault material: a secret only ever leaves through a dial to the vendor it belongs to.
• Billing changes: no top-up, no auto-recharge settings, no plan changes.
• Account and session management: no sign-in, no device pairing, no account deletion.
• Adapter registry and miss-queue writes.
• Control-socket methods and rooms administration.

Reference

Every operation, generated from the OpenAPI document. Each group has its own page, and every operation links its reference as markdown.

Machine docs

Every page here has a markdown twin: add .md to its path.

• /docs/openapi.json: OpenAPI 3.1, the canonical description.
• /docs/openapi-3.2.json: the same as OpenAPI 3.2.
• /docs/llms.txt: the API index for agents.
• /docs/llms-full.txt: every operation as one markdown file.
• /.well-known/api-catalog: the RFC 9727 catalog.