Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tokmodel.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
model
string
required
The reranking model to use. Use the list models endpoint to find available reranking model IDs.
​
query
string
required
The search query against which the documents are ranked.
​
documents
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.
​
top_n
integer
The maximum number of results to return. When omitted, all documents are returned ranked by relevance score.

​
Response fields

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

​
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."
    }
  ]
}