> ## Documentation Index > Fetch the complete documentation index at: https://opentouter.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Submit a rerank request > Submits a rerank request to the rerank router ## OpenAPI ````yaml /openapi/openapi.yaml post /rerank openapi: 3.1.0 info: contact: email: support@openrouter.ai name: OpenRouter Support url: https://openrouter.ai/docs description: OpenAI-compatible API with additional OpenRouter features license: name: MIT url: https://opensource.org/licenses/MIT title: OpenRouter API version: 1.0.0 servers: - description: Production server url: https://openrouter.ai/api/v1 x-speakeasy-server-id: production security: - apiKey: [] tags: - description: API key management endpoints name: API Keys - description: Analytics and usage endpoints name: Analytics - description: Anthropic Messages endpoints name: Anthropic Messages - description: BYOK endpoints name: BYOK - description: Benchmarks endpoints name: Benchmarks - description: Chat completion endpoints name: Chat - description: Task classification market-share endpoints name: Classifications - description: Credit management endpoints name: Credits - description: Datasets endpoints name: Datasets - description: Text embedding endpoints name: Embeddings - description: Endpoint information name: Endpoints - description: Files endpoints name: Files - description: Generation history endpoints name: Generations - description: Guardrails endpoints name: Guardrails - description: Images endpoints name: Images - description: Model information endpoints name: Models - description: OAuth authentication endpoints name: OAuth - description: Observability endpoints name: Observability - description: Organization endpoints name: Organization - description: Presets endpoints name: Presets - description: Provider information endpoints name: Providers - description: Rerank endpoints name: Rerank - description: Speech-to-text endpoints name: STT x-displayName: Transcriptions - description: Text-to-speech endpoints name: TTS x-displayName: Speech - description: Video Generation endpoints name: Video Generation - description: Workspaces endpoints name: Workspaces - description: beta.Analytics endpoints name: beta.Analytics - description: beta.responses endpoints name: beta.responses externalDocs: description: OpenRouter Documentation url: https://openrouter.ai/docs paths: /rerank: post: tags: - Rerank summary: Submit a rerank request description: Submits a rerank request to the rerank router operationId: createRerank requestBody: content: application/json: schema: description: Rerank request input example: documents: - Paris is the capital of France. - Berlin is the capital of Germany. model: cohere/rerank-v3.5 query: What is the capital of France? top_n: 3 properties: documents: description: >- The list of documents to rerank. Documents may be plain strings, or structured objects with `text` and/or `image` for multimodal models. example: - Paris is the capital of France. - Berlin is the capital of Germany. items: anyOf: - type: string - description: >- A structured document with optional text and/or image content. At least one of `text` or `image` must be provided. properties: image: description: >- An image associated with the document, as a remote URL (http/https) or a base64-encoded data URI (data:image/...). example: >- https://upload.wikimedia.org/wikipedia/commons/thumb/8/8b/Phytogenic.png type: string text: description: The document text example: >- AI enables robots to perceive, plan, and act autonomously. type: string type: object description: >- A document to rerank. Either a plain string, or a structured object with optional `text` and/or `image`. minItems: 1 type: array model: description: The rerank model to use example: cohere/rerank-v3.5 type: string provider: allOf: - $ref: '#/components/schemas/ProviderPreferences' - description: Provider routing preferences for the request. query: description: The search query to rerank documents against example: What is the capital of France? type: string top_n: description: Number of most relevant documents to return example: 3 minimum: 1 type: integer required: - model - query - documents type: object required: true responses: '200': content: application/json: schema: description: Rerank response containing ranked results example: id: gen-rerank-1234567890-abc model: cohere/rerank-v3.5 results: - document: text: Paris is the capital of France. index: 0 relevance_score: 0.98 usage: search_units: 1 total_tokens: 150 properties: id: description: Unique identifier for the rerank response (ORID format) example: gen-rerank-1234567890-abc type: string model: description: The model used for reranking example: cohere/rerank-v3.5 type: string provider: description: The provider that served the rerank request example: Cohere type: string results: description: List of rerank results sorted by relevance example: - document: text: Paris is the capital of France. index: 0 relevance_score: 0.98 items: description: A single rerank result example: document: text: Paris is the capital of France. index: 0 relevance_score: 0.98 properties: document: description: >- The document object echoing the original input (text and/or image) properties: image: description: >- The image (URL or data URI) from the original document example: https://example.com/image.png type: string text: description: The document text example: Paris is the capital of France. type: string type: object index: description: Index of the document in the original input list example: 0 type: integer relevance_score: description: Relevance score of the document to the query example: 0.98 format: double type: number required: - index - relevance_score - document type: object type: array usage: description: Usage statistics example: search_units: 1 total_tokens: 150 properties: cost: description: Cost of the request in credits example: 0.001 format: double type: number search_units: description: Number of search units consumed (Cohere billing) example: 1 type: integer total_tokens: description: Total number of tokens used example: 150 type: integer type: object required: - model - results type: object text/event-stream: example: 'data: [DONE]' schema: description: Not used for rerank - rerank does not support streaming type: string x-speakeasy-sse-sentinel: '[DONE]' description: Rerank response '400': content: application/json: example: error: code: 400 message: Invalid request parameters schema: $ref: '#/components/schemas/BadRequestResponse' description: Bad Request - Invalid request parameters or malformed input '401': content: application/json: example: error: code: 401 message: Missing Authentication header schema: $ref: '#/components/schemas/UnauthorizedResponse' description: Unauthorized - Authentication required or invalid credentials '402': content: application/json: example: error: code: 402 message: >- Insufficient credits. Add more using https://openrouter.ai/credits schema: $ref: '#/components/schemas/PaymentRequiredResponse' description: Payment Required - Insufficient credits or quota to complete request '404': content: application/json: example: error: code: 404 message: Resource not found schema: $ref: '#/components/schemas/NotFoundResponse' description: Not Found - Resource does not exist '429': content: application/json: example: error: code: 429 message: Rate limit exceeded schema: $ref: '#/components/schemas/TooManyRequestsResponse' description: Too Many Requests - Rate limit exceeded '500': content: application/json: example: error: code: 500 message: Internal Server Error schema: $ref: '#/components/schemas/InternalServerResponse' description: Internal Server Error - Unexpected server error '502': content: application/json: example: error: code: 502 message: Provider returned error schema: $ref: '#/components/schemas/BadGatewayResponse' description: Bad Gateway - Provider/upstream API failure '503': content: application/json: example: error: code: 503 message: Service temporarily unavailable schema: $ref: '#/components/schemas/ServiceUnavailableResponse' description: Service Unavailable - Service temporarily unavailable '524': content: application/json: example: error: code: 524 message: Request timed out. Please try again later. schema: $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' description: Infrastructure Timeout - Provider request timed out at edge network '529': content: application/json: example: error: code: 529 message: Provider returned error schema: $ref: '#/components/schemas/ProviderOverloadedResponse' description: Provider Overloaded - Provider is temporarily overloaded components: schemas: ProviderPreferences: additionalProperties: false description: >- When multiple model providers are available, optionally indicate your routing preference. example: allow_fallbacks: true nullable: true properties: allow_fallbacks: description: > Whether to allow backup providers to serve requests - true: (default) when the primary provider (or your custom providers in "order") is unavailable, use the next best provider. - false: use only the primary/custom provider, and return the upstream error if it's unavailable. nullable: true type: boolean data_collection: description: >- Data collection setting. If no available model provider meets the requirement, your request will return an error. - allow: (default) allow providers which store user data non-transiently and may train on it - deny: use only providers which do not collect user data. enum: - deny - allow - null example: allow nullable: true type: string enforce_distillable_text: description: >- Whether to restrict routing to only models that allow text distillation. When true, only models where the author has allowed distillation will be used. example: true nullable: true type: boolean ignore: description: >- List of provider slugs to ignore. If provided, this list is merged with your account-wide ignored provider settings for this request. example: - openai - anthropic items: anyOf: - $ref: '#/components/schemas/ProviderName' - type: string nullable: true type: array max_price: description: >- The object specifying the maximum price you want to pay for this request. USD price per million tokens, for prompt and completion. properties: audio: description: Maximum price in USD per audio unit type: string completion: description: Maximum price in USD per million completion tokens type: string image: description: Maximum price in USD per image type: string prompt: description: Maximum price in USD per million prompt tokens type: string request: description: Maximum price in USD per request type: string type: object only: description: >- List of provider slugs to allow. If provided, this list is merged with your account-wide allowed provider settings for this request. example: - openai - anthropic items: anyOf: - $ref: '#/components/schemas/ProviderName' - type: string nullable: true type: array order: description: >- An ordered list of provider slugs. The router will attempt to use the first provider in the subset of this list that supports your requested model, and fall back to the next if it is unavailable. If no providers are available, the request will fail with an error message. example: - openai - anthropic items: anyOf: - $ref: '#/components/schemas/ProviderName' - type: string nullable: true type: array preferred_max_latency: $ref: '#/components/schemas/PreferredMaxLatency' preferred_min_throughput: $ref: '#/components/schemas/PreferredMinThroughput' quantizations: description: A list of quantization levels to filter the provider by. items: $ref: '#/components/schemas/Quantization' nullable: true type: array require_parameters: description: >- Whether to filter providers to only those that support the parameters you've provided. If this setting is omitted or set to false, then providers will receive only the parameters they support, and ignore the rest. nullable: true type: boolean sort: anyOf: - $ref: '#/components/schemas/ProviderSort' - $ref: '#/components/schemas/ProviderSortConfig' - nullable: true description: >- The sorting strategy to use for this request, if "order" is not specified. When set, no load balancing is performed. example: price zdr: description: >- Whether to restrict routing to only ZDR (Zero Data Retention) endpoints. When true, only endpoints that do not retain prompts will be used. example: true nullable: true type: boolean type: object BadRequestResponse: description: Bad Request - Invalid request parameters or malformed input example: error: code: 400 message: Invalid request parameters properties: error: $ref: '#/components/schemas/BadRequestResponseErrorData' openrouter_metadata: additionalProperties: nullable: true nullable: true type: object user_id: nullable: true type: string required: - error type: object UnauthorizedResponse: description: Unauthorized - Authentication required or invalid credentials example: error: code: 401 message: Missing Authentication header properties: error: $ref: '#/components/schemas/UnauthorizedResponseErrorData' openrouter_metadata: additionalProperties: nullable: true nullable: true type: object user_id: nullable: true type: string required: - error type: object PaymentRequiredResponse: description: Payment Required - Insufficient credits or quota to complete request example: error: code: 402 message: Insufficient credits. Add more using https://openrouter.ai/credits properties: error: $ref: '#/components/schemas/PaymentRequiredResponseErrorData' openrouter_metadata: additionalProperties: nullable: true nullable: true type: object user_id: nullable: true type: string required: - error type: object NotFoundResponse: description: Not Found - Resource does not exist example: error: code: 404 message: Resource not found properties: error: $ref: '#/components/schemas/NotFoundResponseErrorData' openrouter_metadata: additionalProperties: nullable: true nullable: true type: object user_id: nullable: true type: string required: - error type: object TooManyRequestsResponse: description: Too Many Requests - Rate limit exceeded example: error: code: 429 message: Rate limit exceeded properties: error: $ref: '#/components/schemas/TooManyRequestsResponseErrorData' openrouter_metadata: additionalProperties: nullable: true nullable: true type: object user_id: nullable: true type: string required: - error type: object InternalServerResponse: description: Internal Server Error - Unexpected server error example: error: code: 500 message: Internal Server Error properties: error: $ref: '#/components/schemas/InternalServerResponseErrorData' openrouter_metadata: additionalProperties: nullable: true nullable: true type: object user_id: nullable: true type: string required: - error type: object BadGatewayResponse: description: Bad Gateway - Provider/upstream API failure example: error: code: 502 message: Provider returned error properties: error: $ref: '#/components/schemas/BadGatewayResponseErrorData' openrouter_metadata: additionalProperties: nullable: true nullable: true type: object user_id: nullable: true type: string required: - error type: object ServiceUnavailableResponse: description: Service Unavailable - Service temporarily unavailable example: error: code: 503 message: Service temporarily unavailable properties: error: $ref: '#/components/schemas/ServiceUnavailableResponseErrorData' openrouter_metadata: additionalProperties: nullable: true nullable: true type: object user_id: nullable: true type: string required: - error type: object EdgeNetworkTimeoutResponse: description: Infrastructure Timeout - Provider request timed out at edge network example: error: code: 524 message: Request timed out. Please try again later. properties: error: $ref: '#/components/schemas/EdgeNetworkTimeoutResponseErrorData' openrouter_metadata: additionalProperties: nullable: true nullable: true type: object user_id: nullable: true type: string required: - error type: object ProviderOverloadedResponse: description: Provider Overloaded - Provider is temporarily overloaded example: error: code: 529 message: Provider returned error properties: error: $ref: '#/components/schemas/ProviderOverloadedResponseErrorData' openrouter_metadata: additionalProperties: nullable: true nullable: true type: object user_id: nullable: true type: string required: - error type: object ProviderName: enum: - AkashML - AI21 - AionLabs - Alibaba - Ambient - Baidu - Amazon Bedrock - Amazon Nova - Anthropic - Arcee AI - AtlasCloud - Avian - Azure - BaseTen - BytePlus - Black Forest Labs - Cerebras - Chutes - Cirrascale - Clarifai - Cloudflare - Cohere - Crucible - Crusoe - Darkbloom - Decart - DeepInfra - DeepSeek - DekaLLM - DigitalOcean - Featherless - Fireworks - Friendli - GMICloud - Google - Google AI Studio - Groq - HeyGen - Inception - Inceptron - InferenceNet - Ionstream - Infermatic - Io Net - Inferact vLLM - Inflection - Liquid - Mara - Mancer 2 - Minimax - ModelRun - Mistral - Modular - Moonshot AI - Morph - NCompass - Nebius - Nex AGI - NextBit - Novita - Nvidia - OpenAI - OpenInference - Parasail - Poolside - Perceptron - Perplexity - Phala - Recraft - Reka - Relace - Sakana AI - SambaNova - Seed - SiliconFlow - Sourceful - StepFun - Stealth - StreamLake - Switchpoint - Tenstorrent - Together - Upstage - Venice - Wafer - WandB - Quiver - Xiaomi - xAI - Z.AI - FakeProvider example: OpenAI type: string PreferredMaxLatency: anyOf: - format: double type: number - $ref: '#/components/schemas/PercentileLatencyCutoffs' - nullable: true description: >- Preferred maximum latency (in seconds). Can be a number (applies to p50) or an object with percentile-specific cutoffs. Endpoints above the threshold(s) may still be used, but are deprioritized in routing. When using fallback models, this may cause a fallback model to be used instead of the primary model if it meets the threshold. example: 5 PreferredMinThroughput: anyOf: - format: double type: number - $ref: '#/components/schemas/PercentileThroughputCutoffs' - nullable: true description: >- Preferred minimum throughput (in tokens per second). Can be a number (applies to p50) or an object with percentile-specific cutoffs. Endpoints below the threshold(s) may still be used, but are deprioritized in routing. When using fallback models, this may cause a fallback model to be used instead of the primary model if it meets the threshold. example: 100 Quantization: enum: - int4 - int8 - fp4 - fp6 - fp8 - fp16 - bf16 - fp32 - unknown example: fp16 type: string ProviderSort: description: The provider sorting strategy (price, throughput, latency) enum: - price - throughput - latency - exacto example: price type: string ProviderSortConfig: description: The provider sorting strategy (price, throughput, latency) example: by: price partition: model properties: by: description: The provider sorting strategy (price, throughput, latency) enum: - price - throughput - latency - exacto - null example: price nullable: true type: string partition: description: >- Partitioning strategy for sorting: "model" (default) groups endpoints by model before sorting (fallback models remain fallbacks), "none" sorts all endpoints together regardless of model. enum: - model - none - null example: model nullable: true type: string type: object BadRequestResponseErrorData: description: Error data for BadRequestResponse example: code: 400 message: Invalid request parameters properties: code: type: integer message: type: string metadata: additionalProperties: nullable: true nullable: true type: object required: - code - message type: object UnauthorizedResponseErrorData: description: Error data for UnauthorizedResponse example: code: 401 message: Missing Authentication header properties: code: type: integer message: type: string metadata: additionalProperties: nullable: true nullable: true type: object required: - code - message type: object PaymentRequiredResponseErrorData: description: Error data for PaymentRequiredResponse example: code: 402 message: Insufficient credits. Add more using https://openrouter.ai/credits properties: code: type: integer message: type: string metadata: additionalProperties: nullable: true nullable: true type: object required: - code - message type: object NotFoundResponseErrorData: description: Error data for NotFoundResponse example: code: 404 message: Resource not found properties: code: type: integer message: type: string metadata: additionalProperties: nullable: true nullable: true type: object required: - code - message type: object TooManyRequestsResponseErrorData: description: Error data for TooManyRequestsResponse example: code: 429 message: Rate limit exceeded properties: code: type: integer message: type: string metadata: additionalProperties: nullable: true nullable: true type: object required: - code - message type: object InternalServerResponseErrorData: description: Error data for InternalServerResponse example: code: 500 message: Internal Server Error properties: code: type: integer message: type: string metadata: additionalProperties: nullable: true nullable: true type: object required: - code - message type: object BadGatewayResponseErrorData: description: Error data for BadGatewayResponse example: code: 502 message: Provider returned error properties: code: type: integer message: type: string metadata: additionalProperties: nullable: true nullable: true type: object required: - code - message type: object ServiceUnavailableResponseErrorData: description: Error data for ServiceUnavailableResponse example: code: 503 message: Service temporarily unavailable properties: code: type: integer message: type: string metadata: additionalProperties: nullable: true nullable: true type: object required: - code - message type: object EdgeNetworkTimeoutResponseErrorData: description: Error data for EdgeNetworkTimeoutResponse example: code: 524 message: Request timed out. Please try again later. properties: code: type: integer message: type: string metadata: additionalProperties: nullable: true nullable: true type: object required: - code - message type: object ProviderOverloadedResponseErrorData: description: Error data for ProviderOverloadedResponse example: code: 529 message: Provider returned error properties: code: type: integer message: type: string metadata: additionalProperties: nullable: true nullable: true type: object required: - code - message type: object PercentileLatencyCutoffs: description: >- Percentile-based latency cutoffs. All specified cutoffs must be met for an endpoint to be preferred. example: p50: 5 p90: 10 properties: p50: description: Maximum p50 latency (seconds) format: double nullable: true type: number p75: description: Maximum p75 latency (seconds) format: double nullable: true type: number p90: description: Maximum p90 latency (seconds) format: double nullable: true type: number p99: description: Maximum p99 latency (seconds) format: double nullable: true type: number type: object PercentileThroughputCutoffs: description: >- Percentile-based throughput cutoffs. All specified cutoffs must be met for an endpoint to be preferred. example: p50: 100 p90: 50 properties: p50: description: Minimum p50 throughput (tokens/sec) format: double nullable: true type: number p75: description: Minimum p75 throughput (tokens/sec) format: double nullable: true type: number p90: description: Minimum p90 throughput (tokens/sec) format: double nullable: true type: number p99: description: Minimum p99 throughput (tokens/sec) format: double nullable: true type: number type: object securitySchemes: apiKey: description: API key as bearer token in Authorization header scheme: bearer type: http ````