LLM router
The CortexHub LLM router is an OpenAI-compatible endpoint for language-model calls. Point any OpenAI client at it, ask for the model cortexhub/auto, and CortexHub picks a model per turn. Every call runs under your organisation's policy and is metered like the rest of your usage.
It is a separate surface from the MCP gateway: the gateway governs tool calls, the router governs model calls. Many applications use both - the router for generation, the gateway for actions.
Why route
| You get | Instead of |
|---|---|
| One endpoint and one credential for every model | A key and SDK per provider |
Per-turn model selection (cortexhub/auto) or a pinned model | Hard-coding one model everywhere |
| Calls governed by org policy and metered in one place | Separate billing and no central policy |
| Drop-in OpenAI Chat Completions and Responses shapes | Rewriting your client |
The interface
The router speaks the OpenAI HTTP API, served under https://api.cortexhub.ai/v1.
| Method | Path | Purpose |
|---|---|---|
GET | /models | List the models enabled for your org, plus cortexhub/auto |
POST | /chat/completions | OpenAI Chat Completions (streaming or single response) |
POST | /responses | OpenAI Responses |
Because the shapes match OpenAI's, existing clients and framework integrations work by changing only the base URL, the API key, and the model.
Model selection
cortexhub/auto(recommended): CortexHub chooses a model for each turn. This is the default in the SDK.- A pinned model: pass any id returned by
GET /modelsto force one model.
There is no implicit server default - the model field is required on every request.
Streaming
Set stream: true for Server-Sent Events, exactly as with OpenAI: a sequence of data: chunks ending with data: [DONE]. Set stream: false (the default on Chat Completions) for a single JSON response.
Governance and metering
Router calls are first-class org usage:
- Policy: calls run under the same organisation policy plane as the rest of CortexHub. A blocked model or a denied call returns an error rather than silently succeeding.
- Metering: input, output, and cache tokens are recorded per call and roll up into the same usage and billing views as your other spend.
Authentication
Two ways to reach the router:
| Path | Credential | Use when |
|---|---|---|
| Keyed (recommended for apps) | An org API key with router access, sent as Authorization: Bearer …, bound to an agent | Your backend or SDK calls the router directly |
| Platform API OAuth | A control-plane OAuth client with the org.router.invoke scope | You already use the Platform API and prefer OAuth |
The keyed path is the one the SDK uses and the simplest to adopt. The bound agent is the billed principal, so no per-request agent header is needed. See Authentication for how credentials are issued.
Next steps
- SDK: LLM router - call the router from Python in a few lines
- Usage - where router spend appears
- Authentication - issuing the credential