---
title: "Rank Candidates"
method: POST
path: "/v1/routing/preferences/rank"
tags: ["routing"]
---

# Rank Candidates

`POST /v1/routing/preferences/rank`

Record scored examples: one routing-memory record each, plus an audit row.

The routing-memory record is written before its audit row for each example,
because it is the load-bearing one (the router votes over it) and embedding it
can fail; writing the audit row only afterwards means a failed embedding never
leaves an orphan audit row.

A failed embedding is a 502 that names the model, not a 500. Every example in
the batch is embedded, so this is the call an operator makes most often and the
one most likely to meet a misconfigured ``router_embedding_model``.

Score keys are stored canonically as ``instance:model`` (see
:func:`_validated_scores`), which is the form the router canonicalizes its
candidates to, so how a policy spells a candidate cannot decide whether it
matches.

## Request body

- RankRequest — Record how well each candidate did, for one or many prompts. A batch because of the arithmetic: a pool routes nothing until it holds ``router_seed_count`` examples (20 by default) and the vote reads the ``k`` nearest (5 by default), so a useful first teaching pass is dozens of examples across the kinds of prompt you care about.
  - `examples` ScoredExample[], required — The scored prompts to record.
    - `label_source` string — Provenance of the scores: 'human' or 'judge'.
    - `prompt` string, required — The prompt that was tried.
    - `scores` object, required — Selector -> quality in [0.0, 1.0], where 1.0 is a great answer. Ties are fine and meaningful: two models that both answered well is exactly the case where the router should take the cheaper one.
    - `task_id` string, nullable — Partition this example belongs to, matching the Otari-Router-Task header requests send. Omit to file it in the user's default pool.
  - `user_id` string, required — Whose routing memory these examples belong to.

## Response `200`

Successful Response

- RankResponse
  - `pools` RecordedPool[], required
    - `records` integer, required
    - `task_id` string, nullable, required
    - `warm` boolean, required
  - `recorded` integer, required
  - `seed_count` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mozilla-ai/apis/otari.md) · [All operations](https://skmtc.net/mozilla-ai/apis/otari/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mozilla-ai/otari/revisions/3945cde96091/schema)