Model APIs / Rerank

# Rerank

Order documents by relevance to a query and get back their indexes with a relevance score.

`POST` `/v1/rerank` `inference:invoke`[Browse rerank models →](https://yelno.ai/catalog?type=rerank)

## Request

| Field | Required | Notes |
| --- | --- | --- |
| model | required | A rerank model's id. |
| query | required | What the documents are ranked against. |
| documents | required | A list of strings, or objects `{text?, image?}`. |
| top_n | optional | How many results to return. |

Request

```
curl https://yelno.ai/v1/rerank \
  -H "Authorization: Bearer $YELNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL",
    "query": "How do I rotate an API key?",
    "documents": [
      "Keys are shown once, at creation.",
      "Rotate a key by creating a new one, then revoking the old one.",
      "Budgets can warn or block before dispatch."
    ],
    "top_n": 2
  }'
```

## Response

200 · application/json

```
{
  "results": [
    { "index": 1, "relevance_score": 0.93 },
    { "index": 0, "relevance_score": 0.41 }
  ],
  "usage": { … },
  "yelno": { … }
}
```

`index` points into your `documents`; `document` is included when the model returns it.

Every JSON response carries the same `yelno` block a chat response does: `request_id`, `provider`, `model`, `endpoint_id`, `attempts` and `cost`. `cost` is `{state: "final", currency, customer_nanos}` when the provider reported the cost with the response, or `{state: "pending", currency, note}` when it reports it later — the charge then settles once. Errors use the standard [error envelope](https://yelno.ai/docs/errors); upstream text never reaches you.

Sending a model to a route it is not served on answers `422` `capability_unsupported` with `code: "operation_unsupported"` and a message naming the route that serves it. Every model in the [catalog](https://yelno.ai/catalog?type=rerank) shows its type and route.

Pricing. You pay the model's listed final price — shown on its catalog page — and nothing on top. A model without a fixed unit price is billed per request: its exact charge comes back with every response in `yelno.cost`. A hold is placed before dispatch and released down to the final charge; when the charge is reported after the response, the request settles once — it is never charged a guess.

Source: https://yelno.ai/docs/rerank