Rerank API (Cohere Compatible)¶

Rank documents by semantic relevance to a query with AWS Bedrock rerank models through a Cohere-compatible interface.

Route Prefix Configuration

By default, all Cohere-compatible routes are prefixed with /cohere. This means the Rerank API is available at /cohere/v2/rerank instead of /v2/rerank. You can customize this prefix using the COHERE_ROUTES_PREFIX configuration variable documented in Operations Configuration.

The curl examples below use a $BASE variable that must include this prefix — set it to your scheme and host followed by COHERE_ROUTES_PREFIX:

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

Why Choose Rerank?¶

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 AWS Bedrock rerank models in your own AWS account — no traffic to third-party endpoints.

Quick Start: Available Endpoint¶

Endpoint	Method	What It Does	Powered By	MCP Tool
`/v2/rerank`	POST	Rank documents by semantic relevance to a query	AWS Bedrock Rerank Models	`cohere_rerank`
`/v1/rerank`	POST	Legacy v1 rerank for older SDKs and integrations	AWS Bedrock Rerank Models	`cohere_rerank_v1`

Example request:

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}
  }
}

Model Support¶

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

Cohere Models¶

Model	Model ID	Notes
Cohere Rerank 3.5	`cohere.rerank-v3-5:0`	Multilingual, state-of-the-art relevance

Amazon Models¶

Model	Model ID	Notes
Amazon Rerank 1.0	`amazon.rerank-v1:0`	Not available in every region (e.g. absent from `us-east-1`)

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

Feature Compatibility¶

Feature	Status	Notes
Input
`query` + `documents` (strings)		Full support
`top_n`		Limits the number of returned results
`max_tokens_per_doc`		Forwarded to the model; support depends on the model
`priority`		Accepted but ignored — not applicable on AWS Bedrock
`return_documents`		Accepted but ignored — v2 results reference input documents by `index`
Extra model-specific params		Extra fields are forwarded as additional model request parameters
Output
`results` (index + score)		Ordered by decreasing relevance
`meta.billed_units`		One search unit per started batch of 100 documents

Legend:

Supported — Fully compatible with the Cohere API
Available on Select Models — Check your model's capabilities
Unsupported — Not available in this implementation
Extra Feature — Enhanced capability beyond the Cohere API

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 AWS Bedrock backend and model support as /v2/rerank; new clients should prefer the v2 endpoint.

Differences from the v2 endpoint:

Feature	Status	Notes
`documents` as objects		Each document is a string or an object with a `text` field
`return_documents`		When `true`, each result echoes back the document text
`rank_fields`		Only the default `["text"]` is accepted; other values return 400
`max_chunks_per_doc`		Rejected with 400 — no AWS Bedrock equivalent
`meta.api_version.version`		Reported as `"1"`

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": [
      {"text": "Carson City is the capital city of Nevada."},
      {"text": "Washington, D.C. is the capital of the United States."}
    ],
    "top_n": 1,
    "return_documents": true
  }'

Example response:

{
  "id": "0f1b3c6e8d9a4b5c8e7f6a5b4c3d2e1f",
  "results": [
    {
      "document": {"text": "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 AWS Bedrock Rerank API, with automatic multi-region routing and failover across the regions where the selected model is available.

Required IAM permission

The Rerank API requires the bedrock:Rerank IAM action in addition to bedrock:InvokeModel. See IAM Permissions.

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.