Create a chat completion
POST/v1/chat/completions
Routes an inference request to an AI provider via the Routing Service and returns a response.
With model: "auto", Artemis Task picks the model: it reads the prompt's task types, estimates each pool
model's score for it and picks by the preset your strategy selects (balanced → Balanced, highest_quality →
Quality-first, cheapest → Cost-first, fastest → Balanced at speed Fastest, or Fastest on a capability
version without a speed table). "auto-artemis-task" and "auto-v2" mean the same as "auto". When Artemis
Task cannot decide, fallback-router:apollo decides and X-Router-Fallback
says why. The fallback router cannot be chosen: "auto-apollo-tier" and "auto-v1" are a 400. Your
governance policy applies whichever router decides.
Responses carry these headers:
| Header | Meaning |
|---|---|
X-Router-Model | The model served |
X-Router-Version | The router that decided a model: "auto" request: v2 (Artemis Task) or v1 (fallback-router:apollo) |
X-Router-Capability-Version | The capability version Artemis Task decided with, e.g. cap-6 |
X-Router-Fallback | Why fallback-router:apollo decided instead of Artemis Task (see _routing.routerFallback) |
X-Router-Tier | fallback-router:apollo only: its predicted tier for the prompt (0 small, 1 medium, 2 large) |
X-Router-Confidence | fallback-router:apollo only: its probability for that tier |
X-Router-Tier-Escalated | fallback-router:apollo only: the tier served, when it was higher than the predicted tier |
X-Router-Estimated-Saving | Estimated fraction saved versus the large-tier reference model, from the served model's price |
Streamed responses carry the same headers.
For a specific model, pass its identifier (e.g. gpt-4o, claude-sonnet-4-6) — the
Routing Service will select the appropriate provider automatically.
Use the optional provider field to pin a specific provider: no router runs. Combined with
model: "auto", that provider serves its default model (the first it lists); name a model to choose it.
Set stream: true to receive a server-sent events (SSE) stream.
A project's policy and budget apply to its requests (those of a project-scoped API key, or naming the project
with X-NuRoute-Project-ID). A model or provider its policy rules out is 403 policy_violation; with model: "auto" the routers pick only models, providers and regions it allows (422 no_available_model when none can
serve). A max_tokens over the policy's limit is 400 invalid_request_error; without max_tokens the provider
is asked for at most that limit. Once a hard-limited monthly budget is spent (UTC calendar month), requests are
402 budget_exceeded.
Requires Authorization: Bearer <token> where <token> is a JWT session token or an aicp-* API key.
Request
Responses
- 200
Default Response