# Rank documents

Cohere v2-style scores with gateway extensions for text objects, returned documents and
exact EUR usage. At most 1000 documents, 64 KiB per query/document and 4 MiB of combined
text. No streaming. `top_n` is applied locally; original documents are always returned,
without forwarding application metadata upstream. The legacy `return_documents` flag
does not suppress the required document field. Scores are sorted descending, ties by original index.
Unknown response fields are tolerated and discarded. Unknown request fields are ignored
with `x-ignored-params`. All invalid fields are collected before contacting a provider.
Token-priced routes require reported usage; routes without usage may only have a fixed
request price. Their token estimate is explicitly marked in `usage.estimated`.

Administrative PII requirements are checked for each actual route, including fallbacks
and retries. This endpoint cannot redact its input: a matching requirement returns
`invalid_parameter` with a `not_available` issue at `$.model` before provider I/O.

`POST https://api.tokenlane.de/v1/rerank`

## Authorizations

[
  [
    {
      "name": "Authorization",
      "description": "API key as bearer token in the `Authorization` header: `Authorization: Bearer sk-tl-v1-…`. Existing `sk-eu-` keys remain valid. Missing, unknown or expired keys get 401 `authentication`.",
      "type": "http bearer",
      "location": "",
      "scopes": []
    }
  ]
]

## curl

```curl
curl --request POST \
  --url 'https://api.tokenlane.de/v1/rerank' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "documents": [
    "Paris is in France.",
    {
      "text": "A recipe.",
      "title": "Cooking"
    }
  ],
  "model": "baai/bge-reranker-v2-m3",
  "query": "European capital",
  "return_documents": true,
  "top_n": 1
}'
```

## node

```node
const response = await fetch("https://api.tokenlane.de/v1/rerank", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "documents": [
    "Paris is in France.",
    {
      "text": "A recipe.",
      "title": "Cooking"
    }
  ],
  "model": "baai/bge-reranker-v2-m3",
  "query": "European capital",
  "return_documents": true,
  "top_n": 1
}`,
});
console.log(await response.text());
```

## python

```python
import os
import urllib.request

body = (r'''{
  "documents": [
    "Paris is in France.",
    {
      "text": "A recipe.",
      "title": "Cooking"
    }
  ],
  "model": "baai/bge-reranker-v2-m3",
  "query": "European capital",
  "return_documents": true,
  "top_n": 1
}''').encode("utf-8")

request = urllib.request.Request(
    "https://api.tokenlane.de/v1/rerank",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
        "Content-Type": "application/json",
    },
    data=body,
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))
```

## vercel

```vercel
// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/rerank", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "documents": [
    "Paris is in France.",
    {
      "text": "A recipe.",
      "title": "Cooking"
    }
  ],
  "model": "baai/bge-reranker-v2-m3",
  "query": "European capital",
  "return_documents": true,
  "top_n": 1
}`,
});
console.log(await response.text());
```

## header: Idempotency-Key (optional)

Explicit opt-in to encrypted response replay across gateway nodes. One 1..=255 printable ASCII value per logical operation, scoped to this API key ID. Reuse the same method, path and normalized body. Completed responses are retained for at most 10 minutes; replay is free and creates no generation. Conflicting content or unavailable replay returns 409. A successful replay carries Idempotent-Replayed: true and preserves the original request and generation IDs. See /docs/guides/idempotency.

### s0: string | null

{}

## Body: application/json

```json
{
  "documents": [
    "Paris is in France.",
    {
      "text": "A recipe.",
      "title": "Cooking"
    }
  ],
  "model": "baai/bge-reranker-v2-m3",
  "query": "European capital",
  "return_documents": true,
  "top_n": 1
}
```

### s30: object

Ranks up to 1000 documents against one nonempty query. Text is limited to 64 KiB per
query/document and 4 MiB combined; additional object metadata shares the body budget.

{}

```json
{
  "documents": [
    "Paris is in France.",
    {
      "text": "A recipe.",
      "title": "Cooking"
    }
  ],
  "model": "baai/bge-reranker-v2-m3",
  "query": "European capital",
  "return_documents": true,
  "top_n": 1
}
```

- documents (required): s361

### s361: array

At most 1000 text documents or text objects; metadata is returned locally. Image document syntax is recognized but unavailable on the configured text-only routes, never silently discarded or downloaded.

{"minItems":"1","maxItems":"1000"}

### s1074: anyOf

One input document; arbitrary object metadata is preserved locally, never forwarded.

{}

anyOf: s7

### s7: string

