Docs

Which surface to use

Match the job to a row. The Auth column is what you send.

MCP endpoints

Three endpoints, one per job. Each takes its own auth.

The superbot tool

The skills CLI installs the superbot skill: npx skills add https://superbot.gg. Once it is installed, a user can say use superbot, and the agent calls superbot with the rest of the request.

Link install

Mint an install code with POST https://superbot.gg/mcp/install. Name the client with client= in the query, a JSON body or a form body. Values: claude-code, codex, gemini-cli, cursor, vscode, cline, zed, windsurf, other. An unknown value is other.

curl -X POST 'https://superbot.gg/mcp/install?client=claude-code'

Over a rate limit, the call answers 429 rate_limited with retry_after, limit and a Retry-After header. Too many pending installs answer 503 temporarily_unavailable with retry_after.

Your own MCP tools

• Methods: initialize, ping, tools/list and tools/call, as JSON-RPC 2.0.
• Auth: a caller key with mcp:invoke. A key without the scope answers 403 insufficient_scope. An account key sbk_… is accepted. A session or device token answers 403 caller_key_required. No key answers 401 unauthorized with a WWW-Authenticate: Bearer header.
• Names: <server>__<tool>. Servers named hub or superbot are never served.
• Limits: 120 tools/call a minute per key, and 8 running at once per user. Over either limit: 429 rate_limited with retry_after and a Retry-After header.
• Refusal codes for a tools/call: remote_mcp_off (the switch is off), device_offline (no paired device is online) and unknown_tool. The call answers as an error result (isError: true).
• Switch: relay app, MCP page, "Your tools, remotely", "Allow remote MCP tools". See Your own MCP tools, remotely.

curl -X POST https://api.superbot.gg/v1/mcp \
  -H "Authorization: Bearer sbc_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Agent tools on this computer

Served at http://127.0.0.1:18787/mcp with a relay key or account key sbk_…. A caller key sbc_… answers 403 caller_key_forbidden. Mounted in the agent sessions the Helper runs: its own agent, the Claude Agent SDK, Codex, and Cursor and Claude over ACP.

Local relay API

The Helper serves the local base URL from this computer.

