Reranker

Cross-encoder reranker for retrieval pipelines. Non-OpenAI extension — schema follows Cohere's /rerank API.

POST https://api.ecohash.com/v1/rerank

Headers

Header	Value
Authorization	Bearer eco_YOUR_KEY
Content-Type	application/json

Request body

Field	Type	Required	Notes
model	string	yes	Reranker model ID
query	string	yes	User's query
documents	array of strings	yes	Candidate documents to rerank — 1 to 1000
top_n	integer	no	Return only the top N scoring documents (default: all)
return_documents	bool	no	Include the document text in each result (default: false)

Example request

curl https://api.ecohash.com/v1/rerank \
  -H "Authorization: Bearer eco_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "how does solar power work?",
    "documents": [
      "Solar panels convert sunlight into electricity.",
      "My cat enjoys the sun but cannot generate power.",
      "Photovoltaic cells transform photons into electric current."
    ],
    "top_n": 2
  }'

Response body

{
  "results": [
    { "index": 0, "relevance_score": 0.987 },
    { "index": 2, "relevance_score": 0.945 }
  ],
  "model": "bge-reranker-v2-m3",
  "usage": { "total_tokens": 64 }
}

results is sorted by relevance_score descending. index maps back to the original documents array position.

If return_documents: true, each result also includes a document: {text: "..."} field.

Errors

See Errors. Common: 401, 402, 404, 429.