{}

anyOf: s1265

### s1265: object

Object containing text and/or image, with optional application metadata.

{}

- image (optional): s958

### s958: string

Image URL or data URI; recognized but not fetched by text-only adapters.

{}

- text (optional): s959

### s959: string

Document text, retained locally for the response.

{}

- model (required): s362

### s362: string

Public reranking model ID or alias. Other endpoint protocols are not eligible.

{}

```json
"baai/bge-reranker-v2-m3"
```

- provider (optional): s363

### s363: object

Provider selection, fallback, data restrictions and maximum EUR token prices.

{}

- query (required): s364

### s364: string

Nonempty query, at most 65536 UTF-8 bytes.

{}

```json
"European capital"
```

- return_documents (optional): s365

### s365: boolean

Legacy compatibility flag; documents are always returned as required by OpenRouter.
Strings are returned as objects with a `text` field.

{}

- top_n (optional): s366

### s366: integer

Number of results, from one through the document count (at most 1000); defaults to all documents. JSON integers have no fixed-width wire format.

{"minimum":"1","maximum":"1000"}

```json
1
```

## Response 200: application/json

Ranked results and exact EUR usage; x-generation-id identifies the persisted rerank generation

```json
{
  "id": "gen-01k7tm9qz3f5c8x2v6b4n0m7hd",
  "model": "baai/bge-reranker-v2-m3",
  "provider": "eu-provider",
  "results": [
    {
      "document": {
        "text": "Paris is in France."
      },
      "index": 0,
      "relevance_score": 0.9
    }
  ],
  "usage": {
    "cost": 0.00005,
    "currency": "EUR",
    "estimated": true,
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}
```

### s31: object

Descending relevance ranking. Equal scores retain original document order.

{}

```json
{
  "id": "gen-01k7tm9qz3f5c8x2v6b4n0m7hd",
  "model": "baai/bge-reranker-v2-m3",
  "provider": "eu-provider",
  "results": [
    {
      "document": {
        "text": "Paris is in France."
      },
      "index": 0,
      "relevance_score": 0.9
    }
  ],
  "usage": {
    "cost": 0.00005,
    "currency": "EUR",
    "estimated": true,
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}
```

- id (required): s367

### s367: string

Gateway generation ID, also returned in `x-generation-id`.

{}

