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 --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

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

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

// 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

{
  "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.

{}

{
  "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.

{}

"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.

{}

"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"}

1

Response 200: application/json

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

{
  "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.

{}

{
  "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.

{}

"gen-01k7tm9qz3f5c8x2v6b4n0m7hd"
  • model (required): s368

s368: string

Resolved public model ID.

{}

"baai/bge-reranker-v2-m3"
  • provider (required): s369

s369: string

Configured provider identifier, never arbitrary upstream text.

{}

"eu-provider"
  • results (required): s370

s370: array

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

{}

s194: object

One ranked document.

{}

{
  "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.

{}

{
  "text": "Paris is in France."
}
  • text (required): s963

s963: string

Nonempty UTF-8 text, at most 65536 bytes.

{}

"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"}

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"}

0.9
  • usage (required): s371

s371: object

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

{}

{
  "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

{}

0.00005
  • currency (required): s966

s966: string

Always EUR.

{}

"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"}

8
  • total_tokens (required): s969

s969: integer

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

int64

{"minimum":"0"}

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

{
  "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.

{}

{
  "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.

{}

{
  "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"}

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.

{}

"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.

{}

{
  "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).

{}

[
  "deepinfra",
  "open-inference"
]
  • docs_url (required): s640

s640: string

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

{}

"/docs#description/model-not-found"
  • failed_routing_step (optional): s641

s641: string

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

{}

"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.

{}

{
  "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"

{}

"out_of_range"
  • message (required): s637

s637: string

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

{}

"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.

{}

"$.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.

{}

{
  "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"

{}

"rate_limited"
  • code (optional): s1300

s1300: string

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

{}

"rate_limit_exceeded"
  • provider_name (required): s1301

s1301: string

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

{}

"deepinfra"
  • retry_after (optional): s1302

s1302: integer

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

int64

{"minimum":"0"}

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"}

429

oneOf: s588

s588: null

{}

  • provider_name (optional): s644

s644: string

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

{}

"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.

{}

""
  • remedy_hint (optional): s646

s646: string

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

{}

"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.

{}

"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
  • requested_providers (optional): s648

s648: array

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

{}

[
  "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"}

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.

{}

{
  "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"}

2
  • reason (optional): s980

s980: string

The request field the step filtered on.

{}

"provider.only"
  • step (required): s981

s981: string

Name of the step, as at OpenRouter.

{}

"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"

{}

"invalid_parameter"
  • user_id (optional): s239

s239: string | null

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

{}

"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