Rerank API (Cohere Compatible)¶

Rank documents by semantic relevance to a query with Amazon Bedrock rerank models through a Cohere-compatible interface. Served under /cohere by default; the examples below use $BASE, which includes that prefix.

At a glance¶

• Better search relevance — Re-order candidate documents by true semantic relevance to the query. A precise second stage after vector or keyword search.
• Higher RAG quality — Feed your LLM only the most relevant passages. Reranking reduces context noise and improves answer accuracy.
• Drop-in Cohere compatibility — Follows the Cohere v2 Rerank API shape. Existing Cohere rerank integrations work by changing the base URL.
• Private AWS backend — Served entirely by Bedrock rerank models in your own AWS account — no traffic to third-party endpoints.
• Billed per search unit — one query with up to 100 documents is one unit, then one more per started batch of 100.
• Differs from the Cohere API: priority and return_documents are accepted and ignored on /v2/rerank, and max_chunks_per_doc is refused on /v1/rerank — see Limits and behaviour to know.

export BASE="https://your-host/cohere"  # <scheme>://<host> + COHERE_ROUTES_PREFIX

curl -X POST "$BASE/v2/rerank" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere.rerank-v3-5:0",
    "query": "What is the capital of the United States?",
    "documents": [
      "Carson City is the capital city of Nevada.",
      "Washington, D.C. is the capital of the United States."
    ],
    "top_n": 1
  }'

Endpoints¶

Feature compatibility¶

Models¶

Any rerank model available in your configured Bedrock regions can be used, for example:

Cohere Models¶

Amazon Models¶

Find compatible models: Call /search_models with route=cohere_rerank to discover model IDs that support reranking in your deployment.

Cohere v1 Rerank API (Legacy)¶

The legacy /v1/rerank endpoint is also available for older Cohere SDKs (cohere.Client) and third-party integrations that predate the v2 API. It shares the same Bedrock backend and model support as /v2/rerank; new clients should prefer the v2 endpoint.

Differences from the v2 endpoint:

Object documents with a single text field use the same plain-text encoding as a string document. Multi-field objects (or object documents combined with a non-default rank_fields) are sent to Bedrock as structured JSON documents, natively reranked on their fields. When rank_fields is set, object documents are first reduced to the listed fields (missing fields are skipped) before being sent; return_documents always echoes back the original, unreduced document.

Example request:

curl -X POST "$BASE/v1/rerank" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere.rerank-v3-5:0",
    "query": "What is the capital of the United States?",
    "documents": [
      {"title": "Nevada", "text": "Carson City is the capital city of Nevada."},
      {"title": "United States", "text": "Washington, D.C. is the capital of the United States."}
    ],
    "rank_fields": ["title", "text"],
    "top_n": 1,
    "return_documents": true
  }'

Example response:

{
  "id": "0f1b3c6e8d9a4b5c8e7f6a5b4c3d2e1f",
  "results": [
    {
      "document": {"text": "title: United States\ntext: Washington, D.C. is the capital of the United States."},
      "index": 1,
      "relevance_score": 0.9871
    }
  ],
  "meta": {
    "api_version": {"version": "1"},
    "billed_units": {"search_units": 1}
  }
}

How It Works¶

Requests are served by the Amazon Bedrock Rerank API, with automatic multi-region routing and failover across the regions where the selected model is available.

Billing¶

AWS bills reranking per search unit: one search unit covers a single query with up to 100 documents. A request with more than 100 documents is billed one additional search unit per started batch of 100. Search units appear in usage logs and cost tracking as search_units.

Limits and behaviour to know¶

priority is accepted and ignored. Amazon Bedrock has no per-request scheduling priority, so the field changes nothing about how or when the request runs.

return_documents is accepted and ignored on /v2/rerank. A v2 result references its input by index and never echoes the document text; use the index against the array you sent. The v1 endpoint does echo documents.

max_chunks_per_doc is refused with 400 on /v1/rerank. The Amazon Bedrock Rerank API has no per-document chunk cap to map it onto, so the request is rejected rather than silently ranked with different chunking. Use max_tokens_per_doc on /v2/rerank.

Amazon Rerank 1.0 is not in every region — it is absent from us-east-1, for one. Add a region that serves it to AWS_BEDROCK_REGIONS, or call /search_models with route=cohere_rerank to see what this deployment actually serves.

Request headers¶

Try it¶

curl -X POST "$BASE/v2/rerank" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere.rerank-v3-5:0",
    "query": "What is the capital of the United States?",
    "documents": [
      "Carson City is the capital city of Nevada.",
      "Washington, D.C. is the capital of the United States.",
      "Capital punishment has existed in the United States since colonial times."
    ],
    "top_n": 2
  }'

Example response:

{
  "id": "0f1b3c6e8d9a4b5c8e7f6a5b4c3d2e1f",
  "results": [
    {"index": 1, "relevance_score": 0.9871},
    {"index": 2, "relevance_score": 0.3251}
  ],
  "meta": {
    "api_version": {"version": "2"},
    "billed_units": {"search_units": 1}
  }
}

Next steps¶

Next: Embed API · Search Models API · IAM Permissions · Cost Management