```json
"gen-01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- model (required): s368

### s368: string

Resolved public model ID.

{}

```json
"baai/bge-reranker-v2-m3"
```

- provider (required): s369

### s369: string

Configured provider identifier, never arbitrary upstream text.

{}

```json
"eu-provider"
```

- results (required): s370

### s370: array

Unique original document indices, sorted by decreasing finite score in [0, 1].

{}

### s194: object

One ranked document.

{}

```json
{
  "document": {
    "text": "Paris is in France."
  },
  "index": 0,
  "relevance_score": 0.9
}
```

- document (required): s960

### s960: object

Original document as an object; strings are wrapped in a `text` field.

{}

```json
{
  "text": "Paris is in France."
}
```

- text (required): s963

### s963: string

Nonempty UTF-8 text, at most 65536 bytes.

{}

```json
"Paris is in France."
```

- * (optional): s964

### s964: any

Original metadata returned locally, without interpreting or forwarding its contents.

{}

- index (required): s961

### s961: integer

Zero-based position in the submitted documents.

int32

{"minimum":"0"}

```json
0
```

- relevance_score (required): s962

### s962: number

Finite relevance score from zero through one; this is not a probability guarantee.

double

{"minimum":"0","maximum":"1"}

```json
0.9
```

- usage (required): s371

### s371: object

Reported or explicitly estimated input tokens, with an exact EUR charge.

{}

```json
{
  "cost": 0.00005,
  "currency": "EUR",
  "estimated": true,
  "prompt_tokens": 8,
  "total_tokens": 8
}
```

- cost (required): s965

### s965: number

Gateway-computed charge in EUR, represented exactly as a JSON decimal number.

double

{}

```json
0.00005
```

- currency (required): s966

### s966: string

Always EUR.

{}

```json
"EUR"
```

- estimated (required): s967

### s967: boolean

True only for a documented local estimate on a fixed-price route.

{}

- prompt_tokens (required): s968

### s968: integer

Input tokens; without native usage, query plus document bytes divided by four per pair.

int64

{"minimum":"0"}

```json
8
```

- total_tokens (required): s969

### s969: integer

Same as input tokens: reranking does not generate output tokens.

int64

{"minimum":"0"}

```json
8
```

- * (optional): s970

### s970: any

Exact cost components and other gateway billing fields.

{}

## Response 400: application/json

Recognized upstream 400/422 request rejections are non-retryable client errors. Invalid JSON, invalid fields with collected issues, unknown model, or context limit exceeded

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

### s3: object

Every response with an HTTP status of 400 or higher has this shape, OpenRouter's error
format. Everything the gateway adds is inside `error.metadata`, so OpenRouter clients see
nothing unfamiliar. See "Errors" in the introduction for all error types.

{}

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

- error (required): s238

### s238: object

What went wrong.

{}

```json
{
  "code": 400,
  "message": "temperature must be at most 2, got 5 (and 1 more)",
  "metadata": {
    "docs_url": "/docs#description/invalid-parameter",
    "issues": [
      {
        "code": "out_of_range",
        "message": "temperature must be at most 2, got 5",
        "path": "$.temperature"
      },
      {
        "code": "invalid_value",
        "message": "messages[1].role must be one of system, developer, user, assistant, tool, got \"bot\"",
        "path": "$.messages[1].role"
      }
    ],
    "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
    "retryable": false,
    "type": "invalid_parameter"
  }
}
```

- code (required): s633

### s633: integer

The HTTP status of the response, as a number.

int32

{"minimum":"0"}

```json
400
```

- message (required): s634

### s634: string

What went wrong, in English. With several problems: the first one and how many more
follow; all of them are in `metadata.issues`. The text may change; match on
`metadata.type` instead.

{}

```json
"temperature must be at most 2, got 5"
```

- metadata (optional): s635

### s635: object

Details for programs: error type, request ID, every problem, a suggested fix and, for
provider errors, which provider failed. Always present on gateway errors.

{}

```json
{
  "docs_url": "/docs#description/rate-limited",
  "provider_error": {
    "category": "rate_limited",
    "provider_name": "deepinfra",
    "retry_after": 2,
    "retryable": true,
    "status": 429
  },
  "provider_name": "deepinfra",
  "remedy_hint": "Retry after the Retry-After interval, or allow fallbacks to other providers (provider.allow_fallbacks).",
  "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
  "retry_after": 2,
  "retryable": true,
  "type": "rate_limited"
}
```

- available_providers (optional): s639

### s639: array

Providers that serve the model (when `provider.only` excluded all of them).

{}

```json
[
  "deepinfra",
  "open-inference"
]
```

- docs_url (required): s640

### s640: string

Link to the section of this error type in the documentation.

{}

```json
"/docs#description/model-not-found"
```

- failed_routing_step (optional): s641

### s641: string

The routing step that left no route (routing errors only).

{}

```json
"Filter by Max Price"
```

- issues (optional): s642

### s642: array

Every problem found in the request, so all can be fixed at once (at most 20); for
routing errors one entry per excluded route, for `no_provider_available` one per failed
attempt.

{}

### s123: object

One problem in the request, one reason a route was excluded, or one failed attempt.

{}

```json
{
  "code": "invalid_url",
  "message": "messages[2].content[0].image_url.url must be an http(s) URL or a base64 data URL",
  "path": "$.messages[2].content[0].image_url.url"
}
```

- code (required): s636

### s636: string

Kind of problem, stable for programs.

"required", "invalid_type", "invalid_value", "out_of_range", "empty", "invalid_url", "invalid_base64", "unsupported_media_type", "media_type_mismatch", "media_too_large", "too_many_media", "unsupported_media_transport", "media_fetch_failed", "unknown_tool", "unknown_model", "not_available", "not_allowed", "route_excluded", "bridge_failed", "provider_failed"

{}

```json
"out_of_range"
```

- message (required): s637

### s637: string

The problem in English, naming the field and, if short, the value sent.

{}

```json
"temperature must be at most 2, got 5"
```

- path (required): s638

### s638: string

Where the problem is: JSONPath of the field in the request body, for example
`$.messages[2].content[0].image_url.url`, or `query.<name>` for a query parameter.

{}

```json
"$.temperature"
```

- provider_error (optional): s643

### s643: oneOf

Safe provider diagnostics, identical for HTTP errors and terminal stream events.

{}

oneOf: s1158

### s1158: object

Provider diagnostics without provider-authored text. HTTP and terminal SSE errors use
this same structure; arbitrary upstream messages and metadata are discarded.

{}

```json
{
  "category": "rate_limited",
  "provider_name": "deepinfra",
  "retry_after": 2,
  "retryable": true,
  "status": 429
}
```

- category (required): s1299

### s1299: string

Gateway classification from HTTP status and recognized dialect identifiers.

"rate_limited", "overloaded", "invalid_request", "context_length", "content_filtered", "authentication", "billing", "timeout", "unavailable", "unknown"

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exact identifier from the configured dialect's fixed list; arbitrary values vanish.

{}

```json
"rate_limit_exceeded"
```

- provider_name (required): s1301

### s1301: string

Configured provider name, never a name supplied by the upstream body.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Bounded seconds from the upstream Retry-After header, when present and numeric.

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s1303

### s1303: boolean

Whether the classified failure can be transient. Unknown failures are not promised retryable.

{}

- status (optional): s1304

### s1304: integer

Actual HTTP status received from the upstream, including 200 for native errors.
Absent when no HTTP status is available.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

### s588: null

{}

- provider_name (optional): s644

### s644: string

The provider that failed, as in the response field `provider` (provider errors only).

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserved OpenRouter compatibility field. The gateway never fills it: provider
free text is deliberately withheld. Use provider_error instead.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

A concrete fix, for example the closest model ID to a mistyped one.

{}

```json
"Did you mean deepseek/deepseek-v4.1-flash?"
```

- request_id (required): s647

### s647: string

ID of the request, the same as the `x-request-id` response header. Quote it when
contacting support.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Providers named in `provider.only` (when it excluded all routes).

{}

```json
[
  "scaleway"
]
```

- retry_after (optional): s649

### s649: integer

Seconds to wait before retrying; also sent as the `Retry-After` header (429 and 503).

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s650

### s650: boolean

Whether sending the identical request again can succeed (for example after a timeout
or rate limit), as opposed to errors that need a changed request.

{}

- routing_funnel (optional): s651

### s651: array

How routing narrowed down the providers: each step with the number of routes left
(routing errors only, same format as OpenRouter).

{}

### s200: object

One routing step, as in OpenRouter's `routing_funnel`.

{}

```json
{
  "endpoint_count": 0,
  "reason": "provider.max_price",
  "step": "Filter by Max Price"
}
```

- endpoint_count (required): s979

### s979: integer

Number of routes (providers of the model) left after the step.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

The request field the step filtered on.

{}

```json
"provider.only"
```

- step (required): s981

### s981: string

Name of the step, as at OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (required): s652

### s652: string

Stable error type to match on in code; see "Errors" in the introduction. Messages may
change, the type does not.

"invalid_request", "invalid_parameter", "unsupported_parameter", "context_length_exceeded", "authentication", "insufficient_credits", "workspace_budget_exceeded", "permission_denied", "moderation", "model_not_found", "no_endpoint", "not_found", "method_not_allowed", "timeout", "payload_too_large", "media_fetch_failed", "rate_limited", "provider_error", "idempotency_conflict", "idempotency_in_progress", "idempotency_unavailable", "provider_invalid_response", "no_provider_available", "byok_invalid_credential", "byok_rate_limited", "byok_unavailable", "feature_unavailable", "internal"

{}

```json
"invalid_parameter"
```

- user_id (optional): s239

### s239: string | null

Organization of the API key, if the key was recognized.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## Response 401: application/json

Missing, invalid or expired API key

## Response 402: application/json

Insufficient key or organization credit for the bounded reservation

## Response 403: application/json

Organization, workspace or key policy forbids this model

## Response 404: application/json

No eligible reranking route; metadata.issues explains route exclusions

## Response 408: application/json

Request upload or upstream response timed out

## Response 409: application/json

idempotency_conflict: this key has different request content; use a new key. idempotency_in_progress: the original is running; respect Retry-After. idempotency_unavailable: no safe replay is possible; do not silently recompute. See remedy_hint.

## Response 413: application/json

Body or parsed JSON exceeds its memory limit

## Response 429: application/json

Customer or provider rate limit; Retry-After gives seconds to wait

## Response 500: application/json

Unexpected gateway error

## Response 501: application/json

feature_unavailable: A required feature is permanently unconfigured on this gateway, for example encrypted idempotency replay without its encryption key, PII redaction without a detector, or BYOK import without import keys. Ask the operator to configure it or remove the optional feature from the request. Retrying the identical request cannot enable the feature: retryable is false and no Retry-After header is sent. Temporary cache, database, detector or provider outages, pending imports and missing or revoked individual customer credentials retain their existing error types.

## Response 502: application/json

Safe provider error or invalid ranking/usage response

## Response 503: application/json

Providers failed, memory is busy, or gateway is shutting down
