API REFERENCE

Modavio API

Modavio implements the Anthropic Messages format. If you already have a Messages client, change the base URL and the key. Every response tells you which model actually answered and what it cost.

Authentication

Send your key in the x-api-key header (an Authorization: Bearerheader is also accepted). Keys look like fg_live_…, are shown once at creation, and are stored only as a SHA-256 hash — we cannot recover one for you. Create and revoke keys in the dashboard; an account may hold 10 active keys at a time.

POST /api/v1/messages

cURL

curl https://modavio.app/api/v1/messages \
  -H "x-api-key: $MODAVIO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "auto:code",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Write a Python function that parses ISO 8601 durations." }
    ]
  }'

Request fields

Field	Required	Notes
`model`	Yes	Any route from the catalogue. Unknown ids are rejected with 400.
`messages`	Yes	Non-empty array; roles `user` or `assistant`.
`max_tokens`	Yes	1–32,000. Used to size the reserve.
`system`	No	Relayed as sent, and counted in the input estimate.
`tools`	No	Up to 64 customer-defined tools. See below.
`stream`	No	Must be false or absent; streaming is not available yet.

Response headers

Header	Meaning
`X-FleetGate-Requested-Model`	The route you asked for.
`X-FleetGate-Delivered-Model`	The model that actually answered — what you were billed for.
`X-FleetGate-Cost-Micros`	Charge for this request, in millionths of a dollar.
`X-FleetGate-Balance-Micros`	Your balance after settlement.
`X-FleetGate-Upstream`	`not-contacted` on a 402; `contacted-no-charge` when Fleet failed.

Tool use

Modavio relays customer-defined tools — objects of the form { name, description, input_schema } . It refuses any tool carrying a type discriminator: the built-in shell, text-editor, computer-use and server-side tools. Those grant ambient capability on the machine running the model, which for a hosted gateway means our infrastructure, not yours. A refused tool returns 400 host_tool_not_permitted and is never sent upstream.

Tool-bearing requests are sent to the Fleet exactly once and never retried. The upstream tool protocol can fail with max_turns before consuming any tokens; a blind retry would risk double-charging upstream for one request of yours. When that happens you get a 400-class error, and your reserve is refunded in full.

GET /api/v1/models

Returns the callable catalogue with live pricing and the pricing version. It lists only routes Modavio can both call and settle — it is not a passthrough of the upstream catalogue.

Errors

Every error is JSON with an error.code. Modavio never relays an upstream HTML error page.

Status	Code	Meaning
401	`invalid_api_key`	Missing, unknown or revoked key.
402	`insufficient_credit`	Not enough balance to reserve. Fleet was not contacted.
400	`unknown_model`	Route is not in the catalogue.
400	`host_tool_not_permitted`	A built-in/host-capability tool was supplied.
413	`request_too_large`	Body over 1 MB.
429	`rate_limited`	Over 120 requests per 60s. See `Retry-After`.
502	`upstream_capacity`	Fleet had no capacity. Reserve refunded.
504	`upstream_timeout`	Fleet did not answer in time. Reserve refunded.

More examples

TypeScript

const response = await fetch("https://modavio.app/api/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.MODAVIO_API_KEY!,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "auto:code",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Explain this stack trace." }],
  }),
});

if (response.status === 402) {
  // Decided before Fleet was contacted — add credit and retry.
  throw new Error("Modavio balance exhausted");
}

const message = await response.json();
console.log(response.headers.get("x-fleetgate-delivered-model"));
console.log(message.content[0].text);

Python

import os, httpx

response = httpx.post(
    "https://modavio.app/api/v1/messages",
    headers={"x-api-key": os.environ["MODAVIO_API_KEY"]},
    json={
        "model": "auto:reasoning",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Summarise this incident report."}],
    },
    timeout=180,
)
response.raise_for_status()
print(response.headers["x-fleetgate-delivered-model"])
print(response.json()["content"][0]["text"])

Anthropic SDK

from anthropic import Anthropic

# Modavio speaks the Messages format, so the official SDK works by
# pointing base_url at Modavio and passing your Modavio key.
client = Anthropic(
    api_key=os.environ["MODAVIO_API_KEY"],
    base_url="https://modavio.app/api",
)

message = client.messages.create(
    model="auto:code",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Refactor this function."}],
)
print(message.content[0].text)

Callable routes

auto
auto:cheap
auto:code
auto:reasoning
auto:long-context
haiku
sonnet
opus