Management API reference
This section is the OpenAPI catalog of Agent Router HTTP services: control-plane and management APIs (clients, keys, catalog, projects, insights, and related services), plus a small set of inference management RPCs. It is the place to look up method paths, request and response schemas, and to try calls interactively.
To send prompts with OpenAI- or Anthropic-compatible request shapes (/v1/chat/completions, /v1/responses, /v1/messages, /v1/models, and related gateway paths), use Gateway APIs. Those wire formats are not listed as OpenAPI operations in this catalog.
Introduction
There are two ways to call the APIs documented here: raw HTTP, or the typed Agent Router SDKs. Gateway requests that reach the inference data plane authenticate with a bearer API key; not every control-plane method that creates a key mints a credential the gateway will accept. See Which API key for which surface.
- HTTP APIs. Plain HTTPS against the documented paths: curl, an HTTP client, or a generated client from the OpenAPI spec.
- Language SDKs. Typed clients for Go, Python, and TypeScript wrap the same HTTP APIs with helpers for authentication, retries, and streaming.
The SDKs mirror the HTTP surface, so anything described in this reference is reachable either way.
Since 0.5.0 the reference also records when a call changed: a call's page carries History lines naming the release that changed it, and the API changelog collects those changes per release. When behavior around a call looks different after an upgrade, that is where to look first.
Which API key for which surface
Not every control-plane "create a key" method produces a credential the inference data plane will accept.
| Goal | Use | Endpoint |
|---|---|---|
| Call models through the inference data plane | CreateClientWithKey | POST /v1/customers/{customer_id}/projects/{project_id}/clients |
| Mint a JWT user-token for a user | CreateApiKey | POST /v1/api-keys |
Keys from CreateApiKey are rejected by the inference data plane. If gateway requests return 401 after a key was created with CreateApiKey, create a client key with CreateClientWithKey instead and use that bearer token.
When calling CreateApiKey, user_key_address must equal the owner's user_id. Passing an email address is rejected.
Cookie-authenticated calls from a browser
Since 0.5.0, the management API also accepts cookie-authenticated calls from allowlisted browser origins, so an internal web application can call it with the signed-in user's session instead of embedding a key. Two properties of the allowlist decide whether a call is accepted:
- A wildcard entry covers one label, not a subtree. A wildcard on
example.comsubdomains matcheshttps://app.example.comand nothttps://a.b.example.com; a deeper origin needs its own entry. - Origins outside the list are still refused. The cookie is only honored when the request's
Originmatches an allowlisted entry; from anywhere else, the call needs a bearer credential as before.
Which cost fields to read
Request logs and Insights stats hold more than one cost representation. Read totalCost. It is the whole billed amount for one request: input plus output plus additional.
Do not add the component fields together. inputTokensCost already contains cachedInputTokensCost and cacheCreationInputTokensCost. A sum of those three counts the same money twice.
| Use for | Fields |
|---|---|
| The billed amount for one request | totalCost |
| The billed amount for a stats group | cost |
| Components of the billed amount, after the platform fee | inputTokensCost, outputTokensCost, additionalCost |
Parts of inputTokensCost, not additions to it | cachedInputTokensCost, cacheCreationInputTokensCost |
| The provider price, before the platform fee | inputTokensCostBeforeFee, outputTokensCostBeforeFee, additionalCostBeforeFee, cachedInputTokensCostBeforeFee, cacheCreationInputTokensCostBeforeFee |
| Deprecated. Always 0. | costMicrodollar, inputTokensCostMicrodollar, outputTokensCostMicrodollar |
A *Cost field is the amount Agent Router billed, after the platform fee. The matching *BeforeFee field is the provider price, before that fee. The fee depends on the tier:
- Agent Router Service applies a 5 percent fee, so each
*Costvalue is 1.05 times its*BeforeFeecounterpart. A Bring Your Own Key (BYOK) request is billed nothing. - Agent Router Enterprise applies no fee: every
*Costfield equals its*BeforeFeecounterpart. A BYOK request records the provider list price, so budgets keep tracking BYOK traffic.
Costs recorded by an Enterprise deployment while an earlier configuration applied the Service fee run 5 percent above the provider price, and records already written are not rewritten. A comparison that crosses the correction should read the *BeforeFee fields, which carry the provider price on both sides of it.
Stats endpoints aggregate before they answer: GetRequestLogStats and the customer stats calls can take tens of seconds to reflect recent traffic on a busy tenant, and no freshness guarantee is published. A billing or credit gate should therefore assume a stale window and check a locally cached figure, rather than holding each inference on a live stats call.
Get the full API specification
The complete management API is published as a single OpenAPI 3.1 document covering every service and endpoint in this catalog. Import it into Postman, Insomnia, or Swagger UI, or feed it to a client generator such as openapi-generator.
Download the OpenAPI spec (YAML)
The spec of the current stable release, published by the release pipeline. Older releases are listed in the stable manifest and kept under tags/.
Browse the interactive reference
Per-endpoint pages with request and response schemas and a built-in "try it" console. Every service is listed under Management API reference in the sidebar.
Make a first call
For a hands-on walkthrough, Make an AI API call through Agent Router covers getting a key, pointing an SDK at the gateway, and streaming a response in a few minutes. That guide also covers the tare CLI and the typed Agent Router SDKs.