---
title: "Chat Completions"
description: "POST /api/v1/router/chat/completions — OpenAI-compatible endpoint that routes and executes in one call."
canonical_url: "https://scholarxiv.com/developers/docs/router-api/completions"
markdown_url: "https://scholarxiv.com/developers/docs/router-api/completions.md"
---

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

# Chat Completions
URL: /developers/docs/router-api/completions
LLM index: /llms.txt
Description: POST /api/v1/router/chat/completions — OpenAI-compatible endpoint that routes and executes in one call.
Related: router-api/route, router-api/feedback

# Route and run

```http
POST /api/v1/router/chat/completions
```

OpenAI-compatible. Send `"model": "auto"` and the router picks; send a real model id and
that one runs, subject to your plan.

## Request body

| Field | Type | Description |
|---|---|---|
| `model` | string | `auto`, `auto:quality`, `auto:cheap`, or a concrete model id. Omit for `auto`. |
| `messages` | array | Required. Standard `{ role, content }` objects. |
| `models` | string[] | Restrict the routing pool (ignored when `model` is a concrete id). |
| `max_tokens` | number | Passed through to the model. |
| `temperature` | number | Passed through to the model. |

## Example

```bash title="completions.sh"
curl -X POST https://scholarxiv.com/api/v1/router/chat/completions \
  -H "x-api-key: sxv_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "Explain the difference between a hazard ratio and a risk ratio" }
    ]
  }'
```

```json title="response.json"
{
  "id": "router-…",
  "object": "chat.completion",
  "model": "alibaba/qwen3.5-flash",
  "decision_id": "8f2c…",
  "task": "factual_qa",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "…" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 41, "completion_tokens": 388, "total_tokens": 429 }
}
```

`model` in the response is always the model that **actually answered** — not what you
asked for. Log it: it's how you audit what the router is doing on your behalf.

## Notes

- Responses are non-streaming today. Use [`/api/v1/router`](/developers/docs/router-api/route)
  and call the model yourself if you need to stream.
- A concrete model id outside your plan returns `403` rather than silently downgrading,
  so you always know which model ran.
- `502` means the upstream model call failed. Retry with the next model from
  `fallbacks` on the decision endpoint.

## 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).