Skip to content

API Reference

Choose the listener first: the inference origin handles governed execution, the Console handles sign-in and enterprise provisioning, and the Collector accepts standard OTLP. Public metadata routes require no bearer credential. Discovery, OAuth, preflight, and rejected requests do not all create Traces or share one error envelope. This is an endpoint index; the linked contracts define complete request, authentication, response, and recovery behavior.

Routes

Inference listener

Method and path Credential Purpose
GET /v1/models Ordinary virtual key Virtual models allowed by catalog, Team allowance and key policy, with capabilities.
POST /v1/chat/completions Ordinary virtual key OpenAI-compatible Chat Completions: streaming, function tools, JSON-schema output, store: false.
POST /v1/responses Ordinary virtual key The stateless Responses subset.
POST /v1/embeddings Ordinary virtual key Ordered embeddings with input-only token usage; see Embed and rerank text.
POST /v1/rerank Ordinary virtual key Mission Control reranking extension; original document indexes and relevance scores.
POST /mcp Ordinary virtual key or client connection MCP revision 2026-07-28: server/discover, tools/list, tools/call.
POST /v1/deployments/{deploymentId}:invoke Ordinary key with deployment.invoke Invoke a Production deployment from your own backend.
GET /.well-known/oauth-protected-resource (and /mcp suffix) None RFC 9728 metadata naming the Console as the authorization server for /mcp. Grants nothing.

OPTIONS /mcp and OPTIONS /v1/deployments/{deploymentId}:invoke answer browser preflight for exactly configured origins; every other method on a route returns 405 with Allow. The private control listener serves no inference route and returns 404 for these paths.

GET /v1/models includes capabilities.operations (generation, embedding, rerank). Generation protocols and streaming/tool/structured-output flags are derived only from generation routes; retrieval-only models do not advertise chat support. See Model discovery.

Complete inference contracts: models, retrieval, MCP, and Deployment invocation.

Credentials and management

User and service-account virtual keys use mck_…; OAuth client connections use mcc_… credential versions of logical user keys. Current owner, Team and operation/resource policy are checked on each use. Human roles authorize management separately. The control listener exposes /management/v1 with scoped mcm_… tokens or real Console sessions; see the complete management resource/DTO inventory. Evaluation datasets, experiments, evaluators, score definitions, scores and publish gates are served there too, under /management/v1/evaluation, with the same token family and the same strict-body and revision rules.

Console listener

Client sign-in endpoints (Console)

Method and path Purpose
GET /.well-known/oauth-authorization-server RFC 8414 metadata: code responses, PKCE S256, authorization_code and refresh_token grants, public clients, client ID metadata documents, iss in responses.
POST /oauth/register RFC 7591 dynamic registration of a public client (thirty-day lifetime).
GET /oauth/authorize The consent page; requires a Console session.
POST /oauth/token Code exchange with PKCE and resource, and refresh with rotation; form bodies only.
POST /oauth/revoke RFC 7009 revocation of an access or refresh token; always 200.

Enterprise provisioning is served separately by the Console at /api/scim/v2; see Enterprise identity for discovery, Users/Groups operations, bearer authentication, pagination and error behavior. It is not mounted on the inference listener.

Collector listener

Method and path Credential Contract
HTTP/protobuf POST /v1/traces Ordinary key with telemetry.ingest Standard OTLP ingestion
gRPC opentelemetry.proto.collector.trace.v1.TraceService/Export Ordinary key with telemetry.ingest Standard OTLP ingestion

Use OpenTelemetry setup for a complete exporter and request-propagation example. The Collector is Trace-only; it does not accept model calls or expose lifecycle registration.

Request headers

Header Routes Meaning
Authorization: Bearer … authenticated inference The credential.
traceparent (and tracestate, baggage) governed inference Continue a W3C Trace you own; omit to let the gateway start one.
x-mission-control-session-id model requests and MCP tools/call Optional grouping under the key's server-resolved namespace. Model discovery ignores it; deployment invoke uses body threadId. See Session semantics.
x-mission-control-customer-subject Direct model/MCP Customer subject under the actual key namespace/assertion/provisioning policy; never a person or payer override. Managed invoke uses body customer:{subject}.
x-mc-tools: governed Chat Completions Attach the governed MCP tools you may call as function tools; see Governed tools on a model call.
x-mc-auto-execute Chat Completions Public tool names the gateway may run inside the call (comma-separated, or * for every autoExecute tool); absent means none.
x-mc-max-tool-rounds Chat Completions Provider rounds the loop may run, 1–20; default 5. Responses carries the same choices on its mcp tool object.
MCP-Protocol-Version: 2026-07-28 /mcp Required on every MCP request.
Mcp-Method /mcp Must equal the JSON-RPC method.
Mcp-Name /mcp tools/call Must equal params.name.
Mcp-Param-* /mcp tools/call Mirrors an argument whose schema property declares x-mcp-header.
Accept: application/json, text/event-stream /mcp Both media types, with positive q-values.
Origin browser callers Must be an exactly configured origin.

Response headers

Header Meaning
traceparent The gateway's request span in the Trace the response belongs to.
X-Mission-Control-Trace-Id The Trace ID to look up under Observe → Traces.
X-Mission-Control-Correlation-Id The correlation ID to quote to support; safe to log.
WWW-Authenticate On 401 from /mcp: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp", scope="mcp", plus error="invalid_token" when a credential was presented.
Retry-After On 429, when a safe retry time is known.

Error envelopes

Use the protocol's authoritative error contract rather than interpreting HTTP status alone: