Docs API reference
Developers

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 model you send is ignored. The router chooses. The reply's model field reports the model that answered, written as fugal/<model>.
  • The reply carries a fugal object with the cost of the call, the tokens used and the model chosen. The OpenAI-format call also returns the cost in the x-fugal-cost-usd header.

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 system text 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.