One API for every model.
An API key needs an account. Make a free account, then bring your own model key or subscription; the paid plans use our models.
superbot is not affiliated with OpenAI, Anthropic or the makers of the clients named on this page.
Any model on your account
Connect a subscription, a provider API key or a custom endpoint once.
Every model it carries answers at this URL.
Name the model id and the call goes to the provider that holds it.
GET /v1/models lists every id your key can name.
Answers come back in the dialect you called, OpenAI or Anthropic.
Set a client up per dialect: the OpenAI base URL reference and the Anthropic base URL reference.
Add a provider in the app, or add an endpoint on the api console or with POST /v1/upstreams.
Keys you mint and manage
Mint one scoped key per tool or teammate.
Give each its own scopes, allowed models and daily or monthly cap.
Revoke one and only that tool stops.
Keys come in two classes: an sbc_ caller key is scoped to one tool or teammate, and an sbk_ account key covers the whole account. The model routes take a caller key; the account key answers 401 there.
Do it on the api console or from the API itself.POST /v1/keys mints, GET /v1/keys lists, PATCH /v1/keys/{id} edits, DELETE /v1/keys/{id} revokes.
A key needs keys:write to do this, and never mints a key wider than itself.
No account yet? An agent follows /auth.md: it signs its user in with an emailed code, then mints a caller key with the token it gets.
Scopes
| scope | what it allows |
|---|---|
| gateway:invoke | Call models through Superbot |
| usage:read | Read usage and spend |
| billing:read | Read the credit balance |
| keys:read | List caller keys |
| keys:write | Mint, edit and revoke caller keys |
| endpoints:read | Read custom endpoints and aliases |
| endpoints:write | Change custom endpoints and aliases |
| teams:read | Read teams and invites |
| teams:write | Manage teams, members and invites |
| devices:read | List devices |
| devices:write | Remove devices |
| runs:read | List and read cloud runs and their events |
| runs:write | Start and cancel cloud runs |
| mcp:invoke | Use the MCP tools on your relay |
| turns:read | Read turns and re-attach to their streams |
| tools:invoke | Use the app's tools: images, audio, connectors, tool search |
Presets: Gateway calls models, Read-only query reads your account, Full access holds every scope.
Your own MCP tools are at https://api.superbot.gg/v1/mcp.
The MCP endpoints are listed in Remote MCP.
Every route
Each route links to its full reference, with request and response samples.
Call models
| method | path | what it does | scope |
|---|---|---|---|
| GET | /v1/turns/{session} | Read a turn | turns:read |
| GET | /v1/turns/{session}/stream | Re-attach to a turn’s stream | turns:read |
| POST | /v1/chat/completions | Create a chat completion | gateway:invoke |
| POST | /v1/responses | Create a response | gateway:invoke |
| POST | /v1/messages | Create a message | gateway:invoke |
| POST | /v1/messages/count_tokens | Estimate input tokens | any key |
| GET | /v1/models | List models | any key |
Manage keys
| method | path | what it does | scope |
|---|---|---|---|
| GET | /v1/keys | List caller keys | keys:read |
| POST | /v1/keys | Create a caller key | keys:write |
| GET | /v1/keys/whoami | Get the calling key | any key |
| PATCH | /v1/keys/{id} | Update a caller key | keys:write |
| DELETE | /v1/keys/{id} | Revoke a caller key | keys:write |
| POST | /v1/keys/{id}/rotate | Rotate a caller key | keys:write |
Usage and spend
| method | path | what it does | scope |
|---|---|---|---|
| GET | /v1/usage | Get usage over a window | usage:read |
| GET | /v1/usage/requests | List usage per request | usage:read |
| GET | /v1/usage/daily | Get usage per UTC day | usage:read |
| GET | /v1/usage/breakdown | Get usage bucketed and grouped | usage:read |
| GET | /v1/usage/export | Export usage rows | usage:read |
| GET | /v1/credits | Get the credit balance | billing:read |
| GET | /v1/spend | Get AI spend across apps | usage:read |
| GET | /v1/usage/report | Get a usage report | usage:read |
Custom endpoints
| method | path | what it does | scope |
|---|---|---|---|
| GET | /v1/upstreams | List custom endpoints | endpoints:read |
| POST | /v1/upstreams | Add a custom endpoint | endpoints:write |
| PATCH | /v1/upstreams/{slug} | Update a custom endpoint | endpoints:write |
| DELETE | /v1/upstreams/{slug} | Remove a custom endpoint | endpoints:write |
| POST | /v1/upstreams/{slug}/probe | Re-probe a custom endpoint | endpoints:write |
| GET | /v1/aliases | List @mention aliases | endpoints:read |
| PUT | /v1/aliases/{token} | Set an @mention alias | endpoints:write |
| DELETE | /v1/aliases/{token} | Delete an @mention alias | endpoints:write |
| GET | /docs/services/{service_id}.json | Get a service’s OpenAPI document | no key |
Teams
| method | path | what it does | scope |
|---|---|---|---|
| GET | /v1/org/{id}/audit | Export a team’s audit log | teams:read |
| GET | /v1/teams | List teams | teams:read |
| POST | /v1/teams | Create a team | teams:write |
| GET | /v1/teams/{team_id} | Get a team | teams:read |
| PATCH | /v1/teams/{team_id} | Update a team | teams:write |
| DELETE | /v1/teams/{team_id} | Delete a team | teams:write |
| GET | /v1/teams/{team_id}/members | List team members | teams:read |
| PATCH | /v1/teams/{team_id}/members/{user_id} | Change a member’s role | teams:write |
| DELETE | /v1/teams/{team_id}/members/{user_id} | Remove a team member | teams:write |
| GET | /v1/teams/{team_id}/invites | List pending team invites | teams:read |
| POST | /v1/teams/{team_id}/invites | Invite someone to a team | teams:write |
| DELETE | /v1/teams/{team_id}/invites/{code} | Revoke a team invite | teams:write |
| POST | /v1/teams/{team_id}/invites/{code}/resend | Resend a team invite | teams:write |
| POST | /v1/team_invites/{code}/accept | Accept a team invite | teams:write |
Devices
| method | path | what it does | scope |
|---|---|---|---|
| POST | /v1/devices/{device_id}/jobs | Run a job on an agent computer | devices:write |
| GET | /v1/devices/{device_id}/jobs/{job_id} | Read an agent computer job | devices:read |
| GET | /v1/devices/{device_id}/terminals/{terminal_id}/stream | Stream an agent computer terminal | devices:read |
| GET | /v1/pair/{user_code} | Preview an agent computer code | any key |
| POST | /v1/pair/{user_code}/approve | Approve an agent computer code | any key |
| POST | /v1/pair/{user_code}/deny | Decline an agent computer code | any key |
| GET | /v1/devices | List devices | devices:read |
| GET | /v1/devices/{device_id} | Get a device | devices:read |
| PATCH | /v1/devices/{device_id} | Rename a device | devices:write |
| DELETE | /v1/devices/{device_id} | Unlink a device | devices:write |
Runs
| method | path | what it does | scope |
|---|---|---|---|
| GET | /v1/runs | List cloud runs | runs:read |
| POST | /v1/runs | Start a cloud run | runs:write |
| GET | /v1/runs/projects | Find the project for a repository | runs:read |
| GET | /v1/runs/{run_id} | Get a cloud run | runs:read |
| GET | /v1/runs/{run_id}/events | Follow a run’s events | runs:read |
| POST | /v1/runs/{run_id}/cancel | Cancel a cloud run | runs:write |
| POST | /v1/runs/{run_id}/messages | Steer a running cloud run | runs:write |
The whole reference lives at /developers.
The machine-readable spec is /docs/openapi.json.
Streaming
Set stream to true.
Read server-sent events.
Chunks arrive in the dialect you called.
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"}}]}
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
One rate card for every call
1 credit = $0.001. Rates are credits per 1M tokens, with dollars beside each.
House models
superbot and superbot-fast bill the same rates below.
| use | input | output | cache write | cache read |
|---|---|---|---|---|
| API and MCP | 1,000 $1.00 | 5,000 $5.00 | 1,250 $1.25 | 50 $0.05 |
| API and MCP, fast mode | 2,000 $2.00 | 10,000 $10.00 | 2,500 $2.50 | 100 $0.10 |
| Superbot apps | 200 $0.20 | 1,000 $1.00 | 250 $0.25 | 10 $0.01 |
| Superbot apps, fast mode | 400 $0.40 | 2,000 $2.00 | 500 $0.50 | 20 $0.02 |
Calls with your API key bill at the API and MCP rate.
An MCP connector turn bills at the same rate.
superbot and superbot-fast both bill it.
Neither model is free.
Fast mode bills 2x every rate.
Reasoning tokens bill as output.
In the Superbot apps, superbot and superbot-fast both bill at 20% of the API and MCP rate.
Your own subscriptions and keys
Models on your own subscriptions and keys are free on superbot.
superbot adds no credits to those calls.
You pay your provider as usual.
A vendor model dialed on superbot credits, with no account of yours attached, is charged at its own list price.
That is the same $0.001 per credit.
Every call on superbot credits is priced on this one card.
Superbot Free carries 10,000 beta credits a month, refilled on the 1st.
House models
These always answer, with or without a provider connected.
Every other model on your account answers by its own id.
| model | role | context |
|---|---|---|
| superbot | Your Superbot agent. | 1M |
| superbot-omni | Superbot agent, run on your computer. | 1M |
| superbot-fast | Quick and cheap, for small jobs. | 500k |
Status contract
401missing, malformed or unknown key402budget spent403revoked key or model not allowed429over the per-key bucket499the caller hung up
Signed in? Mint a key on the api console.
Third-party client? Use superbot from Cursor, Continue, Claude Code and other clients.
Plans? See pricing.