POST/v1/rerank

Rerank

Score documents by relevance to a query — the second stage of two-pass retrieval (vector search → rerank). Wire shape mirrors Cohere /v2/rerank. Models: fc:cohere/rerank-v3.5, fc:cohere/rerank-multilingual-v3.0, fc:voyage/rerank-2, fc:voyage/rerank-2-lite.

Request

HTTP: POST
URL: /v1/rerank
Auth: api_key, client_token

Try it

curl https://api.fightclub.pro/v1/rerank \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fc:cohere/rerank-v3.5",
    "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,
    "return_documents": true
  }'

Parameters

Name	Type	Description
model*	string	fc:cohere/rerank-v3.5 \| fc:voyage/rerank-2 \| …
query*	string	Search query. Max 10,000 chars.
documents*	string[]	Candidates to rank. Max 1,000 docs, 100,000 chars each.
top_n	integer	Return only the top-N most relevant. Defaults to all docs. Voyage callers can use top_k as an alias.
return_documents	boolean	Echo document text back in each result. Defaults to false.

Response fields

Name	Type	Description
id	string	Request ID (req_*).
model	string	Resolved provider/model.
results	array	{ index, relevance_score, document? } sorted by relevance.
usage	object	{ search_units: 1 } — billed per call.

Errors

401invalid_api_key, Missing or revoked key.
400unsupported_rerank_model, Model not in the rerank catalog.
400too_many_documents, documents must be ≤ 1,000.
402wallet_empty, API pool balance is zero — top up.
503platform_not_configured, COHERE_API_KEY / VOYAGE_API_KEY not set on the server.
503upstream_unavailable, Provider returned an error.

See the full error reference.