Rerank API (Cohere Compatible)¶

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

Route Prefix & Base URL

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

Quick Start: Available Endpoints¶

Endpoint	Method	What It Does	Powered By	MCP Tool
`/v2/rerank`	`POST`	Rank documents by semantic relevance to a query	Bedrock rerank models	`cohere_rerank`
`/v1/rerank`	`POST`	Legacy v1 rerank for older SDKs and integrations	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}
  }
}

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 — request scheduling priority is not applicable on 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
Partial — Supported with limitations
Unsupported — Not available in this implementation
Extra Feature — Enhanced capability beyond the Cohere API

Model Support¶

Any rerank model available in your configured 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 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:

Feature	Status	Notes
`documents` as objects		Each document is a string, or a field->value object
`return_documents`		When `true`, each result echoes back the document text
`rank_fields`		Ranks object documents on the selected fields only
`max_chunks_per_doc`		Rejected with 400 — no Bedrock equivalent
`meta.api_version.version`		Reported as `"1"`

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.

Echoed text for multi-field documents

The Cohere v1 response type only carries a single text string per echoed document. For multi-field object documents, this implementation joins the original fields as key: value lines (one per field) — an approximation, since Cohere's own algorithm for this case is not publicly documented.

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.

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.