---
title: "Route"
method: POST
path: "/v1/route"
tags: ["router"]
---

# Route

`POST /v1/route`

Score one request against the chosen router (POC, feature-flagged).

Args:
    request: The routing request (``router_type`` + messages/prompt + knobs).
    auth: The authenticated caller; its team scopes the release flag.

Returns:
    The router's decision, or a conservative fallback route on upstream
    failure (the endpoint never 5xxs on a routing error).

Raises:
    HTTPException: 404 when ``router_type`` is unknown or not released to the
        caller's team (keeps the surface invisible to non-POC teams and
        reveals nothing about which routers exist).

## Request body

- RouteRequest — One routing request for a named model-selection router. Either ``messages`` (OpenAI-shape chat turns) or ``prompt`` (a single user string) identifies the request text; ``messages`` wins when both are set. Exactly one of the two must be non-empty. Every routing knob is optional and falls back to the router's deployed default. Attributes: router_type: Registry id of the router to score with (e.g. ``general``). messages: OpenAI-shape chat messages to route. prompt: Single user prompt, used when ``messages`` is absent. threshold: Minimum calibrated success probability for a candidate (code/auto router family only; ignored where unused). max_regret: Allowed probability gap below the top candidate (code/auto router family only; ignored where unused). alpha: LinUCB exploration weight (router-specific; ignored where unused). lambda_cost: Cost weight in the general router's ``q - cost*lambda`` policy (general router only; ignored where unused). allowed_models: Optional catalog-id subset the router may select between. actual_model: Catalog model the caller would otherwise use, for regret.
  - `router_type` string, required
  - `messages` object[], nullable
  - `prompt` string, nullable
  - `threshold` number, nullable
  - `max_regret` number, nullable
  - `alpha` number, nullable
  - `lambda_cost` number, nullable
  - `allowed_models` string[], nullable
  - `actual_model` string, nullable

## Response `200`

Successful Response

- RouteResponse — A router's decision for one request. Every model id is a standard Pioneer catalog id (the router normalizes its internal slugs before responding). Attributes: model: Chosen catalog model id, or ``None`` when the router declined. confidence: Calibrated success probability of the chosen candidate. expected_cost_usd: Router's expected cost for the chosen candidate. rule: Decision-rule label that fired. reason_codes: Diagnostic reason codes the router attached. policy_version: Deployed policy version that produced the decision. candidates: Per-candidate score rows the router considered.
  - `model` string, nullable
  - `confidence` number, nullable
  - `expected_cost_usd` number, nullable
  - `rule` string, nullable
  - `reason_codes` string[]
  - `policy_version` string, nullable
  - `candidates` object[]

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/pioneer/apis/brain-api.md) · [All operations](https://skmtc.net/pioneer/apis/brain-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pioneer/brain-api/revisions/31dfe831e079/schema)