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

Example response

{
  "object": "list",
  "model": "cohere/rerank-english-v3.0",
  "results": [
    { "index": 2, "relevance_score": 0.94 },
    { "index": 0, "relevance_score": 0.61 },
    { "index": 1, "relevance_score": 0.08 }
  ],
  "usage": { "search_units": 1 }
}

A representative 200 body. Ids and timestamps are illustrative.

Body parameters

Name	Type	Default	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	optional	Return only the top-N most relevant. Defaults to all docs. Voyage callers can use top_k as an alias.
return_documents	boolean	optional	Echo document text back in each result. Defaults to false.

* required.

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

401missing_tokenNo Authorization header was sent.
401invalid_auth_schemeThe scheme was neither Bearer nor Client.
401invalid_token_formatA Bearer token not prefixed ko_.
401invalid_tokenThe API key is unknown, revoked or expired.
403insufficient_scopeThe key is valid but lacks the required scope.
400unsupported_rerank_modelModel not in the rerank catalog.
400too_many_documentsdocuments must be ≤ 1,000.
402wallet_emptyAPI pool balance is zero — top up.
503platform_not_configuredCOHERE_API_KEY / VOYAGE_API_KEY not set on the server.
503upstream_unavailableProvider returned an error.

See the full error reference.