Documentation
One API, one bill, eighteen models across eight providers. This is the short version; the API reference has the detail.
What Swurl is
Swurl is a routing and metering layer in front of the major model providers. You send a request to Swurl; Swurl forwards it to the provider you named, or to whichever provider Auto-Route picks, meters the tokens, draws the cost from your credit balance, and streams the response back.
The request and response shapes are OpenAI-compatible, which means most existing code works by changing the base URL and the key.
Core concepts
| Term | Meaning |
|---|---|
workspace | A billing and policy boundary. Holds seats, a credit pool, the prompt library and the audit log. |
credit | One US dollar of model spend at published rates. Allocated monthly per seat, pooled at workspace level, rolls over 60 days. |
thread | An ordered list of messages carrying context. Threads survive a change of model. |
pin | A binding of a thread or a library prompt to one model, which stops Auto-Route from choosing. |
route | A single decision: this message, this task class, therefore this model. Logged and exportable. |
Quickstart
Create a key in the workspace under Settings → API keys, then:
curl https://api.swurl.ai/v1/chat/completions \
-H "Authorization: Bearer $SWURL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [{"role": "user", "content": "Summarise this contract clause."}]
}'Passing "model": "auto" hands the choice to Auto-Route. Name a model explicitly and that model is used. The response includes a swurl object reporting which model ran, why, and what it cost.
How credits work
Every request is metered on input and output tokens at the published per-model rate, which already includes routing. The cost is drawn from the workspace pool at completion. Streaming requests are metered on the tokens actually delivered, so an aborted stream is charged only for what arrived.
When the pool is empty, behaviour depends on the workspace setting: by default requests continue and the overage appears on the next invoice; with the hard stop enabled, requests return 402 credit_exhausted instead.
Rate limits
| Plan | Requests / min | Concurrent streams | Tokens / min |
|---|---|---|---|
| Free | 20 | 2 | 40,000 |
| Pro | 120 | 8 | 400,000 |
| Team | 600 | 40 | 2,000,000 |
| Enterprise | Negotiated | Negotiated | Negotiated |
Limits are per workspace, not per key. Exceeding one returns 429 with a Retry-After header; back off and retry rather than reissuing immediately.