Egress Gateway API reference
Connection, compatible request fields, errors, streaming, and usage for Cortex Egress Gateway.
- ConnectBase URLs, credentials, and headers
- Send requestsMessages, streaming, and tools
- Inspect responsesUsage, model IDs, and errors
This reference describes native OpenAI and Anthropic client requests through Egress Gateway. Use Egress Gateway for the first request and SDKs and AI tools for client-specific configuration.
Connect
Use CORTEX_API_KEY for your personal cct_ capture token. It is not an administrator-created cgw_ virtual key and it is not a provider API key. Cortex uses organization-managed provider credentials on the gateway.
| Client | CORTEX_BASE_URL value | Capture identity |
|---|---|---|
| curl | The complete request URL issued by your organization | Authorization: Bearer $CORTEX_API_KEY, or X-Chaos-Capture-Token when supported |
| OpenAI Python or TypeScript | The SDK base URL issued by your organization, ending in /gateway/v1 | Put CORTEX_API_KEY in the SDK API-key field |
| Anthropic Python | The SDK base URL issued by your organization, ending in /gateway | Set X-Chaos-Capture-Token in default_headers |
| Codex | The provider base URL issued by your organization, ending in /gateway/v1 | Set http_headers = { "X-Chaos-Capture-Token" = "<personal-capture-token>" } |
The curl URL is already a full request URL. SDK base URLs are already in the shape each client needs. Do not append /gateway, /gateway/v1, or a request suffix to a value that already includes it. Keep the capture token outside source control and client logs.
Cortex access, deployment, retention, and audit policies are organization controls. See Roles and visibility, deployment, and data flow and access.
Endpoints and request shape
| Operation | Compatible client shape | Notes |
|---|---|---|
| Chat Completions | An OpenAI SDK request through its /gateway/v1 base, or a curl request to the issued full URL | Use model and messages with an OpenAI-compatible provider path. |
| Responses | Codex through its /gateway/v1 base | Keep wire_api = "responses" and the capture header. See Codex setup. |
| Messages | An Anthropic SDK request through its /gateway base | Include X-Chaos-Capture-Token in default_headers and use an Anthropic-compatible model. |
Send an explicit organization-enabled model. The gateway uses the model's pricing row to choose an enabled provider; it does not translate arbitrary request formats between providers. cortex/auto is not a built-in alias. Auto Router uses managed configuration on qualified client paths, independently of these SDK forwarding examples.
| Field | Use |
|---|---|
model | An explicit model on the organization's pricing sheet, served by an enabled provider. |
messages | The role/content array for Chat Completions or Messages. Responses uses its native input shape. |
stream | Set to true for streaming on a supported provider path. |
max_tokens, temperature | Settings accepted by the native client and provider path. |
tools | Compatible tool definitions for that provider. |
response_format | Structured-output settings on provider paths that support them. |
A request routing object does not configure Smart Router. Provider ordering, candidate lists, and quality/cost objectives must not be sent as Cortex gateway controls.
Responses
For Chat Completions, read the message from choices[0].message.content and token counts from usage. For Anthropic Messages, read text blocks from content and token counts from usage.input_tokens and usage.output_tokens. The response model identifies the returned model.
Streaming, tools, and structured output
Streaming
Set stream: true in a compatible client to receive server-sent events. Handle an opened request, incremental deltas, and a terminal completion event. Render partial output as it arrives. Usage can arrive with the terminal event rather than each delta. Cancel from the client by aborting the request and record the request as cancelled or incomplete.
Tool calls and results
A compatible request can include tools; a compatible response can contain tool-call data. Validate every call before invoking it, execute the tool in your application, then send the tool result in the next compatible message. Preserve an idempotency boundary for tool actions that a retry could repeat.
Structured output
Send response_format on compatible paths and validate the result against your schema in the client.
Errors and limits
Model and capture-identity refusals use error.code and error.message. An unsupported endpoint returns plain text, unsupported relay endpoint, with HTTP 404. Other relay policy refusals can use a top-level code. Check the HTTP status and content type before parsing; preserve provider-native errors.
| Status | Code or response text | What to do | Retry unchanged? |
|---|---|---|---|
| 401 | capture_identity_token_* | Send a valid personal cct_ token in the expected credential field or capture header. | No |
| 400 | unknown_model | Choose a model on the organization pricing sheet. | No |
| 403 | provider_not_configured | Ask an administrator to enable an organization provider for that model. | No |
| 404 | unsupported relay endpoint | Use Egress Gateway with the issued URL and required native request suffix. A Defender endpoint does not serve this gateway route. | No |
For throttling, a timeout, or a context-size error, inspect the returned code and message, then apply bounded backoff or reduce the request as indicated.
Usage and routing
| Value | Meaning |
|---|---|
| Response ID | The id returned with a message or completion. |
| Requested model | The model sent by the client. |
| Recommended tier | The classifier's Easy, Medium, or Hard recommendation. Organization Router records expose tiers, not raw model IDs. |
| Forwarded model | The target placed in the outbound request after routing checks; local decision evidence can expose routed_model. |
| Response-reported model | The model returned in the provider response; it may be a versioned identifier. |
| Usage | Token values returned in usage for that response. |
| Atlas activity, if enabled | Captured activity under the capture-token owner. |
Use an explicit model and the issued Egress URL to check gateway forwarding. A returned response confirms that Egress Gateway forwarded the request. If your organization has Cortex Atlas enabled, check your Cortex Atlas profile for capture activity. Atlas is optional: Egress Gateway does not require an Atlas subscription. On a qualified Auto Router path, follow Inspect decisions and evaluate. A selected tier or a successful model response does not establish that routing was applied or capture reached Atlas.