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

# Rerank

> Examples of reranking documents with SynapsAI Cloud

Our rerank endpoint follows a Cohere-compatible request format at `POST /v1/rerank`.

Here is an example of reranking documents:

**Parameters:**

* `model`: The model ID of the model you want to use
* `query`: The search query or question to rank documents against
* `documents`: The list of documents to rerank
* `top_n`: The number of top ranked results to return (optional)
* `max_tokens_per_doc`: Maximum number of tokens to consider per document (default: 4096)

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  model = SynapsAI("your-api-key")

  response = model.rerank.create(
      model="model-id",
      query="What is the capital of France?",
      documents=[
          "Paris is the capital and most populous city of France.",
          "Berlin is the capital of Germany.",
          "Madrid is the capital of Spain."
      ],
      top_n=2,
      max_tokens_per_doc=4096
  )

  for result in response.results:
      print("Index:", result.index)
      print("Relevance Score:", result.relevance_score)
      print("Document:", result.document)
      print("---")
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/rerank \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "model-id",
          "query": "What is the capital of France?",
          "documents": [
            "Paris is the capital and most populous city of France.",
            "Berlin is the capital of Germany.",
            "Madrid is the capital of Spain."
          ],
          "top_n": 2,
          "max_tokens_per_doc": 4096
      }'
  ```
</CodeGroup>

Here is another example for semantic search ranking:

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  model = SynapsAI("your-api-key")

  response = model.rerank.create(
      model="model-id",
      query="Which document talks about pricing and billing?",
      documents=[
          "You can manage your API keys from the dashboard settings page.",
          "Billing is calculated based on model usage and output tokens.",
          "Team members can be invited from the organization settings page.",
          "Rate limits vary by model and subscription tier."
      ],
      top_n=3
  )

  for result in response.results:
      print("Index:", result.index)
      print("Relevance Score:", result.relevance_score)
      print("Document:", result.document)
      print("---")
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/rerank \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "model-id",
          "query": "Which document talks about pricing and billing?",
          "documents": [
            "You can manage your API keys from the dashboard settings page.",
            "Billing is calculated based on model usage and output tokens.",
            "Team members can be invited from the organization settings page.",
            "Rate limits vary by model and subscription tier."
          ],
          "top_n": 3,
          "max_tokens_per_doc": 4096
      }'
  ```
</CodeGroup>

For deeper insights into the rerank endpoint, see our [API reference](https://docs.synapsai.cloud/api-reference/rank-texts-relative-to-a-query).