> ## Documentation Index > Fetch the complete documentation index at: https://www.edenai.co/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Rerank > Rank `documents` by relevance to `query` (Cohere v2 rerank). ## OpenAPI ````yaml https://api.edenai.run/v3/docs/openapi.json post /v3/rerank openapi: 3.1.0 info: title: Eden AI API V3 version: 3.0.0 servers: - url: https://api.edenai.run description: Production server security: [] paths: /v3/rerank: post: tags: - Rerank summary: Create Rerank description: Rank `documents` by relevance to `query` (Cohere v2 rerank). operationId: create_rerank_v3_rerank_post requestBody: content: application/json: schema: $ref: '#/components/schemas/RerankBody' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RerankResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - AuthBearer: [] components: schemas: RerankBody: properties: tags: title: Tags description: >- Up to 10 key/value labels recorded with this call, for filtering and grouping usage. Merged with the `X-EdenAI-Tags` header. examples: - client: acme project: invoices routing: anyOf: - $ref: '#/components/schemas/ProviderRoutingPreferences' - type: 'null' description: >- How to pick between the providers that serve the requested model. Applies when `model` is a model name with no provider prefix (e.g. 'gpt-5.5'); ignored for a concrete 'provider/model' id, which already names its provider, except `zero_data_retention`, which holds every model in the request to it. With model='@edenai' the platform chooses the model too: `quality_cost` steers that choice, and the provider fields apply whenever the chosen model is a provider-less name. model: type: string title: Model description: >- Model identifier in 'provider/model' format, e.g. 'cohere/rerank-v3.5'. query: type: string minLength: 1 title: Query description: The search query to rank the documents against. documents: items: type: string type: array maxItems: 1000 minItems: 1 title: Documents description: The texts to rank, at most 1000. top_n: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' title: Top N description: >- Return only the `top_n` most relevant results. Defaults to all documents. return_documents: type: boolean title: Return Documents description: >- Echo each ranked document's text in its result under `document.text`. default: false metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Arbitrary metadata attached to the request. extra_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Extra Headers description: Additional HTTP headers forwarded to the provider API. additionalProperties: true type: object required: - model - query - documents title: RerankBody description: >- Cohere `POST /v2/rerank` request body, plus Eden extensions. Unknown top-level fields are forwarded to the provider; connection keys are rejected. ``routing`` is declared so ``prepare_input`` reads it validated; with a concrete 'provider/model' only ``zero_data_retention`` applies. RerankResponse: properties: cost: anyOf: - type: number - type: 'null' title: Cost description: >- Charge in USD from the row's rates; None when it cannot be computed in full (no row, an unusable rate, or no billable count for a priced unit). provider: anyOf: - type: string - type: 'null' title: Provider id: anyOf: - type: string - type: 'null' title: Id description: Identifier of the rerank call, as the provider returned it. results: items: $ref: '#/components/schemas/RerankResult' type: array title: Results description: Documents ordered by relevance to the query, most relevant first. meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta description: The provider's own billing metadata, as litellm returned it. usage: $ref: '#/components/schemas/RerankUsage' description: >- The priced units of the call; both counts are None when the provider reports neither. additionalProperties: true type: object title: RerankResponse description: |- Cohere-compatible rerank response plus Eden `cost` and `provider`. `usage` carries the billed units: `search_units` or `total_tokens`. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ProviderRoutingPreferences: properties: sort: anyOf: - type: string enum: - cost - speed - latency - exact - type: 'null' title: Sort description: >- What to optimise for when several providers serve the requested model. 'cost' (default) picks the cheapest for this request's shape; 'speed' the highest tokens/second; 'latency' the fastest to first token; 'exact' the most reliable at producing well-formed tool calls / structured output. Health is always a filter first — no mode will route you to a failing provider. Can also be written as a model suffix, e.g. 'gpt-5.5:speed'. sticky: anyOf: - type: boolean - type: 'null' title: Sticky description: >- Keep a conversation on the provider holding its prompt cache. On by default, and only ever active for models whose providers discount cache reads. Set false to route every request independently on price instead. Naming an explicit `sort` or an `order` also takes priority over cache affinity. allow_fallbacks: anyOf: - type: boolean - type: 'null' title: Allow Fallbacks description: >- Whether other providers of the same model may be tried when the chosen one fails. On by default. Set false to pin the request to the single best provider: it then fails rather than silently moving to another seller, useful when a cache-warm prompt would cold-miss elsewhere. This governs PROVIDERS of the requested model only; models you list in `fallbacks` are your own choice and are always kept. quality_cost: anyOf: - type: integer maximum: 10 minimum: 0 - type: 'null' title: Quality Cost description: >- Only with model='@edenai': how far to trade answer quality for cost when the platform chooses the MODEL. 0 asks for the best model for the request, 10 for the cheapest model that can still handle it, values in between blend the two; omit it to leave the choice to the platform (quality first). This is the one `routing` field that steers the model rather than the provider — `sort` never changes which model is chosen. allowed_providers: anyOf: - items: type: string maxLength: 64 minLength: 1 type: array - type: 'null' title: Allowed Providers description: >- Restrict routing to these providers, e.g. ['openai', 'anthropic']. Only providers that serve the requested model are considered, so an entry that does not sell it is simply inert. If none of them do, the request fails rather than falling back to a provider you excluded. Case-insensitive. Applies to routed providers only. a concrete 'provider/model' you named in `fallbacks` is your own choice and is kept. zero_data_retention: anyOf: - type: boolean - type: 'null' title: Zero Data Retention description: >- Serve this request only from providers that keep no prompts or outputs, and save neither its content nor its response. Applies to every model in the request, including a concrete 'provider/model' and your `fallbacks`: one that is not zero data retention fails the request. It can only add the restriction. When your organization requires zero data retention, `false` does not lift it. ignored_providers: anyOf: - items: type: string maxLength: 64 minLength: 1 type: array - type: 'null' title: Ignored Providers description: >- Never route to these providers, e.g. ['deepinfra']. The mirror of `allowed_providers`: an entry that does not sell the requested model is inert, and if the list removes every seller the request fails rather than falling back to one you excluded. Case-insensitive. A provider named in both lists is a validation error. A concrete 'provider/model' you named in `fallbacks` is your own choice and is kept. order: anyOf: - items: type: string maxLength: 64 minLength: 1 type: array maxItems: 16 - type: 'null' title: Order description: >- Providers to try first, in this order, e.g. ['azure', 'openai']. They become the head of the fallback chain; the remaining providers of the model follow, ranked by `sort` (or load-balanced on price when no `sort` is given). An entry that does not sell the model is inert. A provider our health data marks as down is moved to the end of the chain whatever its position here. Naming an `order` turns cache affinity off, as naming a `sort` does. Case-insensitive. max_price: anyOf: - $ref: '#/components/schemas/MaxPrice' - type: 'null' description: >- Only route to providers whose listed per-token rates are at or under this price, in USD per MILLION tokens, e.g. {'input': 2.5, 'output': 10}. Either side may be omitted. Providers priced by another unit (per image, per second) are unaffected. If no provider of the model is within the ceiling the request fails and names the cheapest one. type: object title: ProviderRoutingPreferences description: >- How to choose between SELLERS of one model — and, with ``@edenai``, how far to trade quality for cost when the platform chooses the model. ``order``, ``allowed_providers``, ``ignored_providers`` and ``max_price`` shape WHICH sellers and in what order; ``sort`` ranks the rest. The seller fields are only meaningful when `model` is a canonical name (`gpt-5.5`) rather than a concrete `provider/model` — with a concrete id there is nothing to choose between. For choosing the MODEL itself see ``router_candidates`` and ``model="@edenai"``, which is a different router; ``quality_cost`` below is the one field here that speaks to it. RerankResult: properties: index: type: integer title: Index description: Position of the document in the request's `documents`. relevance_score: type: number title: Relevance Score description: Relevance of the document to the query, higher is closer. document: anyOf: - $ref: '#/components/schemas/RerankResultDocument' - type: 'null' description: The ranked document, present only when `return_documents` is true. type: object required: - index - relevance_score title: RerankResult description: >- One ranked document: its position in the request and its relevance score. RerankUsage: properties: search_units: anyOf: - type: integer - type: 'null' title: Search Units description: >- Search units billed by a per-query provider (Cohere, Bedrock, Vertex). total_tokens: anyOf: - type: integer - type: 'null' title: Total Tokens description: >- Tokens billed by a per-token provider (DeepInfra, Fireworks AI, Qwen). type: object title: RerankUsage description: The priced units of one rerank call. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError MaxPrice: properties: input: anyOf: - type: number minimum: 0 - type: 'null' title: Input description: Highest input rate accepted, in USD per million tokens. output: anyOf: - type: number minimum: 0 - type: 'null' title: Output description: Highest output rate accepted, in USD per million tokens. additionalProperties: false type: object title: MaxPrice description: >- A price ceiling in USD per MILLION tokens, one bar per direction, either one optional. Unknown keys are refused: a typo on one side (``ouput``) must not silently remove that bar. RerankResultDocument: properties: text: anyOf: - type: string - type: 'null' title: Text description: The text of the ranked document. additionalProperties: true type: object title: RerankResultDocument description: >- The ranked document echoed back, present only when ``return_documents`` is true. securitySchemes: AuthBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.