> ## Documentation Index > Fetch the complete documentation index at: https://docs.opper.ai/llms.txt > Use this file to discover all available pages before exploring further. # Rerank documents > Reorder `documents` by relevance to `query` and get them back most-relevant first. `model`, `query` and `documents` are required; `top_n` caps how many results come back (integer >=1; default: all). `top_k` is a compatibility alias (zero means unspecified); positive values must match when both fields are supplied, and `return_documents` echoes each document's text alongside its score. Up to 1000 documents per call. Billed per call or per token depending on the endpoint: `usage.cost` is what was charged, `usage.total_tokens` the provider's count when it reports one. `model` accepts either form, and which one you send decides the routing: - a **bare model name** (e.g. `rerank-v3.5`) routes over that model's pooled endpoints and **falls over to the next one** when an endpoint fails — the case this matters for is provider rate limits, where one endpoint's quota is exhausted and another's is not. - a **fully-qualified id** (e.g. `aws/cohere/rerank-v3.5`) pins that exact endpoint and never falls over. The response's `model` is the endpoint that actually served the call, which for a pooled name is not necessarily the preferred one. List what is available with `GET /v3/models?type=rerank`. The project's Comply model allowlist applies to every endpoint a bare name can route to, not only the one you named: an endpoint it forbids is never tried, not even as a fallover target. A pinned id the allowlist forbids, or a pool it empties, is refused with `403` rather than substituted. A provider that requires a signed agreement needs the organization's grant, as everywhere else: no grant, no call, and never as a fallover target. See the [rerank guide](/build/gateway/rerank) for examples, model selection, and billing behavior. ## OpenAPI ````yaml post /v3/rerank openapi: 3.1.0 info: description: Schema-driven generative API that orchestrates LLM-powered workflows. title: Task API version: 3.0.0 servers: - description: Production url: https://api.opper.ai - description: Local development url: http://localhost:8080 security: - BearerAuth: [] tags: - description: Schema-driven function management and execution name: Functions - description: OpenAI-compatible chat completions name: Chat - description: OpenAI Responses API compatible endpoint name: Responses - description: Google-compatible interactions endpoint name: Interactions - description: Model registry and capabilities name: Models - description: Synchronous image generation name: Images - description: Text-to-speech and speech-to-text name: Audio - description: Asynchronous video generation name: Videos - description: Reusable file storage for media inputs and generated outputs name: Files - description: Async generation status and downloads name: Artifacts - description: OpenAI-compatible embeddings name: Embeddings - description: Recorded HTTP request/response generations name: Generations - description: System health and status name: System - description: Roundtable endpoint — fan out a query to multiple LLMs and combine results name: Roundtable - description: Web search, fetch, and other utility tools name: Tools - description: Caller identity, credits, and usage name: Account - description: >- Programmatic project and API-key management. Authenticates with an `op-mak-…` management token; available on the control_plane and enterprise plans. name: Management paths: /v3/rerank: post: tags: - Rerank summary: Rerank documents description: >- Reorder `documents` by relevance to `query` and get them back most-relevant first. `model`, `query` and `documents` are required; `top_n` caps how many results come back (integer >=1; default: all). `top_k` is a compatibility alias (zero means unspecified); positive values must match when both fields are supplied, and `return_documents` echoes each document's text alongside its score. Up to 1000 documents per call. Billed per call or per token depending on the endpoint: `usage.cost` is what was charged, `usage.total_tokens` the provider's count when it reports one. `model` accepts either form, and which one you send decides the routing: - a **bare model name** (e.g. `rerank-v3.5`) routes over that model's pooled endpoints and **falls over to the next one** when an endpoint fails — the case this matters for is provider rate limits, where one endpoint's quota is exhausted and another's is not. - a **fully-qualified id** (e.g. `aws/cohere/rerank-v3.5`) pins that exact endpoint and never falls over. The response's `model` is the endpoint that actually served the call, which for a pooled name is not necessarily the preferred one. List what is available with `GET /v3/models?type=rerank`. The project's Comply model allowlist applies to every endpoint a bare name can route to, not only the one you named: an endpoint it forbids is never tried, not even as a fallover target. A pinned id the allowlist forbids, or a pool it empties, is refused with `403` rather than substituted. A provider that requires a signed agreement needs the organization's grant, as everywhere else: no grant, no call, and never as a fallover target. operationId: createRerank requestBody: content: application/json: schema: $ref: '#/components/schemas/RerankRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/RerankResponse' description: Successful response '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad request '401': description: Unauthorized - missing or invalid API key '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error components: schemas: RerankRequest: properties: documents: items: type: string type: array model: type: string query: type: string return_documents: type: boolean top_k: description: >- Compatibility alias for top_n. Zero means unspecified. Positive values must match top_n when both are supplied. minimum: 0 type: integer top_n: description: Maximum number of results. Omit to return all documents. minimum: 1 type: integer required: - model - query - documents type: object RerankResponse: properties: id: type: string model: type: string results: items: properties: document: properties: text: type: string required: - text type: object index: type: integer relevance_score: type: number required: - index - relevance_score type: object type: array usage: properties: cost: type: number total_tokens: type: integer required: - total_tokens - cost type: object required: - id - model - results - usage type: object ErrorResponse: properties: error: properties: code: type: string details: description: Any value message: type: string required: - code - message type: object meta: type: object required: - error type: object securitySchemes: BearerAuth: bearerFormat: API Key description: API key authentication. Pass your API key as a Bearer token. scheme: bearer type: http ````