POST /v1/rerank — Document Reranking

The /v1/rerank endpoint takes a search query and a list of documents, then returns the documents ordered by their relevance to the query. Each result includes a relevance score you can use to filter or threshold results before passing them to a language model. Reranking is commonly used as a second-stage retrieval step in RAG pipelines to improve the quality of context sent to a model.

Request parameters

string

required

The reranking model to use. Use the list models endpoint to find available reranking model IDs.

string

required

The search query against which the documents are ranked.

string[]

required

An array of document strings to rank. Each string is treated as a candidate document. The order of this array determines the index values in the response.

integer

The maximum number of results to return. When omitted, all documents are returned ranked by relevance score.

Response fields

array

An array of ranked result objects sorted from highest to lowest relevance score.

Show properties

integer

The zero-based position of this document in the original documents input array.

number

A float between 0 and 1 indicating how relevant the document is to the query. Higher values indicate greater relevance.

string

The document text, as provided in the input array.

Example

Request

curl https://tokmodel.com/v1/rerank \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "cohere/rerank-english-v3.0",
    "query": "How do I reset my password?",
    "documents": [
      "To reset your password, click the Forgot Password link on the login page.",
      "Our pricing plans start at $10 per month.",
      "You can update your email address from the Account Settings page.",
      "Password requirements: at least 8 characters, one number, one symbol."
    ],
    "top_n": 2
  }'

Response

{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9823,
      "document": "To reset your password, click the Forgot Password link on the login page."
    },
    {
      "index": 3,
      "relevance_score": 0.7541,
      "document": "Password requirements: at least 8 characters, one number, one symbol."
    }
  ]
}

​Request parameters

​Response fields

​Example

​Request

​Response

Request parameters

Response fields

Example

Request

Response