API reference
Every call the service answers, what it returns, the errors you can get, and what is not supported.
Base address and keys
All calls go to https://fugalai.com. Send your key as Authorization: Bearer sk-fugal-... or as x-api-key: sk-fugal-...; both work on every call that needs one. Keys are created and revoked in Settings.
Calls
| Call | Key | What it does |
|---|---|---|
POST /v1/route |
Not needed | A preview: the routing decision only. No model is called and it is free. |
POST /v1/chat/completions |
Needed | An answer, in the OpenAI format. Supports streaming. |
POST /v1/messages |
Needed | An answer, in the Anthropic format. Supports streaming. |
GET /v1/models |
Not needed | Lists the one model name you can send, fugal/auto. |
GET /health |
Not needed | Whether the service is up, and which router it is serving. |
Preview: POST /v1/route
Send {"query": "..."} or {"messages": [...]}. The reply has:
| Field | Meaning |
|---|---|
worker |
The model that would be called. |
p_solve |
The router's predicted chance that model answers correctly. |
ranked |
Every model on the menu, each with its model, p_solve, est_cost_usd and utility. |
est_cost_usd is the expected cost of this one question on that model, not a price per token. Previews are rate limited per address.
Answers
Both answer calls take what their format normally takes. Two things differ from calling a model directly:
- The
modelyou send is ignored. The router chooses. The reply'smodelfield reports the model that answered, written asfugal/<model>. - The reply carries a
fugalobject with the cost of the call, the tokens used and the model chosen. The OpenAI-format call also returns the cost in thex-fugal-cost-usdheader.
Tool calling works on both. Your tools are passed to the chosen model, and tool calls come back in the format you asked in, streaming included.
Tool-heavy work is not yet measured. The router was trained to predict which model answers a question correctly. How well it routes long tool-using sessions has not been measured, so no claim is made about it.
Errors
| Code | Meaning |
|---|---|
401 |
The key is missing, unknown or revoked. A revoked key stops working shortly after it is revoked. |
402 |
The free allowance is used up and there is no credit, or billing is briefly unavailable. Previews stay free either way. |
429 |
Too many requests. Wait a moment and retry. |
502, 503 |
The chosen model or the billing service could not be reached. Retry. |
Not supported
- Images and other non-text input. Non-text parts are dropped from the prompt.
- A true system role on the Anthropic call. Your
systemtext is folded into the conversation as a leading turn. - Choosing the model. Routing is the product.
- Batch, embeddings, files and MCP.
One request is one model call. There is no retry loop and no second model checking the first, so a request is billed for a single call.