Rerank

Reranks a list of documents based on their relevance to a query. This endpoint provides a unified interface to reranking models from multiple providers including Cohere, Voyage, Jina, Pinecone, Bedrock, and Azure AI.

Reranking is useful for improving search results by scoring and sorting documents based on semantic relevance to a query, rather than just keyword matching.

POST /rerank

cURL

Default

curl https://api.portkey.ai/v1/rerank \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-virtual-key: $PORTKEY_PROVIDER_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v3.5",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital of France.",
      "Berlin is the capital of Germany.",
      "Madrid is the capital of Spain."
    ],
    "top_n": 2
  }'

200

{
  "object": "list",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.98,
      "document": {
        "text": "<string>"
      }
    }
  ],
  "model": "rerank-v3.5",
  "id": "rerank-abc123",
  "usage": {
    "search_units": 123
  },
  "provider": "cohere"
}

Authorizations

Portkey-Key & Virtual-KeyPortkey-Key & Provider-Auth & Provider-NamePortkey-Key & ConfigPortkey-Key & Provider-Auth & Provider-Name & Custom-Host

x-portkey-api-key · string · header · required

x-portkey-virtual-key · string · header · required

Headers

x-portkey-trace-id · string

An ID you can pass to refer to one or more requests later on. If not provided, Portkey generates a trace ID automatically for each request. Docs

x-portkey-span-id · string

An ID you can pass to refer to a span under a trace.

x-portkey-parent-span-id · string

Link a child span to a parent span

x-portkey-span-name · string

Name for the Span ID

x-portkey-metadata · object

Pass any arbitrary metadata along with your request

Body

application/json

Request body for reranking documents. The unified API supports multiple providers including Cohere, Voyage, Jina, Pinecone, Bedrock, and Azure AI.

model · string · required

ID of the model to use for reranking. Model availability depends on the provider:

• Cohere: rerank-v3.5, rerank-english-v3.0, rerank-multilingual-v3.0, rerank-english-v2.0, rerank-multilingual-v2.0
• Voyage: rerank-2, rerank-2-lite
• Jina: jina-reranker-v2-base-multilingual, jina-reranker-v1-base-en, jina-reranker-v1-turbo-en, jina-reranker-v1-tiny-en
• Pinecone: bge-reranker-v2-m3, pinecone-rerank-v0
• Bedrock: Model ARN (e.g., arn:aws:bedrock:us-west-2::foundation-model/cohere.rerank-v3-5:0)
• Azure AI: Cohere rerank deployments on Azure AI Inference; use the model name from your deployment, typically prefixed with cohere. (the gateway strips that prefix for the upstream request)

Example:

"rerank-v3.5"

query · string · required

The search query to compare against the documents.

Example:

"What is the capital of France?"

documents · (string | object · object)[] · required

The list of documents to rerank. Each document can be a string or an object with a text field. The documents will be scored based on their relevance to the query.

Minimum array length: 1

A document to be reranked. Can be a simple string or an object with a text field and optional metadata.

Example:

"Paris is the capital of France."

Example:

[
  "Paris is the capital of France.",
  "Berlin is the capital of Germany.",
  "Madrid is the capital of Spain."
]

top_n · integer

The number of top results to return. If not specified, all documents are returned sorted by relevance. For Voyage, the gateway maps this field to the provider's top_k parameter.

Required range: x >= 1

Example:

3

return_documents · boolean · default: false

Whether to return the document text in the response. Supported by Voyage, Jina, and Pinecone.

max_tokens_per_doc · integer

Maximum number of tokens per document. Documents exceeding this limit will be truncated. Cohere-specific parameter.

Required range: x >= 1

priority · number

Request priority hint. Cohere-specific parameter.

rank_fields · string[]

The fields to use for ranking when documents are objects with multiple fields. Pinecone-specific parameter.

Example:

["text", "title"]

truncation · boolean

Whether to truncate documents that exceed the model's maximum context length. Voyage-specific parameter.

parameters · object

Additional provider-specific parameters. Pinecone-specific parameter.

Response

200 - application/json

OK

Response from the rerank endpoint.

object · enum<string> · required

The object type, which is always "list".

Available options: list

Example:

"list"

results · object[] · required

The reranked results sorted by relevance score in descending order.

Show child attributes

model · string · required

The model used for reranking.

Example:

"rerank-v3.5"

id · string

A unique identifier for the rerank request.

Example:

"rerank-abc123"

usage · object

Usage information for the rerank request.

Show child attributes

provider · string

The provider that processed the request.

Example:

"cohere"