Routing decision

POST /api/v1/route asks which model should serve a call and executes nothing. Use it when your own code runs the model: local models, your own provider accounts, or a client you cannot repoint. How routers, tiers, Smart routing and Automatic updates decide is on Model routing.

Request

Body: { "messages": [...] } or { "task": "summarize this doc" }, plus an optional "session_id" (up to 200 characters) and an optional "model": naming a model decides through that model’s anchored router, exactly as naming it on chat completions does. Bodies cap at 128 KB.

const res = await fetch("https://platform.belvedir.ai/api/v1/route", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.BELVEDIR_API_KEY,
  },
  body: JSON.stringify({ messages, session_id: sessionId }),
});
const route = await res.json();
const model = route.configured ? route.model : "qwen3:4b"; // local fallback

Response

{
  "configured": true,
  "model": "zai-org/GLM-5.2-FP8",
  "tier": "default",
  "matched_group": null,
  "complexity": 0.35,
  "reason": "...",
  "router_id": "...",
  "anchor_model": null
}

Field	Meaning
`configured`	`false` when the project has no router; the call still returns `200`, so keep a local fallback model
`model`	the model to serve the call with
`tier`	why it was chosen (below)
`matched_group`	`{ id, label }` when a task group matched, else `null`
`complexity`	the request’s difficulty score
`router_id`	the router that decided
`anchor_model`	set when the router is anchored on a model your code named

tier values:

Tier	Meaning
`group`	a task group you assigned a model to matched
`group-record`	Automatic updates picked the model from the task group’s recorded results
`strong`	the request scored as hard, so the Big model serves it
`small`	the request is a quick machine task and a Small model is set
`pinned`	an earlier decision for the same `session_id` was replayed (below)
`fixed`	Smart routing is off, so the named model (or the Medium model, for `auto`) is served with no substitution
`default`	the Medium model

Session pinning

Pass your SDK session id as session_id and the session’s first decision sticks: repeat calls return the same model as tier: "pinned" for up to 24 hours, keeping a conversation consistent and prompt caches warm. Changing a router releases stale pins (a pinned model no longer in the config is re-decided).

Overview

Tracing

Inference

Request

Response

Session pinning

​Request

​Response

​Session pinning

Request

Response

Session pinning