• Base URL: http://127.0.0.1:18787/v1. Default port: 18787. Read the port on the relay app's Overview page, in the Endpoint card with Local picked, on the Base URL row.
• Routes: POST /v1/messages, POST /v1/messages/count_tokens, POST /v1/chat/completions, POST /v1/responses.
• Sign-ins served: Claude, ChatGPT, Gemini, Grok, Muse Code, Kimi Code and GLM Coding Plan. Each answers in either API: a Claude model answers POST /v1/chat/completions, and a GPT model answers POST /v1/messages.
• No key: GET /v1/models, GET /health.
• Key required: GET /v1/keys/whoami, every other /v1/* route, and /mcp.
• Accepted keys:
  • relay key sk-superbot-…, sent as Authorization: Bearer or x-api-key;
  • caller key sbc_… and account key sbk_…;
  • saved Anthropic or OpenAI provider key, on its own vendor's routes only. Other routes answer 403 provider_key_wrong_vendor.
• Relay switched off (the Relay switch in the superbot relay card on the relay app's Overview page): every /v1 route answers 503 relay_off to every key; /health and /mcp keep answering.
• Relay key mint: the Helper mints a relay key on its first run and prints it. superbot clients wire [client] routes a client: it reuses that client's live relay key or mints one, and writes the local base URL and key into the client's config.
• Caller key mint: superbot keys mint <name> and the relay app's Remote API page, Mint new key, mint caller keys sbc_… on your account. The raw key shows once. A caller key works on the hosted base and on the local base URL. The Remote API key is an agent key: its tools run on this computer, and the edge picks who pays. The CLI takes --mode and --route; without them the edge's defaults apply.
• Failover between your sign-ins: the relay answers from your own vendor sign-ins, pooled per vendor. On 401 or 403 that sign-in is re-minted and the call moves to a sibling. On 429 it moves too. Each request makes at most 3 attempts, or one per sign-in when the vendor's pool holds more, up to 8.
• Bare model: superbot or auto. Chat goes to superbot-omni. Code goes to Claude Code's default model on the Anthropic plan.
• Own keys in connected apps: when the Helper wires an app, a key already in that app's config is kept and registered as a seat. Shapes: sk-ant-… (Anthropic), and sk-…, sk-proj-…, sk-svcacct-… or sk-admin-… (OpenAI). Not adopted: sk-ant-oat… (Anthropic OAuth tokens), sk-or-…, AIza… and xai-….
• Extra listen addresses: relay app, Overview, Endpoint card, Also listen on, Add address. Host: an IPv4 address. Port: 1024 to 65535. 0.0.0.0 needs allow-all.
• On an extra address: the Host header must equal that IPv4 (else 421 host_not_allowed); every route needs a key; lane keys answer 403 lane_key_loopback_only; the Origin header must be on the allow-list; the /v1 routes and /mcp are served.

curl http://127.0.0.1:18787/v1/chat/completions \
  -H "Authorization: Bearer sk-superbot-…" \
  -H "Content-Type: application/json" \
  -d '{"model": "superbot", "messages": [{"role": "user", "content": "Summarize this thread."}]}'

Secret references

• Form: {{secret:<id>}}, or {{secret:<id>.<field>}} with password, secret or value as the field.
• The <id> is a custody row id, written kind:adapter.
• A reference expands only after the user approves the call.
• The first use of a credential in a session raises one consent card. An Allow holds for the rest of that session.
• A secret never expands into a file inside a git work tree. That call is refused.
• Output values are scrubbed to [redacted].

Shell-safety switches

• Location: Settings > Advanced, Relay group.
• Sandbox agent shell commands: writes stay in the project and temp. On Windows, the row says macOS and Linux only.
• Guard shell prompts and sudo: asks before sudo runs.
• Both are off by default.
• An agent cannot set either one. hub__settings_set refuses both, true or false.

Discovery and access

Discovery documents

Sign-in and access answers

Built-in tools

Every agent starts with the same tools, so one ask can research a topic and hand back a finished file.

• Web search and page reading, with a browser for pages that need JavaScript and web archives for pages that are gone.
• Research searches scholarly papers and code repositories, and writes a cited report.
• Files builds a spreadsheet with live formulas, a document, a deck or a PDF.
• Media makes pictures, video, audio and 3D models from a description.
• Browser and screen works sites you are signed into and, when you allow it, any app on your screen.

Related: Your browser and your screen, Pictures, video, audio and 3D

Browser sessions and logins

Your agent works the sites you are signed into, using sessions the Helper reads from your own browsers.

1. Sign in to the site in your browser.
2. Ask your agent to use the site. The Helper reads your browsers only after you allow it. On a Mac it reads Chrome, Brave, Edge, Arc, Vivaldi, Firefox and Safari.
3. To import one site yourself, run superbot cookies <domain>. Add --dry-run to write nothing or --yes to skip the prompt.

Saved logins import from your browsers and from 1Password, Bitwarden, LastPass and KeePass. To switch a read off, open Settings > Privacy and use Browser sign-ins or Passwords and SSH keys under What Superbot can read on this computer (this Mac on a Mac).

Your browser and your screen

Your agent browses websites for you, for example to order food, and with your permission works any app on your screen.

On the desktop, the chip in the Browser pane's address bar picks where agent pages open: Cloud, or This Mac (This computer on Windows). My IP sends the cloud browser's traffic out through your computer's connection, so sites see your own address.

Computer use works on Mac and Windows and has three settings. Off never touches your screen, Ask asks before each action, and Always acts without asking. It starts at Off.

1. Press the computer use toggle in the composer to move through Off, Ask and Always.
2. On a Mac, the first time, Turn on computer use asks for Accessibility to click and type and Screen Recording to take screenshots. On Windows, there is no system permission to grant: the first screen action shows the inline Allow card instead.

When it is Off and a task needs your screen, the agent asks Turn on computer use: <reason>. Choose Allow in this chat, Always allow or Not now.

Related: Download superbot

Live view and remote control

From another device, you watch the screen of the device that did your task and take its controls.

1. From one device, ask another to do something, for example from your phone to your computer. The reply shows a tile with Watch live.
2. Press Watch live. The other device opens as live video.
3. Choose Observe to watch or Control to click and type. End closes the viewer.

The viewed computer shows a banner naming the device, with Stop Sharing. To change what it allows, open Settings > Privacy and find the Live view group:

• Let your other devices view and control this computer turns Live view on or off. It is on by default.
• Require approval on this computer asks on this computer before another device can view or control it. It is off by default.

A device you have not allowed opens view only. Press Allow on the viewed computer, then reconnect to take control. A device added to your account in the last 24 hours starts this way.

Pictures, video, audio and 3D

superbot makes pictures, video, audio and 3D models on its own account, so you connect nothing first.

• Pictures appear in the chat, from a description.
• Video is a short clip, from a description or a picture.
• Audio is a song, a sound effect or a spoken voice line.
• 3D is a model file, from a description or a picture.

On superbot's account each result costs credits, and each kind has a daily limit.

A sign-in or key of your own is used first when you have connected one, and it spends no credits: your ChatGPT plan or your OpenAI, Gemini or Grok key for pictures, your OpenRouter, Google or xAI key for video, and your OpenAI or Gemini key for audio. A ChatGPT Free plan cannot make images, so superbot tries your key next.

Every result says which account paid. When your own sign-in or key could not be used, it says why.

Connect accounts in Settings > Subscriptions & keys. On the phone, open Settings > Connections.

Related: Credits

Calls and texts from your phone

Your agent calls and texts people from your own iPhone number, and a text to superbot's own number gets its answer back as a text.

This needs a Mac with the Helper running, an iPhone paired to it, and Messages signed in to your Apple Account on the Mac.

1. Open Settings > Voice. At the bottom, under Phone line, the chip reads Calls and texts from your iPhone when setup is done.
2. Finish the setup it lists: Allow Messages, then Open Full Disk Access. For calls, also choose Superbot Call Mic as the microphone in Phone.
3. Ask: "call the dentist and ask for the first free slot".

Every call and text asks you first. If Phone.app needs it, you tap Call once on your Mac. The same number is called at most once in 24 hours. Open calls… under Phone line lists what your agent made.

To text superbot, text its number: the Text Superbot card under Phone line on Settings > Voice shows Text <number> to link a phone. On the phone, open Settings, then Connections, and under Phone line open Text Superbot.

Related: Text Superbot, Endpoints

Text Superbot by SMS

Superbot answers questions and runs tasks over SMS. Text its number from any phone to start.

• Text +14157180220 from any phone. No purchase or app install is required.
• Your first text is your opt-in. Superbot texts you back.
• Link a Superbot account by SMS, and you get a one-time confirmation text.
• Reply STOP to opt out, or HELP for help. Message frequency varies, and message & data rates may apply.

Related: Text Superbot, Calls and texts from your phone

Voice chat and dictation

Talk to an agent and hear it answer, or dictate a message instead of typing it.

Voice chat

1. On the desktop, press Voice in the composer, or choose Start voice chat in the File menu (⌘⇧O on a Mac, Ctrl+Shift+O on Windows). On the phone, press Voice in the composer.
2. Talk. The control shows what is happening, from Listening to Speaking.
3. Press End voice to finish.

To use your own voice, open Settings > Voice, press Record my voice under Your voice, read for up to 60 seconds, tick My voice, or I have permission, then choose My voice. The sample goes to ElevenLabs and the voice is AI-generated.

Dictation

1. Press the microphone in the composer (Click to speak) and talk. It reads Listening. Click to stop.
2. The text lands in the message box, ready to edit.
3. To choose where speech becomes text, open Settings > Voice and set Dictation engine. On this Mac (On this computer on Windows) keeps the audio on it, and Superbot cloud sends it to the speech provider.

Quick Ask

On the desktop, one shortcut opens a small panel from any app that answers about the window you were using.

1. Press Alt+Space (⌥Space on a Mac) from any app, or choose Quick Ask in the File menu.
2. Type your question under Ask anything. A chip shows the app and window you came from.
3. Press Expand to full chat to carry on in the full app. Escape hides the panel and keeps your draft.

Quick Ask attaches a screenshot only when you press Screen snapshot. To change the shortcut, open Settings > Shortcuts and press Record in the Quick Ask group. Restore default goes back.

Build, edit and preview

On the desktop, you run a live copy of what your agent builds and change its files without leaving the app.

1. Press Preview in the project header, beside Publish. The app runs the project on your computer and opens it in the side pane. Stop ends it.
2. Open a project file to edit it. Save writes it, Format formats it, and Diff and File switch the view.
3. For a page or document the agent made in a chat, press Open in pane. In the pane, Edit changes it in place and Done finishes. View code shows the source and Download saves it.

Related: Publish your app, Download superbot

Publish your app

Your app goes online at a free <name>.superbot.sh address on your own Cloudflare account.

This needs a free Cloudflare account. The first time, Connect Cloudflare opens a dialog: press Continue to Cloudflare, sign in, then pick Use this account.

1. Open a project and press Publish in its header.
2. Pick a name. Under Who can open it? choose Anyone or Only people I invite.
3. Press Put it online. Publish checks the app and tests it on your computer first. Later publishes read Update live app.

Once it is live, the Live tab on the project manages it. Versions keeps every publish and Roll back returns to an older one. Domains renames the address or adds your own. Keys stores the secrets your app reads. Remove app, under Take it offline, deletes the app and its data for good.

Type /publish in a chat to have your agent publish the project.

Related: Build, edit and preview, Download superbot

Cloud runs from your phone

Your phone sends a task to a cloud copy of your project, and the files it changes sync back to your computer.

This needs Sync projects across devices on in Settings > Privacy > Projects, and Sync this project on for the project: click the project's name at the top of its page. Both are on by default. If either is off, the phone says Turn on sync to work in the cloud.

1. On the phone, open a chat in the project and press Run in cloud in the thread header.
2. The next time the Helper syncs, the changed files land in your local folder.

On the desktop, press Build in cloud on the plan card. It stays off until the project is linked to a repo, with the reason Link a repo to this project first.

In a repo-linked project, if you edited a file the cloud also changed, yours stays and the cloud's version lands beside it as notes.sync-conflict-20261004-101500-cloud.md.

Related: Download superbot

Phone extras

On iPhone, you start a chat from the home screen or the Action Button, and the Lock Screen shows a running agent.

• Home-screen shortcuts: press and hold the superbot icon for New chat, Ask by voice and Voice chat.
• Action Button: in the iOS Settings app, open Action Button, choose Shortcut, then pick New chat or Start voice chat from superbot.
• Lock Screen and Dynamic Island: show Superbot is working while an agent runs and Waiting for you when it needs you.
• Notifications: in Settings, on Your agent, under General, switch Push when Superbot finishes and Push when Superbot needs you. Both are on by default.
• Offline reading: chats stay readable on the phone without a connection.

Related: Voice chat and dictation, Download superbot

superbot-omni

superbot-omni is superbot's own agent loop: it sends your turn to the model, runs the tools it asks for and repeats until done.

It drives any model behind the OpenAI or Anthropic API with the same tools, including the models on your custom endpoints. To compare two models, pick each in the model picker and send the same task.

Related: Custom endpoints, Models

Teams and policy

A team shares MCP servers, rules and skills across its members and applies one signed policy to every member's devices.

1. Open Account > Teams and press Create team.
2. Under Members, enter an email, pick a role below your own and press Invite.
3. Owners and admins see the Policy and coverage card. It reads a count such as 3 of 5 reported once a policy is published, and marks a member whose devices have not reported as not reported.

An owner or admin publishes the signed policy through the org API. Until then the card reads No policy published yet.

Related: Teams

Usage and spend

See what your agents used and what it cost, for the last 7 days by default.

Open Account > Usage to read it, and pick a longer range there. To cap a caller key, set Daily limit or Monthly limit in credits when you mint it under Account > API. A key that reaches a limit is refused until the window resets.

Related: Keys and authentication, Endpoints

Custom endpoints

Add any OpenAI- or Anthropic-compatible endpoint to the model picker and dial it with your own superbot key beside the house models.

1. Open Settings > Subscriptions & keys and find the Custom endpoints group.
2. Press Add endpoint (Add an endpoint on an empty list).
3. Under Where it is saved, pick Hosted endpoint so every device on your account can dial it, or This Mac (This computer on Windows) to keep it on this computer.
4. On the hosted path, enter a Label, the Base URL and the API key.
5. Set Dialect to Auto, OpenAI or Anthropic, then press Add endpoint.

Models load when the endpoint answers /models, and Refresh models reloads them. Scan for keys, under Found on this Mac (Found on this computer on Windows), finds API keys already on this computer and offers each one as an endpoint. On the phone, open Settings > Connections and choose Custom endpoints.

Related: Models, Keys and authentication

Keys and authentication

A caller key starts with sbc_ and belongs to your account.

Key kinds

Mint a key

1. Open Account > API, find Keys and select New key.
2. Enter a Name of up to 64 characters.
3. Set the fields you need.
4. Select Create key.
5. Copy the key. The page shows it in full only once.

To edit a key, select its row under Keys and change the fields below. To revoke a key, select Revoke on its row under Keys. It stops working immediately.

Key settings

Send a key

The key goes in the Authorization: Bearer header. x-api-key carries the same key for clients that expect it.

curl https://api.superbot.gg/v1/models \
  -H "Authorization: Bearer sbc_…"

No account yet? Make a free account first: there are no trial keys. POST https://api.superbot.gg/v1/keys/trial issues nothing and answers 403 trial_unavailable with the sign-up link in signup_url. A Free account's key calls the API on your own model key or subscription (saved under Providers on Account > API); a call that would run on our house models answers 403 model_plan_gated until the account is on Plus or above, and the paid plans use our models.

Related: Set up your clients, Account

Routing by key

One base URL serves every key. The key sets what answers. Set the base URL and key as shown under Send a message.

What runs per key

Subscription ids run on a Claude Pro/Max, ChatGPT/Codex, Gemini Code Assist or SuperGrok sign-in. Device ids are the ollama/, lmstudio/, omlx/ and openrouter/ ids a live device holds.

Per route

Held means the edge can open a saved sign-in or key for the vendor, a custom endpoint, or a live device that holds the vendor. Nothing held means none of those three.

Per request

• superbot, superbot-omni and superbot-fast always run a full agent turn, whatever x-superbot-mode says.
• A saved provider key ignores both headers and cannot name those three ids (403 model_not_allowed).

Device and list rules

• On byo, a credential only a device can open (a sign-in or key sealed to your devices) answers 403 no_vendor_credential, reason device_required, when no device that can serve it is online. There is no credits fallback on byo.
• On auto, the same credential with no device online goes to credits. With a device online, the call is routed to that device.
• GET /v1/models with the key is the authoritative list of what the account can call. Credits rows carry available; a reason is set when one applies.

Models

GET /v1/models lists every model id the account can call, whether or not the key's Models names it. A saved provider key lists only its vendor's ids. A call to an id the key's Models does not name answers 403 model_not_allowed.

Model ids

Each GET /v1/models row that knows its window carries context_length, with the same value in context_window. Agent ids always carry one.

House models

superbot: Your Superbot agent. Context window: 1M. superbot-omni: Superbot agent, run on your computer. Context window: 1M. superbot-fast: Quick and cheap, for small jobs. Context window: 500k.

Credits per 1M tokens, with dollars beside them; one credit is $0.001. Calls with your API key bill at the API and MCP rate. In the Superbot apps, superbot and superbot-fast both bill at 20% of the API and MCP rate. Neither model is free on either lane. Fast mode bills 2x every rate. Reasoning tokens bill as output.

Effort and Fast

superbot serves the efforts none (no reasoning), low, high, xhigh and max, and runs at high, its default, when the request names none. low reasons less than high, and max reasons the most. superbot-fast runs at low, or none. Send the effort in the request's own field: reasoning_effort, reasoning.effort or output_config.effort. Each level is served as one superbot runs:

Fast serves the turn on the faster tier at twice the price. Ask for it with service_tier: "priority" or "fast", with Anthropic's speed: "fast", or with the header x-sbr-speed: fast. GET /v1/models lists each house model's reasoning_efforts, default_reasoning_effort and service_tiers. Asked in Anthropic's shape (with an anthropic-version header), each house row carries max_input_tokens and capabilities.effort instead, and with ?client_version= the list is Codex's own model catalog.

Other models

Vendor model ids run on your own accounts and keys, or on credits. An endpoint added with Add endpoint under Providers on Account > API appears as custom/<endpoint>/<model>, for example custom/example/llama-3.3-70b.

Related: Custom endpoints, Credits, The API page

Endpoints

Each route links to its reference on /developers.

A scope names what the key must hold. any key takes any live key, and no key answers without one.

Related: Full API reference, OpenAPI 3.1 spec

Send a message

POST /v1/chat/completions takes an OpenAI Chat Completions body, POST /v1/responses an OpenAI Responses body and POST /v1/messages an Anthropic Messages body. Each answers in its own shape.

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_…

curl https://api.superbot.gg/v1/chat/completions \
  -H "Authorization: Bearer sbc_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "superbot",
    "messages": [{"role": "user", "content": "Summarize this thread."}]
  }'

from openai import OpenAI

client = OpenAI(base_url="https://api.superbot.gg/v1", api_key="sbc_…")
response = client.chat.completions.create(
    model="superbot",
    messages=[{"role": "user", "content": "Summarize this thread."}],
)
print(response.choices[0].message.content)

from anthropic import Anthropic

client = Anthropic(base_url="https://api.superbot.gg/v1", api_key="sbc_…")
message = client.messages.create(
    model="superbot",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize this thread."}],
)
print(message.content[0].text)

Streaming

Send "stream": true to any of the three routes to receive server-sent events in that route's own shape.

curl -N https://api.superbot.gg/v1/chat/completions \
  -H "Authorization: Bearer sbc_…" \
  -H "Content-Type: application/json" \
  -d '{"model": "superbot", "stream": true, "messages": [{"role": "user", "content": "Summarize this thread."}]}'

• Chat Completions sends data: {"choices":[…]} frames and ends with data: [DONE].
• Responses sends typed events such as response.output_text.delta and ends with response.completed.
• Messages sends Anthropic's events, from message_start to message_stop.

Usage and billing settle when the stream ends, and an aborted stream is billed for what it produced.

Long answers without streaming

A non-streamed call whose answer takes more than 30 seconds gets its 200 and content-type: application/json headers early, then a newline every 15 seconds until the JSON body follows. Any JSON parser skips that leading whitespace. If the call fails after those headers went out, the status stays 200 and the body is the route's error object ({"error": {…}}, or {"type": "error", "error": {…}} on Messages). Send "stream": true for long turns.

Limits and errors

Rate limit

A caller key gets 1200 requests a minute. Over that, the route answers 429 before any model is called, with this body:

{
  "error": {
    "message": "per-key rate limit reached",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_error",
    "retry_after": 12,
    "source": "account"
  }
}

That is the Chat Completions and Responses body. On Messages the same refusal comes in Anthropic's envelope: {"type": "error", "error": {"type": "rate_limit_error", "message": "per-key rate limit reached", "retry_after": 12, "source": "account"}}. retry_after is in seconds. source: account says the limit is your key's own. The x-ratelimit-remaining and x-ratelimit-reset headers carry the same window.

Errors

Model routes answer in the caller's dialect, and the Field column says where each code sits. A top-level error is a string code. Account routes answer in that form too, with message, doc_url and request_id beside it. The two refusals of a body Superbot cannot take, 413 and 415, are flat bodies with the code at the top level, in code.

An error object can carry machine members beside message and code. They only add: a client that does not know a member ignores it, and a member never changes the status, error.type, error.code or message of the refusal.

• error.source says whose side the problem is on: request (the request or conversation itself), client (your key, API shape or headers), account (your credits, plan, limits or saved keys), superbot (Superbot itself failed; a retry may help), model_server (Superbot's model service is down, overloaded or answered nothing) or provider (a provider you connected refused or failed). The set can grow, so ignore a value you do not know.
• error.fix names the step that clears the refusal. On unknown_model it is pick_listed_model: error.models_path is /v1/models, and error.accepted_models lists up to three ids the key can call, never the one you sent. A key with no other id to offer gets no accepted_models.
• The 415 carries fix: resend_supported_encoding at the top level, with supported_encodings listing the encodings Superbot decodes: gzip, x-gzip, deflate, br and, where the server supports it, zstd.

A provider's own error passes through with the provider's status, marked by the x-superbot-error-origin: vendor header.

Out of credit

When the account behind a caller key has no credit left, the call answers HTTP 402 with the header x-superbot-error: insufficient_balance. The body is in the dialect of the route you called. Its error.message is two lines: a sentence that says what to do (for a credit-out, the billing page to add credits), then the status, code and billing reason in parentheses.

OpenAI routes (/v1/chat/completions, /v1/responses):

{
  "error": {
    "message": "Your Superbot account has no plan or credits left. Add credits at https://superbot.gg/account/billing\n(402 insufficient_balance · no_plan)",
    "type": "invalid_request_error",
    "param": null,
    "code": "insufficient_balance",
    "refusal_class": "credit_out",
    "source": "account"
  }
}

Anthropic routes (/v1/messages):

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Your Superbot account has no plan or credits left. Add credits at https://superbot.gg/account/billing\n(402 insufficient_balance · no_plan)",
    "code": "insufficient_balance",
    "refusal_class": "credit_out",
    "source": "account"
  }
}

error.code is insufficient_balance for every refusal that comes from the account's credit or spend limits, so it is the one code to branch on. error.refusal_class says which refusal it is, and error.source is account: the refusal comes from your account.

https://superbot.gg/account/billing is the page to add credits. All the top-up, subscribe, recharge and manage links name this one page. The link is not signed and does not expire: you sign in on the web to use it, and a pack or plan button on that page asks how you want to pay: Card opens Stripe Checkout directly, and Crypto leads to a crypto invoice at 5% off the price before tax. On GET /v1/plans, a paid plan's subscribe_url is the same page with ?plan= and the plan id on it.

A refusal that is not a credit-out keeps this body: only error.message and error.refusal_class change, and a pending top-up and a suspension name no billing page in the message. Superbot's own apps, signed in as the account, get a richer body with plan and balance fields.

The billing reason is one of these:

Related: Credits, Plans and packs

Credits

superbot bills in credits: one credit is $0.001. Each token type is priced as a multiple of the input rate (on superbot: output counted at 5x, cache reads at 0.05x and cache writes at 1.25x). A vendor model called on credits, with none of your own accounts attached, costs its own list price. Models on your own subscriptions and keys spend no credits. Credits are held and charged by the billing service behind superbot: the balance, the plan and every charge are its records, and the app and the API show what it reports.

Read your balance

GET /v1/credits returns the balance as balance_credits, with the pots in credits, and the plan and auto-recharge state. balance_credits is the credit any model can spend; a plan's house allowance, spendable only on superbot and superbot-fast, is listed apart as credits.house and as a house row of grants, which names those models. It needs the billing:read scope, which Models and Read-only query keys hold. low is true when balance_credits is zero or less, so an account holding only the house allowance is low: its Superbot models still run. reason appears with it. The route reads the balance from billing and holds none itself, so while billing cannot be reached it answers 503 billing_unavailable with a retry hint.

curl https://api.superbot.gg/v1/credits \
  -H "Authorization: Bearer sbc_…"

Related: Models, The API page

Plans and packs

• Free costs nothing and carries 10,000 beta credits a month, refilled on the 1st (UTC). Cloud computer · 5 h/mo.
• Superbot Plus is $20 a month with 22,000 credits included for any model and 250M non-cached Superbot tokens a month at 3:1 input to output, or $200 a year. Cloud computer · 20 h/mo.
• Pro is $100 a month with 120,000 credits included for any model and 1.5B non-cached Superbot tokens a month at 3:1 input to output, or $960 a year. Cloud computer · 100 h/mo.
• Max is $200 a month with 270,000 credits included for any model and 4B non-cached Superbot tokens a month at 3:1 input to output, or $1,920 a year. Cloud computer · 300 h/mo.
• Superbot Teams is $24 a seat a month, or $228 a seat a year, with 20,000 credits a seat a month for any model and 250M non-cached Superbot tokens a seat a month at 3:1 input to output, pooled across the team. Cloud computer · 20 h/mo a seat.

Every paid plan also sells a yearly term at the yearly price, and a yearly plan still releases its allowance monthly. Any account can start a 7-day Superbot Pro trial at checkout: it takes a card, charges nothing during the trial, gives a one-time 20,000-credit grant that expires when the trial ends, and cancels when it ends unless you continue; an account gets one trial ever. Past the allowance, Plus, Teams and Teams Premium bill $1.00 per 1,000 credits, Pro $0.90 and Max $0.80.

Every model is available on every plan.

A plan's scheduled runs are its automation runs, on a cron or an interval.

Packs are one-time purchases: 5,000 credits for $5, 20,000 for $20, 100,000 for $100, 275,000 for $250, 600,000 for $500, 1,250,000 for $1,000. A pack's credits never expire, and a plan does not reprice the $5/$20/$100/$250/$500/$1,000 packs. Plans and packs are bought on the billing page. Account > Billing opens it, and so does the topup_url or subscribe_url of a 402 or of GET /v1/credits: each opens that same page, which asks you to sign in if you are not already. A pack or plan button on it asks how you want to pay: Card opens Stripe Checkout directly, and Crypto leads to a crypto invoice at 5% off the price before tax.

Auto-recharge

Auto-recharge charges your card for more credits when the balance falls to a level you set. It is off until you turn it on, then $20 per charge, capped at $100 per calendar month. Declined charges count toward the monthly limit. GET /v1/credits reports its state as auto_recharge, and the reason of a 402 says when it is off, capped or failed.

Related: Usage and spend

Which credits are spent first

Superbot models (superbot and superbot-fast) spend in this order: beta credits, the house allowance, plan allowance, promo credits, auto-recharge credits, packs. Every other model skips the house allowance, which only Superbot models can spend. Beta credits refill on the 1st (UTC); the house and plan allowances reset at renewal; none of the three rolls over. Packs and auto-recharge credits never expire.

Troubleshooting

Fixes for what goes wrong after you install the Helper.

If superbot seems down, check status.superbot.gg.

My AI client does not show superbot

Restart the client. If it still lists no superbot tool, add the server again with its recipe under Your AI clients.

superbot: command not found

Paste the activation line the installer printed at the end. In sh, bash and zsh it is export PATH="$HOME/.superbot/bin:$PATH".

The installer did not sign me in

Run superbot signin. It opens your browser to sign in.

My caller key is refused

A 401 means the key is missing or malformed, and a 403 means it was revoked or does not allow that model. Mint a new key in Keys and authentication.

Related: Your AI clients

Remote SSH projects

A project on an SSH host keeps its files, terminal and agents on that box.

Click + and pick Connect to an SSH host, then choose a host or type user@host.

The chat shows a connection error

• SSH sign-in failed: enter the password, or add your key to ssh-agent or pick one for this host.
• Host key rejected: the box's host key differs from the one you accepted. Check the fingerprint, then retry.
• Box unreachable: the box did not answer. Check that it is on and reachable from your computer.
• Box platform unsupported: the box needs Linux with glibc 2.28 or newer, or macOS, on x64 or arm64. Alpine and other musl Linux do not work.
• Box has no internet: the box cannot download the Helper. Send from this computer (Send from this Mac on a Mac) copies it over.
• Port forwarding blocked: allow AllowTcpForwarding in sshd_config on the box, then retry.
• Login shell prints output: stop the shell profile or login banner from printing on connect, then retry.
• Engine missing on box: Reinstall puts the engine back.
• OpenSSH too old: update OpenSSH on your computer to 8.7 or newer, then retry.

Uninstall

superbot uninstall deletes superbot and everything it left on your machine: the Helper, the desktop app and its data, superbot's own entries in your AI clients, and your local accounts, chats and keys.

You sign in again after a reinstall. superbot uninstall --dry-run lists what would go and deletes nothing. A script with no terminal has to pass --yes.

To remove one client by hand, run claude mcp remove superbot for Claude Code, or delete the superbot entry from that client's config file. Nothing else was installed.

Related: Your AI clients

More ways to read this

This documentation in the formats other tools read.

• llms.txt: every install recipe and the MCP endpoint, as an agent reads it.
• docs.md: this page as markdown.
• clients: the per-client setup pages.
• api: the full rate card and the request formats.
• for teams: teams, spend, custom builds and pricing.
• request a client: one that is not on the list yet.