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": "gpt-6-astra",
  "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 or max: it overrides the model's configured default, a model without that tier gets its own ceiling (max reaches a vendor with three tiers as high), and a value none can honour is a 400 naming what the model accepts. 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.

Code search

codesearch runs on our side: give it a query, get matching code from public repositories. No search account of your own.

copyPOST https://api.crowbot.sh/v1/tools/codesearch
Authorization: Bearer <your account number>

query is required; lang, repo and count are optional. query may itself carry search filters (repo:, file:, lang:, patterntype:regexp, patterntype:structural, …), which compose with the fields; count is capped.

copyjson{"query": "epoll_wait", "lang": "c", "count": 5}

The reply is {"query", "results", "truncated"}, each result carrying repo, path, the first matching line, a url to the source on its own host, and a snippet (for a type:symbol query, the symbol's kind, name and line):

copyjson{"results": [{"repo": "github.com/x/y", "path": "loop.c", "line": 42,
              "url": "https://github.com/x/y/blob/<ref>/loop.c#L42",
              "snippet": "int n = epoll_wait(epfd, events, MAX_EVENTS, timeout_ms);"}],
 "truncated": false}

Write queries the way code is written: exact identifiers find code, sentences rarely do. lang narrows by language; repo as org/name is anchored to that one repository, which turns a pile of forks into the canonical file. A backend rate limit comes back as 429 rate_limited with Retry-After.

Wiring it into an agent. Register the tool below; when the model calls it, POST the arguments to the endpoint above and feed the reply back as the tool result.

copyjson{
  "type": "function",
  "function": {
    "name": "codesearch",
    "description": "Search public source code and get back matching snippets with repo, path and line. Use it when a real implementation answers better than a description. Write the query the way code is written, not the way a question is asked: two or three exact identifiers (function, class, option or constant names) find code; sentences almost never do. Set lang when you know the language. Set repo when you know the project - org/name is enough - which turns a pile of forks into the one canonical file. Quote an exact phrase \"like this\" to match it verbatim; add type:symbol to find where a name is defined rather than used (slower, but finds the defining file even when the canonical repo is not indexed); add patterntype:regexp for a pattern. If nothing comes back, or the repository is reported as not found, drop the repo filter or a term and search again.",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "Identifiers and exact phrases, optionally with file:/type:symbol/patterntype:regexp filters"
        },
        "lang": {
          "type": "string",
          "description": "Language filter, e.g. python, c++, typescript, go"
        },
        "repo": {
          "type": "string",
          "description": "Repository: org/name (anchored to that repo) or a regexp over full names like github.com/org/name"
        },
        "count": {
          "type": "integer",
          "description": "Maximum results, capped by the server"
        }
      },
      "required": [
        "query"
      ]
    }
  }
}

Snippets bill as ordinary input tokens on your next turn; there is no search fee. Calls are rate-limited. This is the same definition the web chat gives the model.

Errors

Errors are {"error": {"message": …, "type": …}}. The type is the field to branch on — not the status, because a status can be ambiguous.

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.

Two things can pay for a request, and they are asked in a fixed order. A pass — what buying a plan gives you, see Plans — pays first, for any model in its scope. Your balance pays for everything else: a model the pass does not cover, or every request when you hold no pass. The two never mix inside one request; whichever said yes at the door settles it.

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. A streamed response does not carry it — headers are sent before the body starts, so the figure would be stale before the first token. Read /api/me after a stream, or use the usage block on the final chunk.

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 — a balance gets as many parallel requests as it covers in worst-case requests, a pass at most the slots its plan sold, one at minimum either way — and past that a 429 rate_limited with Retry-After.

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", "Refills every day", "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; crypto settles in stablecoin.
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": "…"}) → {"device_code", "user_code", "ttl"}. 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>: 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.