API reference

crowbot speaks the OpenAI chat-completions dialect. Anything that can talk to OpenAI can talk to crowbot by changing two settings: the base URL and the API key.

copybase URL   https://api.crowbot.sh/v1
auth       Authorization: Bearer <your 16-digit account number>

Your account number is your API key. There is no separate key to generate. Spaces are accepted, so you can paste it exactly as it was shown to you.

Where things live

Three origins, each serving only its own paths; a path asked of the wrong one is a plain 404.

GET https://api.crowbot.sh/api/me returns site and api, so a client given one origin can find the others.

Endpoints

/v1/chat/completions is a passthrough: your system message is sent to the model unchanged and stays first, and so are your tools, tool_choice and response_format. Your system prompt is never replaced, edited, reordered or moved behind anything of ours.

Some models add a short instruction block of their own alongside it — formatting or refusal style. Your prompt keeps its exact bytes and its position; ours goes after it.

Request

copyjson{
  "model": "glm-5.3-flash-crow",
  "messages": [
    {"role": "system", "content": "You are a careful assistant."},
    {"role": "user", "content": "Hello"}
  ],
  "max_tokens": 1024,
  "stream": true
}

An unrecognised model falls back to the default rather than erroring, because agentic clients often send names from other providers.

A model id we do recognise but are not serving returns 404 model_not_found and lists the live ids: falling back there would bill you for a model you did not ask for.

Sampling parameters are forwarded as you send them, including temperature and top_p. Which of them a model honours is up to its vendor.

reasoning_effort we do interpret. Send low, medium, high, xhigh or max: it overrides the model's configured default, any model takes any of them, and one without that tier gets its highest below it (xhigh and max reach a vendor with three tiers as high). Any other value is a 400 naming these. Reasoning tokens bill as output, so this is a spend control, not a quality slider.

Streaming

Set stream: true and read Server-Sent Events. Chunks are chat.completion.chunk objects terminated by data: [DONE], exactly as OpenAI emits them. Usage arrives on a final chunk with an empty choices array — you do not need to ask for it.

Reasoning models put their thinking trace in choices[].delta.reasoning_content, alongside the usual content. Clients that don't know the field simply ignore it.

Tool calling

Standard OpenAI shape in both directions:

copyjson{
  "tools": [{"type": "function", "function": {
    "name": "bash",
    "description": "Run a shell command",
    "parameters": {"type": "object",
                   "properties": {"command": {"type": "string"}},
                   "required": ["command"]}
  }}],
  "tool_choice": "auto"
}

Replies carry message.tool_calls[] with function.arguments as a JSON string, and finish_reason: "tool_calls". Return results as {"role": "tool", "tool_call_id": …, "content": …} messages — one per call, as OpenAI expects. Parallel calls work; send every result before the next turn.

Streaming tool calls arrive as delta.tool_calls[] fragments. Concatenate function.arguments per index to rebuild the JSON.

Errors

Errors are {"error": {"message": …, "type": …}}. The type is the field to branch on — not the status, because a status can be ambiguous. A type worth sending again unchanged adds "retry": true.

Every /v1/chat/completions answer, error or not, carries an X-Request-Id header. Quote it when reporting a failure: it names the one record we keep of that call.

A streamed reply may open with an SSE comment line (:) and carry one during any pause: a keepalive, which every SSE client ignores. A failure after the stream has opened arrives as that same {"error": {"message": …, "type": …}} envelope in a data: frame, followed by data: [DONE].

An upstream vendor's own 401/402/403 is never relayed to you as-is. If our account with a vendor lapses you get a 503 upstream_unavailable: the fault is ours, not your key's or balance's.

Billing

Input, cached input and output bill at separate per-million rates — see Models. Every token sent upstream is billed, and cached input is discounted at the same ratio the upstream gives us.

A pass (see Plans) pays first for models in its scope; your balance pays for the rest. One request is paid by one of them.

A pass does not bill at the rates above. It carries an allowance, sized from what the plan cost, that requests draw down at what the model costs us and that refills continuously at the plan's rate — so it absorbs a burst and comes back over the day. Once the allowance cannot cover a request, that request is the balance's, unless you have said otherwise: POST /api/me/balance-fallback with {"on": false} caps you at the plan, and a request that would then need the balance is refused with 402 plan_allowance_spent and a message saying roughly when the allowance is back. GET /api/me shows the pass while you hold one: allowance_bp is how much of the allowance is left, in basis points of the whole, and refills says roughly when it is full again.

