# Ranking

`POST /v1/rerank` orders your documents by how well each answers one question, with a score for
each and what it cost.

## Request

Send it with an API key, as JSON. The [Rerank](/docs/rerank) guide shows it at work. Souk Bot
sends a customer's question and the passages of the shop's help pages; the answer lists the
passages best first, each under its place in what you sent.

| Field | Needed | You send |
|---|---|---|
| `model` | yes | a rerank model, `lab/model`. It also picks the meter: some models count searches, others tokens |
| `query` | yes | the question the documents are ranked against |
| `documents` | yes | one or more documents: each a string, or `{"text": "...", "image": "..."}` where the model reads pictures, the picture as a public link or a `data:image/...` address |
| `top_n` | no | how many results come back, best first; absent, every document. Every document sent is scored either way |
| `provider` | no | which providers may serve it: `only` and `order` name them, `sort` ranks them by `price`, `throughput` or `latency`, and `max_price` caps the price the router may pick, in DA |
| `user` | no | your own id for the person behind the request |
| `session_id` | no | your own id grouping related requests, never sent to the model |

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/rerank"
MODEL = "cohere/rerank-4-pro"

documents = [
    "A cancelled order refunds the deposit within 14 days.",
    "Delivery outside Algiers takes three to five days.",
    "Refunds return to the original payment method.",
]

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "query": "Is the deposit refundable if I cancel?",
            "documents": documents,
            "top_n": 2,
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

for result in answer["results"]:
    print(result["relevance_score"], documents[result["index"]])
print(answer["usage"]["cost"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/rerank";
const MODEL = "cohere/rerank-4-pro";

const documents = [
  "A cancelled order refunds the deposit within 14 days.",
  "Delivery outside Algiers takes three to five days.",
  "Refunds return to the original payment method.",
];

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    query: "Is the deposit refundable if I cancel?",
    documents,
    top_n: 2,
  }),
});
const answer = await response.json();

for (const result of answer.results) {
  console.log(result.relevance_score, documents[result.index]);
}
console.log(answer.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address = "https://opendunes.com/v1/rerank"
	model   = "cohere/rerank-4-pro"
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	documents := []string{
		"A cancelled order refunds the deposit within 14 days.",
		"Delivery outside Algiers takes three to five days.",
		"Refunds return to the original payment method.",
	}
	body, err := json.Marshal(map[string]any{
		"model":     model,
		"query":     "Is the deposit refundable if I cancel?",
		"documents": documents,
		"top_n":     2,
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var answer struct {
		Results []struct {
			Index          int     `json:"index"`
			RelevanceScore float64 `json:"relevance_score"`
		} `json:"results"`
		Usage struct {
			Cost float64 `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}
	for _, result := range answer.Results {
		fmt.Println(result.RelevanceScore, documents[result.Index])
	}
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/rerank"
MODEL="cohere/rerank-4-pro"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "query": "Is the deposit refundable if I cancel?",
    "documents": [
      "A cancelled order refunds the deposit within 14 days.",
      "Delivery outside Algiers takes three to five days.",
      "Refunds return to the original payment method."
    ],
    "top_n": 2
  }'
```

## Response

`200 OK`, once every document is scored.

| Field | Holds |
|---|---|
| `id` | the receipt handle, read back with `GET /v1/generation` |
| `model` | the model that ranked them, `lab/model` |
| `provider` | the provider that served it, when it is named |
| `results` | the documents, best first: `top_n` entries, or one per document sent |
| `index` | in each entry: the document's place in what you sent, from 0 |
| `relevance_score` | in each entry: how well the document answers `query`; higher is better |
| `document` | in each entry: the document as sent, its `text`, and its `image` where it carried one |
| `usage` | what was counted, and the charge |
| `search_units` | the searches counted, on a model that counts searches |
| `total_tokens` | the tokens read, the query and the documents together |
| `cost` | the charge, in DA |

Two headers ride the answer: `X-Generation-Id`, the receipt handle, and `X-Balance-Available`,
your balance after this charge, in µDA.

## What it cost

Charged in DA from your balance the moment the answer ends, on the model's own meter: its
searches, `usage.search_units`, or its tokens, `usage.total_tokens`. Both counters ride every
answer; the model's page shows which one it charges and at what rate. `usage.cost` carries the
charge.

- **Picks the price**: `model`, which also picks the meter.
- **Moves the count**: `query` and `documents`. On a model that counts searches, a long document
  is cut into pieces first and each piece counts toward the documents one search covers, so long
  documents can take more than one search.
- **Changes the answer, never the bill**: `top_n`. Every document sent is scored and counted,
  however few results come back.

Nothing that comes back is counted. Nothing is charged when the provider fails before it answers.
An answer with no result still charges the documents that were scored.

## Errors

The body says why.

| Status | When |
|---|---|
| 400 | `model`, `query` or `documents` is missing, `documents` is empty, a document is neither a string nor an object, or a field has the wrong type |
| 401 | the key is missing, wrong, disabled or expired |
| 402 | your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; `error.metadata.limit_source` names which, and `deposit_url` or `key_url` says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries `Retry-After: 60` |
| 403 | the key is kept to other models or other addresses, a guardrail's budget is spent, or a guardrail or a filter blocked the request |
| 404 | `model` is not a rerank model on sale, or no provider serves it |
| 502 | the provider failed, or answered with nothing usable |
