Download OpenAPI specification:Download
The data plane: how an application sends governed LLM and MCP traffic through Cortega. Requests are proxied to upstream providers and MCP servers after Cortega authenticates the caller, resolves the model, enforces budgets, guardrails, and authorization, and records telemetry.
This is separate from the Analytics API,
which reads usage and agent verdicts back out. Different token, different
audience: the gateway takes a virtual key (ck_...), the Analytics API
takes a management API key (crt_...).
Cortega terminates the OpenAI and Anthropic wire formats. Point your existing SDK at the gateway and use a virtual key as the API key:
export OPENAI_BASE_URL="<LLM URL from Console → Client Setup>/v1"
export OPENAI_API_KEY="ck_..."
# or
export ANTHROPIC_BASE_URL="<LLM URL from Console → Client Setup>"
export ANTHROPIC_API_KEY="ck_..."
The base URL differs per install (a local stack uses an internal service name; a hosted install uses a public hostname or load balancer). The MCP URL is a separate URL, also shown in Client Setup.
The request and response bodies for chat/completions, responses, and
messages are the provider's, not Cortega's — see the linked provider docs.
This spec covers what Cortega adds: the virtual-key auth, the optional
Cortega request headers, the models list, the MCP endpoint, and the error
responses Cortega itself returns.
Proxied to the resolved model's provider. The request and response bodies are OpenAI's; model may be a concrete model name or a Cortega virtual model name. Streaming (stream: true) is passed through as SSE.
| X-Cortega-Application | string A stable name for the calling workload, shown in Observability as the Agent Stack. |
| X-Your-App-Id-Header | string If you registered an Agentic Application, the request header you chose (for example |
| X-Cortega-Upstream-Authorization | string Only for a provider configured with credential source "client-supplied upstream credential". Carries your own provider key; Cortega rewrites it to the provider-native header and strips this one. Sending it to a stored-credential provider is refused with 403 unless substitution was explicitly allowed. The header name is configurable per install. |
| model required | string A configured model name or a Cortega virtual model name. |
| messages required | Array of objects OpenAI message objects. |
| stream | boolean |
| property name* additional property | any |
{- "model": "string",
- "messages": [
- { }
], - "stream": true
}{ }Proxied like chat/completions. Not supported when the resolved model routes to an Anthropic provider — the gateway returns an unsupported-conversion error; use chat/completions or messages for Anthropic-backed models.
| X-Cortega-Application | string A stable name for the calling workload, shown in Observability as the Agent Stack. |
| X-Your-App-Id-Header | string If you registered an Agentic Application, the request header you chose (for example |
| property name* additional property | any |
{ }{ }Proxied to the resolved model's provider. The request and response bodies are Anthropic's. Works for Anthropic destinations and for non-Anthropic models the gateway can convert to.
| X-Cortega-Application | string A stable name for the calling workload, shown in Observability as the Agent Stack. |
| X-Your-App-Id-Header | string If you registered an Agentic Application, the request header you chose (for example |
| X-Cortega-Upstream-Authorization | string Only for a provider configured with credential source "client-supplied upstream credential". Carries your own provider key; Cortega rewrites it to the provider-native header and strips this one. Sending it to a stored-credential provider is refused with 403 unless substitution was explicitly allowed. The header name is configurable per install. |
| property name* additional property | any |
{ }{ }OpenAI-compatible models list, filtered to what the virtual key's team is authorized for (concrete models plus any virtual model names).
{- "object": "list",
- "data": [
- {
- "id": "gpt-4o",
- "object": "model",
- "owned_by": "cortega"
}, - {
- "id": "claude-sonnet-4-6",
- "object": "model",
- "owned_by": "cortega"
}, - {
- "id": "smart",
- "object": "model",
- "owned_by": "cortega"
}
]
}A single Model Context Protocol endpoint that multiplexes every MCP server the caller's team is authorized for. Point an MCP client at the MCP URL from Client Setup with the virtual key as a bearer token.
initialize / tools/list / tools/call fan out to the authorized upstream servers; tools/list is filtered to the tools the team is granted. A tool call the team is not authorized for is refused with JSON-RPC error -32001. Request and response bodies are MCP JSON-RPC and are not modelled here.
An MCP JSON-RPC request.
{ }