Non-streamed responses carry X-Balance-Microdollars with your remaining paid balance in microdollars (1e-6 USD); a request the pass paid for leaves it where it was. Streamed responses don't (headers precede the body): read /api/me or the final chunk's usage.

Every request is sized to whatever is paying for it before it is sent upstream: max_tokens (or max_completion_tokens) is capped to what the pass's remaining allowance or the balance can pay for after the estimated input, and a request whose input alone costs more than that is refused with 402 insufficient_balance before any vendor is called. Concurrency follows the payer too: each request in flight holds what it can cost (its input and its capped output), and together they may hold what the balance covers, or a pass's remaining allowance and a little past it, up to the parallel requests its plan sold. Past that comes a 429 rate_limited with Retry-After, which names the limit that was reached.

Plans

A plan is one price for a fixed number of days. Buying one gives the account a pass: an allowance that pays first for every model in the plan's scope, the way Billing describes, while the balance goes on paying for everything else. What is on sale is public:

copyGET https://chat.crowbot.sh/api/plans
Authorization: Bearer <your account number>     (optional)

The reply is {"plans": [...]}, one entry per plan you may buy:

copyjson{"id": "starter", "label": "Starter", "tagline": "Hard working or hardly working?",
 "price_usd": 15, "days": 30, "concurrency": 2, "scope": ["frontier"],
 "features": ["Every frontier model", "Cancel any time"], "badge": null}

price_usd buys days days. concurrency is how many requests the pass runs at once; scope names the directions on the Models page it covers (frontier is the resold frontier models, crow our own). features and badge are the card's own words. A pass fixes its allowance in money when it is bought, so nothing on a plan moves when a vendor reprices.

The list is what your account may buy. Signed out, it is whatever is on general sale; while plans are in a closed beta it is empty unless your account is in it. {"plans": []} means nothing is on sale to you, not that the call failed.

Funding, programmatically

The chat UI does all of this with buttons; an agent can do it with four calls, all on https://chat.crowbot.sh except the last.

1. Create an account. GET https://chat.crowbot.sh/api/pow?kind=signup returns {"challenge", "bits", "ttl"}. Find a nonce (≤ 40 chars) such that sha256("<challenge>:<nonce>") has at least bits leading zero bits, then POST https://chat.crowbot.sh/api/signup with header X-Pow: <challenge>.<nonce>. The reply is {"account_number", "formatted", "api_base"} — the only time the number is ever shown. Each signup from an address raises the next one's bits for a day, and signups are capped per address; a 428 means the work grew meanwhile: fetch again.
2. Pick an amount. GET https://chat.crowbot.sh/api/funding → {"min_usd", "max_usd", "pay_with", "rails"} (rails: [{"name", "label", "renews"}]). Any amount in range is accepted, to the cent (usd=3.50), credited 1:1.
3. Get an invoice. GET https://chat.crowbot.sh/checkout?usd=<amount> with Authorization: Bearer <number> returns {"checkout_url"} (a browser Accept: text/html request is redirected there instead). Payment is by crypto or card.
4. Confirm. There is no payment-status endpoint. The processor's callback credits the wallet; poll GET https://api.crowbot.sh/api/me until balance_microdollars rises. Balances never expire.

Device pairing and keys

A machine can hold its own key, so a laptop can be revoked later without changing the account number. This is what the installer does; the raw flow:

1. POST https://chat.crowbot.sh/api/pair/start (optional body {"hostname": "…", "client": "…"}; the key is named <client> @ <hostname>) → {"device_code", "user_code", "ttl", "interval"}. Unauthenticated, capped per address.
2. Show the person the user_code and send them to https://chat.crowbot.sh/pair, where they type it and press Approve while signed in (programmatically: POST https://chat.crowbot.sh/api/pair/approve with the chat cookie and {"user_code"}, or {"user_code", "deny": true}).
3. Poll GET https://chat.crowbot.sh/api/pair/<device_code> every interval seconds: 202 {"status": "pending"} while waiting, then 200 {"status": "ready", "api_key"} exactly once, then 410 pair_expired. Codes last 15 minutes.

GET /api/me/keys lists the account's live keys with a ref, name, hint, created_at and whether each is the one making the request; POST /api/me/keys/<ref>/revoke revokes one. The key that authenticated the request cannot be revoked (409 cannot_revoke_current): there is no recovery, so that click would be a permanent lockout.