---
title: "Router API"
description: "Send a prompt, get the model that should answer it. The same routing engine that powers Auto mode in ScholarXIV chat and health."
canonical_url: "https://scholarxiv.com/developers/docs/router-api"
markdown_url: "https://scholarxiv.com/developers/docs/router-api.md"
---

> For the complete documentation index, see [llms.txt](/llms.txt).

# Router API
URL: /developers/docs/router-api
LLM index: /llms.txt
Description: Send a prompt, get the model that should answer it. The same routing engine that powers Auto mode in ScholarXIV chat and health.
Related: router-api/route, router-api/completions, router-api/feedback, router-api/dashboard

# Router API

Picking a model is a decision your users should not have to make, and one you should
not have to hardcode. The Router API reads a request and tells you which model to send
it to — weighing task type, difficulty, price, speed and measured reliability.

It's the same engine behind **Auto** mode in ScholarXIV's research and health chat.

## Two ways to use it

**Decide only** — `POST /api/v1/router` returns a model id and fallbacks. You call the
model yourself, on your own infrastructure, with your own keys.

**Decide and run** — `POST /api/v1/router/chat/completions` routes *and* executes, in an
OpenAI-compatible shape. Swap your base URL, set `"model": "auto"`, done.

## How a decision is made

1. **Constraints.** Models that can't serve the request are removed outright: no tool
   support when you need tools, no image/pdf input when you're sending a scan, not
   enough context for the prompt, or outside your plan.
2. **Classification.** A fast classifier assigns the request one of 14 task types
   (`research_synthesis`, `code`, `math_reasoning`, `vision_doc`, `trivial_chat`, …)
   plus a difficulty score.
3. **Scoring.** Survivors are ranked on quality, cost, speed and reliability, weighted
   by your chosen preset. Two guard rails bound the result: each task carries a
   **capability floor**, so a cheap preset can't answer a hard question with a weak
   model, and each plan carries a **per-request cost ceiling**, so a quality preset
   can't quietly spend frontier money on a long prompt. Both only ever filter — if
   nothing survives a guard rail, the closest candidate is used rather than failing.
4. **Fallbacks.** The top three come back ranked, so you can retry down the list.

## Presets

| Preset | Behavior |
|---|---|
| `quality` | Strongest model available for the task |
| `balanced` *(default)* | Frontier models when the task earns it, fast ones otherwise |
| `cheap` | Cheapest model that still clears the task's capability floor |

## Quick start

```bash title="route.sh"
curl -X POST https://scholarxiv.com/api/v1/router \
  -H "x-api-key: sxv_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Compare the endpoints used across these three cardiology RCTs",
    "preset": "balanced"
  }'
```

```json title="response.json"
{
  "decision_id": "8f2c…",
  "model": "google/gemini-3-flash",
  "fallbacks": ["alibaba/qwen3.7-plus", "xai/grok-4.1-fast-reasoning"],
  "task": "research_synthesis",
  "difficulty": 0.82,
  "preset": "balanced",
  "estimated_cost_usd": 0.00312,
  "candidates_considered": 47,
  "routing_latency_ms": 210,
  "degraded": false
}
```

## Billing and control

Two ways to pay, switched in the [developer dashboard](/developers/dashboard/router):

- **Your ScholarXIV subscription** — we bill it, and your plan decides which models
  the router can reach.
- **Your own AI Gateway key** — you pay the provider directly, and plan tiers stop
  restricting the pool. The key is verified before it is stored and encrypted at rest;
  it is never shown again.

The dashboard is also where you define **routing profiles**: named policies with an
allowed-model list, a default preset and a per-request cost ceiling. Point different
API keys at different profiles to run tiers of your own product through one router,
and watch per-key volume, spend, latency and model mix in the same place.

See [Dashboard](/developers/docs/router-api/dashboard) for the full walkthrough.

## Pricing

Routing decisions count against your regular API rate limit — there is no separate
per-decision charge. When you use `/chat/completions`, you pay the underlying model's
rate with no router surcharge.

## Close the loop

Send the `decision_id` back through
[the feedback endpoint](/developers/docs/router-api/feedback) when a routed answer was
regenerated, rejected, or worked well. Feedback is what turns the router's model
rankings from estimates into measurements.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).