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.
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 you created a key 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.
Which cost fields to read
Request logs and Insights stats expose more than one cost representation. Use the decimal string fields for metering and billing; do not rely on the microdollar integers.
| Use for | Fields |
|---|---|
| Canonical cost (includes platform fee/markup) | cost, inputTokensCost, outputTokensCost, cachedInputTokensCost, cacheCreationInputTokensCost |
| Pre-fee provider cost | inputTokensCostBeforeFee, outputTokensCostBeforeFee, cachedInputTokensCostBeforeFee, cacheCreationInputTokensCostBeforeFee |
| Avoid | costMicrodollar, inputTokensCostMicrodollar, outputTokensCostMicrodollar, and other *CostMicrodollar fields — these currently return 0 |
Decimal cost fields include the platform fee/markup. The corresponding *BeforeFee fields carry the raw provider cost before that markup. Prefer summing or reading the decimal strings when attributing usage per API key or building a credit ledger.
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)
Always-current spec. The pinned agentrouter-openapi-0.1.1.yaml is also available at the same path.
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 your 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.