skip to content
superbot.gg

Gateway

OpenAI- and Anthropic-shaped model calls, answered in the dialect you dialed.

7 operations. Errors link to their row on the overview.

view .mdopenapi

Read a turnlink to Read a turn

GET /v1/turns/{session}

Where a turn of one of your conversations stands: running with the text so far, done with the reply (and assets, the files it made, for a caller key that draws no cards), error, cancelled. ?request= names one turn (the request_id of an async call’s 202, from either form: x-superbot-callback-url or Prefer: respond-async); without it the conversation’s newest turn. A turn the gateway admitted reads running (empty text) from the moment of its 202, before the agent has produced a frame, so a poll that starts at once never sees a gap; one an earlier process lost after admitting it reads error with reason interrupted. Turns are stored for 24 hours. Needs the turns:read scope; the read bills nothing. A missing or unknown bearer is 401, a key without the scope 403 insufficient_scope, a request id this account never admitted 404 no_turn and a deleted conversation 410 chat_deleted.

A caller key holding turns:read (Authorization: Bearer sbc_… or x-api-key: sbc_…), or a signed-in session.

Operation id getTurn in Gateway.

Path parameters

  • session string required

    The conversation id (what x-superbot-session named, or the session of an async call’s 202).

Query parameters

  • request string optional

    A turn’s request id.

Response 200

The turn.

application/json: TurnRecord.

  • state string required

    Where the turn stands. One of running, done, error, cancelled, parked.

  • request_id string required
  • text string

    The reply so far (running) or the whole reply (done).

  • assets array of TurnAsset

    Only on a done turn, only when it made files, and only when the read is by a caller key that draws no cards (an automation step, a script): the files the reply names, one entry per file, in order. text is unchanged beside it.

    4 fields
    • name string required

      A file name with its extension where one is known, ready to hand to a Gmail attachment or a Drive upload.

    • mime string required

      The file’s media type.

    • size integer required

      The size in bytes.

    • url string required

      Where to fetch the bytes. A generated picture, sound or clip is at /gen/; an artifact is published at an unguessable, immutable public link (/shared/ or /gen/) for a zapier/ or n8n/ caller, and answered by its signed artifact link (valid 24 hours) for any other.

Errors

StatusCodeWhat to change
401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

404not_found

No such resource on this account; check the id.

view .mdopenapi
Request

curl

