Given a query and a list of document chunks, the Rerank API indexes the documents from most to least semantically relevant to the query. It requires the following input at the minimum:
- A reranker model that takes a user query and assesses the relevance of the data sources that it can access.
- The user query.
- A list of document chunks that the reranker must reorder according to their relevance to the query.
| Method |
Path |
Description |
| POST |
/rerank |
Reranks a list of document chunks based on a query. |
It finds the most relevant document chunks in relation to a specific query. It accomplishes this through a method called cross-encoding where the model computes a relevance score for a document Chunk in relation to a user question.
| Parameter |
Type |
Description |
| query |
string |
Input query |
| model |
string |
provider/modelName reranker to use; supported values: cohere/rerank-v3.5, awsbedrock/cohere.rerank-v3.5, awsbedrock/amazon.rerank-v1 |
| documents |
string or array |
A list of text chunks |
| top_n |
string |
Count of best n results to return |
This method enables highly accurate information understanding, exceeding traditional keyword and embedding search, and can be applied after an initial dense retrieval stage to ensure the answers surfaced to users are maximally precise.
Body definitions as follows:
{
"model": "string",
"query": "string",
"documents": [
"chunk_1",
"chunk_2",
...
],
"top_n": number
}
The expected response is similar to:
{
"id": "guid",
"results": [ // list of indexed results
{
"index": number,
"relevance_score": [0..1]
},...
],
"meta": {
"api_version": {
"version": "string"
},
"billed_units": {
"search_units": number
}
}
}
curl --location '$BASE_URL/rerank' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $SAIA_PROJECT_APITOKEN' \
--data '{
"model": "cohere/rerank-v3.5",
"query": "What is the Capital of the United States?",
"documents": [
"Carson City is the capital city of the American state of Nevada.",
"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
"Washington, D.C. is the capital of the United States.",
"Capital punishment has existed in the United States since before it was a country."
],
"top_n": 3
}'
{
"id": "ab65b965-40bd-4d0e-9639-d6b9f8211255",
"results": [
{
"index": 2,
"relevance_score": 0.8963332
},
{
"index": 0,
"relevance_score": 0.17393301
},
{
"index": 1,
"relevance_score": 0.08111866
}
],
"meta": {
"api_version": {
"version": "1"
},
"billed_units": {
"search_units": 1
}
}
}
API Reference