> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rerank API (/rerank)

> Learn how to use the Rerank API through TrueFoundry AI Gateway to enhance search relevance by scoring and reordering document results.

**API Reference:** [`POST /v2/rerank`](/docs/api-reference/rerank/rerank-documents)

## Provider capabilities

The table below summarizes gateway support for this endpoint by provider.

<Info>
  Legend:

  * **✅** Supported by provider and TrueFoundry
  * <Icon icon="circle-xmark" iconType="regular" color="red" /> Provided by provider, but not by TrueFoundry
  * <Icon icon="circle-minus" iconType="regular" /> Provider does not support this feature
</Info>

| Provider         | Rerank                                                      |
| ---------------- | ----------------------------------------------------------- |
| OpenAI           | <Icon icon="circle-minus" iconType="regular" />             |
| Azure OpenAI     | ✅                                                           |
| Azure AI Foundry | ✅                                                           |
| Anthropic        | <Icon icon="circle-minus" iconType="regular" />             |
| Bedrock          | ✅                                                           |
| Vertex           | <Icon icon="circle-minus" iconType="regular" />             |
| Cohere           | ✅                                                           |
| Gemini           | <Icon icon="circle-minus" iconType="regular" />             |
| Groq             | <Icon icon="circle-minus" iconType="regular" />             |
| Together-AI      | <Icon icon="circle-xmark" iconType="regular" color="red" /> |
| xAI              | <Icon icon="circle-minus" iconType="regular" />             |
| DeepInfra        | <Icon icon="circle-xmark" iconType="regular" color="red" /> |

For every gateway endpoint and provider, see [Supported APIs](/docs/ai-gateway/intro-to-llm-gateway#supported-apis).

<Note>
  **Using Cohere reranker models on Azure AI Foundry?** Set the **Azure Endpoint** on the model to `https://<resource>.services.ai.azure.com/providers/cohere/v2` — the gateway appends `/rerank` itself. See [Azure AI Foundry — Cohere Rerank](/docs/ai-gateway/azure-ai-foundry#cohere-rerank).
</Note>

<Note>
  **Using AWS Bedrock reranker models?** The IAM user or role attached to your Bedrock model account needs the `bedrock:Rerank` permission in addition to `bedrock:InvokeModel` — reranking is served by a separate AWS endpoint (`bedrock-agent-runtime`), so invoke-only policies fail with `AccessDeniedException`. See [AWS Bedrock — Required IAM Policy](/docs/ai-gateway/aws-bedrock#adding-models).
</Note>

**Reranking** is a powerful technique that enhances the relevance of search results. It works by taking a **query** and a list of **documents**, then scoring each document based on how relevant it is to the query. This is especially useful in multi-step search pipelines where you:

1. Use a traditional or vector-based search system to retrieve candidate documents.
2. Use the **Rerank API** to reorder those candidates based on relevance.

Reranking helps boost precision in **semantic search**, **chatbots**, **RAG systems**, and **knowledge retrieval systems**.

The reranker takes:

* A **query** (user input or search question)
* A list of **documents** (initially retrieved search results)
* Returns a ranked list with **relevance scores**

### Code Snippet

```python lines theme={"dark"}
import cohere

BASE_URL = "{GATEWAY_BASE_URL}"
API_KEY = "your-truefoundry-api-key"

# Configure Cohere client with TrueFoundry settings
client = cohere.ClientV2(
	api_key=API_KEY,
	base_url=BASE_URL
)

response = client.rerank(
    model="test-ss-cohere/rerank-multilingual-v3-0",
    query="Where is New Delhi?",
    documents=["New Delhi is capital of India","The sky is blue"],
    top_n=1,
)

print(response)
```

### Expected Output

```json lines theme={"dark"}
{
  "id": "a9279c7a-1e34-4bee-9892-db1d38ca9be0",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.783542
    }
  ]
}
```

In this example, the document *"New Delhi is the capital of India."* has a higher relevance score to the query compared to *"The sky is blue."*, and is therefore ranked higher.