curl -sS -X GET "https://superbot.gg/v1/turns/$SESSION" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const session = 'SESSION';
const res = await fetch(`https://superbot.gg/v1/turns/${session}`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

session = "SESSION"
res = requests.request(
    "GET",
    f"https://superbot.gg/v1/turns/{session}",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())
Response

200 The turn.

{
  "state": "running",
  "request_id": "your-request-id",
  "text": "your-text",
  "assets": [
    {
      "name": "Q3-report.pdf",
      "mime": "application/pdf",
      "size": 0,
      "url": "https://example.com"
    }
  ]
}

401 The bearer is missing, malformed or unknown.

{
  "error": "unauthorized",
  "message": "Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.",
  "doc_url": "https://superbot.gg/developers#errors-unauthorized",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

403 The key lacks a scope (insufficient_scope), is revoked, or may not call this route.

{
  "error": "insufficient_scope",
  "message": "The key lacks the scope in required_scopes; mint a key that holds it.",
  "doc_url": "https://superbot.gg/developers#errors-insufficient_scope",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

404 No such resource on this account.

{
  "error": "not_found",
  "message": "No such resource on this account; check the id.",
  "doc_url": "https://superbot.gg/developers#errors-not_found",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

Re-attach to a turn’s streamlink to Re-attach to a turn’s stream

GET /v1/turns/{session}/stream

Server-sent events: every journaled frame of the turn after after (or Last-Event-ID), then the live frames until its answer or error. A cursor past the journal gets one resync with the text so far. Needs the turns:read scope.

A caller key holding turns:read (Authorization: Bearer sbc_… or x-api-key: sbc_…), or a signed-in session.

Operation id streamTurn in Gateway.

Path parameters

  • session string required

    The conversation id (what x-superbot-session named, or the session of an async call’s 202).

Query parameters

  • request string required

    The turn’s request id (required).

  • after string optional

    The last frame id already seen.

Response 200

The turn’s frames as server-sent events.

text/event-stream: string.

Errors

StatusCodeWhat to change
401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

404not_found

No such resource on this account; check the id.

view .mdopenapi
Request

curl

curl -sS -X GET "https://superbot.gg/v1/turns/$SESSION/stream?request=string" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const session = 'SESSION';
const res = await fetch(`https://superbot.gg/v1/turns/${session}/stream?request=string`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

session = "SESSION"
res = requests.request(
    "GET",
    f"https://superbot.gg/v1/turns/{session}/stream?request=string",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())
Response

200 The turn’s frames as server-sent events.

text/event-stream: string

401 The bearer is missing, malformed or unknown.

{
  "error": "unauthorized",
  "message": "Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.",
  "doc_url": "https://superbot.gg/developers#errors-unauthorized",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

403 The key lacks a scope (insufficient_scope), is revoked, or may not call this route.

{
  "error": "insufficient_scope",
  "message": "The key lacks the scope in required_scopes; mint a key that holds it.",
  "doc_url": "https://superbot.gg/developers#errors-insufficient_scope",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

404 No such resource on this account.

{
  "error": "not_found",
  "message": "No such resource on this account; check the id.",
  "doc_url": "https://superbot.gg/developers#errors-not_found",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

Create a chat completionlink to Create a chat completion

POST /v1/chat/completions

OpenAI Chat Completions: passed through to your own vendor key, transcoded, or answered by your agent (model: "superbot"). 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. When the agent answers with files (a generated picture, sound or clip, a document), the reply carries them beside the text as a top-level superbot_assets array of {name, mime, size, url} (a streamed reply sends it on its last chunk before [DONE]), only for a caller that draws no cards and only when there are files; the text is unchanged. The url is a durable public link for a zapier/ or n8n/ client (x-superbot-client) and the artifact’s signed link (valid 24 hours) for any other caller. When your agent answers, its server-side memory is kept per conversation: name one with the x-superbot-session header, or superbot reads the id your client sends (prompt_cache_key, metadata.session_id, metadata.conversation_id, a Responses conversation or an Anthropic metadata.user_id), else it keys the conversation on its first message.

A caller key holding gateway:invoke (Authorization: Bearer sbc_… or x-api-key: sbc_…).

Operation id createChatCompletion in Gateway.

Header parameters

  • x-superbot-route string optional

    Override the key’s route for this request. One of byo, credits, auto.

  • x-superbot-mode string optional

    Override the key’s mode for this request. One of model, agent.

  • x-superbot-engine string optional

    Run the agent lane on your computer (omni). One of omni.

  • x-superbot-session string optional

    Names the server-side conversation your agent continues: letters, digits, _ and -, at most 59 characters.

  • x-superbot-callback-url string optional

    An https URL (a Zapier catch hook, an n8n webhook node). The call is accepted at once with 202 {session, request_id}, the turn runs, and when it settles Superbot POSTs {session, request_id, status, text} to this URL (status is done or error; an error also carries error: {code, message}; a turn that made files also carries assets, the same list as the reply’s superbot_assets). The URL is a secret: it is stored sealed, never logged, and forgotten once delivered. A 2xx from your URL ends the delivery; a network error, 408, 429 or 5xx is retried (1 s, 5 s, 30 s, 2 min, 10 min). Each delivery carries x-superbot-event: turn.settled and a stable x-superbot-delivery id. Every refusal a plain call gets (401, 402, 403, 429, a bad body) is still answered synchronously and starts no turn. The reply is the non-streamed one whatever stream says. Name the thread with x-superbot-session to continue it; a key holding turns:read reads the same turn back at GET /v1/turns/{session}?request={request_id}.

  • Prefer string optional

    respond-async (RFC 7240) starts the turn and answers 202 {session, request_id} with Preference-Applied: respond-async as soon as it is accepted; nothing is delivered, so read the result by polling GET /v1/turns/{session}?request={request_id} (or re-attach at /stream) with turns:read. The turn runs on whether or not you stay connected. It applies to the agent (the default for model: superbot); on a call that dials a model directly the preference is ignored, the call is answered as usual and the response carries no Preference-Applied. With x-superbot-callback-url too, the callback form is used. Every refusal a plain call gets is still answered synchronously and starts no turn. The reply is the non-streamed one whatever stream says.

Request body

application/json, required.

An OpenAI Chat Completions request body.

  • model string required

Body reference: OpenAI Chat Completions reference.

Response 200

The answer in the dialect you dialed; streamed as server-sent events when the body asks for stream: true.

application/json: object.

text/event-stream: string.

Response 202

Only with x-superbot-callback-url or Prefer: respond-async: the call was accepted and the turn is running. With the callback header the result is POSTed to that URL when it settles; with Prefer: respond-async alone nothing is delivered and the caller polls. session and request_id read it back with turns:read. Preference-Applied: respond-async names the preference whenever the call asked for it.

application/json: TurnCallbackAccepted.

  • session string required

    The conversation the turn runs in: what x-superbot-session named, else the id the gateway derived.

  • request_id string required

    The turn’s id (also the response’s x-request-id): the request of GET /v1/turns/{session}.

Errors

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.

402byo_url

The key’s budget or your credits are spent (byo_url on the body).

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

403model_not_allowed

Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries x-superbot-error-origin: vendor is your vendor credential’s refusal, not the gateway’s.

403no_vendor_credential

Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries x-superbot-error-origin: vendor is your vendor credential’s refusal, not the gateway’s.

403no_custom_upstream

Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries x-superbot-error-origin: vendor is your vendor credential’s refusal, not the gateway’s.

429rate_limited

Over the per-key request bucket; retry after x-ratelimit-reset.

499

The caller hung up; the agent turn keeps running.

5XX

The upstream’s own status, rendered in your dialect. When a status is your own vendor credential’s answer (a BYO or custom-endpoint dial) the response carries x-superbot-error-origin: vendor and error.origin: "vendor" with error.vendor_status; a refusal without them is the gateway’s own.

view .mdopenapi
Request

curl

curl -sS -X POST "https://superbot.gg/v1/chat/completions" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"superbot"}'

JavaScript

const res = await fetch(`https://superbot.gg/v1/chat/completions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"model":"superbot"}),
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "POST",
    "https://superbot.gg/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"model":"superbot"},
)
print(res.status_code, res.json())
Response

200 The answer in the dialect you dialed; streamed as server-sent events when the body asks for `stream: true`.

{}

202 Only with `x-superbot-callback-url` or `Prefer: respond-async`: the call was accepted and the turn is running. With the callback header the result is POSTed to that URL when it settles; with `Prefer: respond-async` alone nothing is delivered and the caller polls. `session` and `request_id` read it back with `turns:read`. `Preference-Applied: respond-async` names the preference whenever the call asked for it.

{
  "session": "your-session",
  "request_id": "your-request-id"
}

400 The body is not JSON or the dialect refused it.

"string"

401 Missing, malformed or unknown key. A 401 that carries `x-superbot-error-origin: vendor` is your vendor credential’s refusal, not the gateway’s.

"string"

402 The key’s budget or your credits are spent (`byo_url` on the body).

"string"

403 Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries `x-superbot-error-origin: vendor` is your vendor credential’s refusal, not the gateway’s.

"string"

429 Over the per-key request bucket. A 429 that carries `x-superbot-error-origin: vendor` is your vendor’s rate limit, not the gateway’s.

"string"

499 The caller hung up; the agent turn keeps running.

(no body)

5XX The upstream’s own status, rendered in your dialect. When a status is your own vendor credential’s answer (a BYO or custom-endpoint dial) the response carries `x-superbot-error-origin: vendor` and `error.origin: "vendor"` with `error.vendor_status`; a refusal without them is the gateway’s own.

"string"

Create a responselink to Create a response

POST /v1/responses

OpenAI Responses: model: "superbot" (or superbot-omni) runs your agent; a linked Codex login passes through. 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. When your agent answers, its server-side memory is kept per conversation: name one with the x-superbot-session header, or superbot reads the id your client sends (prompt_cache_key, metadata.session_id, metadata.conversation_id, a Responses conversation or an Anthropic metadata.user_id), else it keys the conversation on its first message.

A caller key holding gateway:invoke (Authorization: Bearer sbc_… or x-api-key: sbc_…).

Operation id createResponse in Gateway.

Header parameters

  • x-superbot-route string optional

    Override the key’s route for this request. One of byo, credits, auto.

  • x-superbot-mode string optional

    Override the key’s mode for this request. One of model, agent.

  • x-superbot-engine string optional

    Run the agent lane on your computer (omni). One of omni.

  • x-superbot-session string optional

    Names the server-side conversation your agent continues: letters, digits, _ and -, at most 59 characters.

Request body

application/json, required.

An OpenAI Responses request body.

  • model string required

Body reference: OpenAI Responses reference.

Response 200

The answer in the dialect you dialed; streamed as server-sent events when the body asks for stream: true.

application/json: object.

text/event-stream: string.

Errors

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.

402byo_url

The key’s budget or your credits are spent (byo_url on the body).

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

403model_not_allowed

Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries x-superbot-error-origin: vendor is your vendor credential’s refusal, not the gateway’s.

403no_vendor_credential

Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries x-superbot-error-origin: vendor is your vendor credential’s refusal, not the gateway’s.

403no_custom_upstream

Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries x-superbot-error-origin: vendor is your vendor credential’s refusal, not the gateway’s.

429rate_limited

Over the per-key request bucket; retry after x-ratelimit-reset.

499

The caller hung up; the agent turn keeps running.

5XX

The upstream’s own status, rendered in your dialect. When a status is your own vendor credential’s answer (a BYO or custom-endpoint dial) the response carries x-superbot-error-origin: vendor and error.origin: "vendor" with error.vendor_status; a refusal without them is the gateway’s own.

view .mdopenapi
Request

curl

curl -sS -X POST "https://superbot.gg/v1/responses" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"superbot"}'

JavaScript

const res = await fetch(`https://superbot.gg/v1/responses`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"model":"superbot"}),
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "POST",
    "https://superbot.gg/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"model":"superbot"},
)
print(res.status_code, res.json())
Response

200 The answer in the dialect you dialed; streamed as server-sent events when the body asks for `stream: true`.

{}

400 The body is not JSON or the dialect refused it.

"string"

401 Missing, malformed or unknown key. A 401 that carries `x-superbot-error-origin: vendor` is your vendor credential’s refusal, not the gateway’s.

"string"

402 The key’s budget or your credits are spent (`byo_url` on the body).

"string"

403 Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries `x-superbot-error-origin: vendor` is your vendor credential’s refusal, not the gateway’s.

"string"

429 Over the per-key request bucket. A 429 that carries `x-superbot-error-origin: vendor` is your vendor’s rate limit, not the gateway’s.

"string"

499 The caller hung up; the agent turn keeps running.

(no body)

5XX The upstream’s own status, rendered in your dialect. When a status is your own vendor credential’s answer (a BYO or custom-endpoint dial) the response carries `x-superbot-error-origin: vendor` and `error.origin: "vendor"` with `error.vendor_status`; a refusal without them is the gateway’s own.

"string"

Create a messagelink to Create a message

POST /v1/messages

Anthropic Messages, transcoded to the upstream the key routes to, or answered by your agent (model: "superbot"). 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. When your agent answers, its server-side memory is kept per conversation: name one with the x-superbot-session header, or superbot reads the id your client sends (prompt_cache_key, metadata.session_id, metadata.conversation_id, a Responses conversation or an Anthropic metadata.user_id), else it keys the conversation on its first message.

A caller key holding gateway:invoke (Authorization: Bearer sbc_… or x-api-key: sbc_…).

Operation id createMessage in Gateway.

Header parameters

  • x-superbot-route string optional

    Override the key’s route for this request. One of byo, credits, auto.

  • x-superbot-mode string optional

    Override the key’s mode for this request. One of model, agent.

  • x-superbot-engine string optional

    Run the agent lane on your computer (omni). One of omni.

  • x-superbot-session string optional

    Names the server-side conversation your agent continues: letters, digits, _ and -, at most 59 characters.

Request body

application/json, required.

An Anthropic Messages request body.

  • model string required

Body reference: Anthropic Messages reference.

Response 200

The answer in the dialect you dialed; streamed as server-sent events when the body asks for stream: true.

application/json: object.

text/event-stream: string.

Errors

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.

402byo_url

The key’s budget or your credits are spent (byo_url on the body).

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

403model_not_allowed

Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries x-superbot-error-origin: vendor is your vendor credential’s refusal, not the gateway’s.

403no_vendor_credential

Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries x-superbot-error-origin: vendor is your vendor credential’s refusal, not the gateway’s.

403no_custom_upstream

Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries x-superbot-error-origin: vendor is your vendor credential’s refusal, not the gateway’s.

429rate_limited

Over the per-key request bucket; retry after x-ratelimit-reset.

499

The caller hung up; the agent turn keeps running.

5XX

The upstream’s own status, rendered in your dialect. When a status is your own vendor credential’s answer (a BYO or custom-endpoint dial) the response carries x-superbot-error-origin: vendor and error.origin: "vendor" with error.vendor_status; a refusal without them is the gateway’s own.

view .mdopenapi
Request

curl

curl -sS -X POST "https://superbot.gg/v1/messages" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"superbot"}'

JavaScript

const res = await fetch(`https://superbot.gg/v1/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"model":"superbot"}),
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "POST",
    "https://superbot.gg/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"model":"superbot"},
)
print(res.status_code, res.json())
Response

200 The answer in the dialect you dialed; streamed as server-sent events when the body asks for `stream: true`.

{}

400 The body is not JSON or the dialect refused it.

"string"

401 Missing, malformed or unknown key. A 401 that carries `x-superbot-error-origin: vendor` is your vendor credential’s refusal, not the gateway’s.

"string"

402 The key’s budget or your credits are spent (`byo_url` on the body).

"string"

403 Revoked · insufficient_scope · model_not_allowed · no_vendor_credential · no_custom_upstream. A 403 that carries `x-superbot-error-origin: vendor` is your vendor credential’s refusal, not the gateway’s.

"string"

429 Over the per-key request bucket. A 429 that carries `x-superbot-error-origin: vendor` is your vendor’s rate limit, not the gateway’s.

"string"

499 The caller hung up; the agent turn keeps running.

(no body)

5XX The upstream’s own status, rendered in your dialect. When a status is your own vendor credential’s answer (a BYO or custom-endpoint dial) the response carries `x-superbot-error-origin: vendor` and `error.origin: "vendor"` with `error.vendor_status`; a refusal without them is the gateway’s own.

"string"

Estimate input tokenslink to Estimate input tokens

POST /v1/messages/count_tokens

A local estimate (characters / 4). No upstream call and no charge.

Any live caller key (Authorization: Bearer sbc_… or x-api-key: sbc_…).

Operation id countMessageTokens in Gateway.

Request body

application/json, required.

An Anthropic Messages body; only messages is read.

  • model string required

Body reference: Anthropic count tokens reference.

Response 200

The estimate.

application/json: TokenCount.

  • input_tokens integer required

Errors

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

view .mdopenapi
Request

curl

curl -sS -X POST "https://superbot.gg/v1/messages/count_tokens" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"superbot"}'

JavaScript

const res = await fetch(`https://superbot.gg/v1/messages/count_tokens`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"model":"superbot"}),
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "POST",
    "https://superbot.gg/v1/messages/count_tokens",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"model":"superbot"},
)
print(res.status_code, res.json())
Response

200 The estimate.

{
  "input_tokens": 0
}

400 The body is not JSON.

"string"

401 Missing, malformed or unknown key. A 401 that carries `x-superbot-error-origin: vendor` is your vendor credential’s refusal, not the gateway’s.

"string"

403 The key is revoked.

"string"

List modelslink to List models

GET /v1/models

The agent models first (superbot, superbot-omni, superbot-fast), then your linked vendors’ models, your custom endpoints’ ids as custom/<slug>/<id>, then the credits catalog.

Any live caller key (Authorization: Bearer sbc_… or x-api-key: sbc_…).

Operation id listModels in Gateway.

Response 200

Every model this key can name.

application/json: ModelList.

  • object string required

    One of list.

  • data array of Model required
    12 fields
    • id string required
    • object string required

      One of model.

    • created integer required
    • owned_by string required
    • lane string
    • tier string
    • available boolean
    • reason string
    • min_plan string
    • auto boolean
    • context_window integer
    • context_length integer

Errors

StatusCodeWhat to change
401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

view .mdopenapi
Request

curl

curl -sS -X GET "https://superbot.gg/v1/models" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const res = await fetch(`https://superbot.gg/v1/models`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "GET",
    "https://superbot.gg/v1/models",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())
Response

200 Every model this key can name.

{
  "object": "list",
  "data": [
    {
      "id": "superbot",
      "object": "model",
      "created": 0,
      "owned_by": "your-owned-by",
      "lane": "your-lane",
      "tier": "your-tier",
      "available": true,
      "reason": "your-reason",
      "min_plan": "your-min-plan",
      "auto": true,
      "context_window": 0,
      "context_length": 0
    }
  ]
}

401 Missing, malformed or unknown key. A 401 that carries `x-superbot-error-origin: vendor` is your vendor credential’s refusal, not the gateway’s.

"string"

403 The key is revoked.

"string"