# Management API reference

> <p className="tare-lead">
  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.
</p>

# 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.

:::tip Gateway model calls live elsewhere
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](/reference/supported-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](#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](/reference/api/clients/agentrouter-clients-v-1-clients-service-create-client-with-key) | `POST /v1/customers/{customer_id}/projects/{project_id}/clients` |
| Mint a JWT user-token for a user | [CreateApiKey](/reference/api/api-keys/agentrouter-api-keys-v-1-api-keys-service-create-api-key) | `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 <code>agentrouter-openapi-0.1.1.yaml</code> is also available at the same path.
  
  <Link to="/reference/api/inference/agentrouter-inference-v-1" className="tare-nav-card">
    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.
  </Link>

## Make your first call

For a hands-on walkthrough, [Make an AI API call through Agent Router](/agent-router-service/quickstarts/make-an-api-call) 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.

## Related

  <Link to="/reference/supported-apis" className="tare-nav-card">
    Gateway APIs
    Gateway wire formats for model calls (OpenAI- and Anthropic-compatible), with request and streaming examples.
  </Link>
  <Link to="/reference/gateway-behavior" className="tare-nav-card">
    Gateway behavior
    Error normalization, correlation IDs, and the request debugging workflow.
  </Link>