Skip to main content
POST
https://app.firmware.ai
/
api
/
v1
/
rerank
Rerank
curl --request POST \
  --url https://app.firmware.ai/api/v1/rerank \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "query": "<string>",
  "documents": [
    {}
  ],
  "top_n": 123,
  "return_documents": true
}
'
{
  "id": "rerank-abc123",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.98,
      "document": { "text": "Paris is the capital of France." }
    },
    {
      "index": 2,
      "relevance_score": 0.61,
      "document": { "text": "France is a country in Western Europe." }
    }
  ],
  "usage": {
    "total_tokens": 512
  }
}
Rerank a list of documents by relevance to a query. Returns documents sorted by relevance score.

​
Authenticate

Use an API key in the Authorization header. 
curl https://app.firmware.ai/api/v1/rerank \
  -H "Authorization: Bearer $FIRMWARE_API_KEY"

​
Request body

​
model
string
required
Reranking model ID to use. See available rerank models for the full list.Examples: rerank-2.5, rerank-2.5-lite
​
query
string
required
The search query to rank documents against.
​
documents
array
required
List of documents to rerank. Pass an array of strings or objects with a text field.
["First document text", "Second document text", "Third document text"]
​
top_n
integer
Number of top results to return. Defaults to the total number of documents.
​
return_documents
boolean
default:"false"
Whether to include the document text in the response.

​
Response

​
id
string
Unique identifier for the rerank request.
​
results
array
Reranked documents sorted by relevance score descending.
​
usage
object
Token usage statistics.

​
Examples

curl https://app.firmware.ai/api/v1/rerank \
  -H "Authorization: Bearer $FIRMWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-2.5",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital of France.",
      "Berlin is the capital of Germany.",
      "France is a country in Western Europe."
    ],
    "top_n": 2
  }'

{
  "id": "rerank-abc123",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.98,
      "document": { "text": "Paris is the capital of France." }
    },
    {
      "index": 2,
      "relevance_score": 0.61,
      "document": { "text": "France is a country in Western Europe." }
    }
  ],
  "usage": {
    "total_tokens": 512
  }
}