> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ninjachat.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Smart routing
> Choose a model automatically, then select a provider for cost, speed and data policy.
Use `ninja/auto` to select a model for your request. Set `routing.strategy` to prioritize cost, latency, quality or a balanced approach. NinjaChat selects an available provider and can try another route if the request fails.
`GET /api/v1/models/ninja/auto` lists the router's current candidate pool under `router.candidates`; the per-request ranking comes back on every response under `routing.router`.
```typescript TypeScript SDK theme={null}
const response = await client.responses.create({
model: "ninja/auto",
input: "Review this repository migration plan.",
routing: {
strategy: "balanced",
allow_fallbacks: true,
data_policy: "zero_retention",
},
});
console.log(response.routing.resolved_model);
console.log(response.provider, response.cost_usd);
```
```python Python SDK theme={null}
response = client.responses.create(
model="ninja/auto",
input="Review this repository migration plan.",
routing={
"strategy": "balanced",
"allow_fallbacks": True,
"data_policy": "zero_retention",
},
)
print(response["routing"]["resolved_model"])
print(response["provider"], response["cost_usd"])
```
```bash cURL theme={null}
curl https://www.ninjachat.ai/api/v1/responses \
-H "Authorization: Bearer $NINJACHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model":"ninja/auto",
"input":"Review this repository migration plan.",
"routing":{"strategy":"balanced","allow_fallbacks":true,"data_policy":"zero_retention"}
}'
```
## Routing strategies
With `ninja/auto` the strategy picks the **model**; with a pinned model it orders the **provider rails** behind that model.
| Strategy | With `ninja/auto` (model choice) | With a pinned model (rail choice) | Reach for it when |
| ---------- | ----------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------- |
| `balanced` | Curated order for the detected task | Overall production fit | Default application traffic |
| `cost` | Cheapest model that clears the task's quality bar, by reference-request price | Lowest eligible rail cost | High-volume extraction and classification |
| `latency` | Lowest p50 latency measured from live traffic | Lowest observed latency | Interactive chat and tool loops |
| `quality` | Flagship first | Highest-quality eligible rail | Final answers and complex agent work |
**Billing:** you pay the resolved model and provider rail's published rate for actual token usage. The response identifies both, so cost attribution stays explicit. See [Pricing](/pricing) for the live catalog.
## Provider controls
`routing.providers` lets you include, exclude, or order provider rails without changing the public model ID. `data_policy` filters rails before ranking, and `require_parameters` rejects rails that cannot honor every requested feature.
```typescript TypeScript SDK theme={null}
const response = await client.responses.create({
model: "claude-sonnet-5",
input: "Draft a production rollout plan.",
routing: {
strategy: "latency",
providers: {
only: ["anthropic", "deepinfra", "gmicloud"],
order: ["anthropic", "deepinfra"],
},
allow_fallbacks: true,
require_parameters: true,
max_cost_usd: 0.08,
},
});
```
The response always tells you what ran:
```json theme={null}
{
"model": "claude-sonnet-5",
"provider": "anthropic",
"routing": {
"strategy": "latency",
"requested_models": ["claude-sonnet-5"],
"resolved_model": "claude-sonnet-5",
"provider": "anthropic",
"fallbacks_allowed": true,
"data_policy": "default"
}
}
```
When the request was `ninja/auto`, `model` and `routing.resolved_model` carry the concrete model that served it, `routing.requested_models` keeps `["ninja/auto"]`, and a `router` block explains the decision:
```json theme={null}
{
"model": "gemini-3-flash",
"provider": "google",
"routing": {
"strategy": "balanced",
"requested_models": ["ninja/auto"],
"resolved_model": "gemini-3-flash",
"provider": "google",
"fallbacks_allowed": true,
"data_policy": "default",
"router": {
"id": "ninja/auto",
"task": "summarize",
"classified_by": "regex",
"override": null,
"reasoning": "...",
"candidates": ["gemini-3-flash", "..."],
"considered": ["..."]
}
}
}
```
`task` is one of the task types above, `classified_by` is `regex`, `llm`, or `llm-cached`, `candidates` is the ranked chain the router would try in order, and `considered` lists every model it evaluated with the reason it was kept or eliminated. The same block is persisted on the request trace (`GET /requests/{id}`).
## Current frontier choices
The router tracks the live catalog rather than a hard-coded marketing table. Current leading options you can pin directly include `gpt-5.6-sol`, `gpt-5.5-pro`, `claude-fable-5`, `claude-opus-5`, `claude-sonnet-5`, `gemini-3.7-flash`, `gemini-3.1-pro`, `grok-4.6`, `deepseek-v4-pro`, `glm-5.2`, `minimax-m2.7`, and `qwen3-coder-next`. Fetch `/models` at runtime when you need a user-facing picker.
## Pair it with
`routing.max_cost_usd` caps each request
Explicit order with automatic failover
Evaluate important outputs before acceptance