Rerank

Order candidate documents against a query with the cruxy-rerank model.

POST /api/v1/rerank scores each candidate document against your query and returns them best-first, so you can pick the strongest matches from a shortlist. Here is a working request:

curl https://api.cruxy.ai/api/v1/rerank \
  -H "Authorization: Bearer $CRUXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cruxy-rerank",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital and largest city of France.",
      "Berlin is the capital of Germany.",
      "The Louvre is a museum in Paris.",
      "France is in Western Europe."
    ],
    "top_n": 3
  }'

const documents = [
  'Paris is the capital and largest city of France.',
  'Berlin is the capital of Germany.',
  'The Louvre is a museum in Paris.',
  'France is in Western Europe.',
]
 
const res = await fetch('https://api.cruxy.ai/api/v1/rerank', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CRUXY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'cruxy-rerank',
    query: 'What is the capital of France?',
    documents,
    top_n: 3,
  }),
})
 
const { results } = await res.json()
const top = results[0] // highest relevance_score
const topDocument = documents[top.index]

The model

model must be "cruxy-rerank". It is the only rerank model on the gateway.

Not OpenAI-compatible

Most of the gateway mirrors the OpenAI shape. This endpoint does not; it follows a Cohere-style rerank contract instead. There is no object envelope, and the results carry indices into your input, not the document text. Map each index back to your own documents array to recover the text, as the TypeScript example does above.

Request fields

Field	Type	Example	Purpose
`model`	string	`"cruxy-rerank"`	Must be `"cruxy-rerank"`.
`query`	string	`"What is the capital of France?"`	Scored against each document.
`documents`	array		Candidate strings to rank.
`top_n`	integer	`3`	Cap on how many results come back. Omit to rank every document.

Ranking and top_n

Every document is scored against query, and the response is sorted by relevance_score in descending order, the most relevant document first. top_n caps how many results return; with top_n: 3 over four documents, only the top three come back. Omit top_n to get all of them, still ranked.

Response shape

{
  "model": "cruxy-rerank",
  "results": [
    { "index": 0, "relevance_score": 0.98 },
    { "index": 2, "relevance_score": 0.71 },
    { "index": 3, "relevance_score": 0.12 }
  ],
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  },
  "cruxy": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "cost": { "tier": "cruxy-rerank" }
  }
}

Field	Meaning
`model`	Always `"cruxy-rerank"`.
`results`	Ranked entries, `relevance_score` descending, capped to `top_n`.
`index`	Position of the document in the request `documents` array.
`relevance_score`	Relevance of that document to `query`; higher is more relevant.
`usage`	`prompt_tokens` and `total_tokens` for the request.
`cruxy`	Additive block with the `request_id` and `cost` (see Chat).

Each result's index points back into the documents you sent, so read the ranked text as documents[results[i].index]. A dropped document (one below the top_n cut) has no entry.

Where it fits

Rerank and Embeddings are the two retrieval primitives on the gateway, and they work at different stages. A common pattern is to retrieve broadly with embeddings, then rerank the top candidates to settle their final order.

	Embeddings	Rerank
Model id	`cruxy-embed`	`cruxy-rerank`
What it does	Turns text into vectors you compare with cosine similarity.	Scores each candidate document against the query directly.
Best for	A first-pass search over a large corpus.	Ordering a shortlist before you use it.
Learn more	Embeddings	Retrieval-augmented generation

Errors

Rerank returns 400 for a malformed request, 401 for a bad key, and 429 for rate_limited or budget_exhausted. See Errors.

Next steps

Retrieval-augmented generation: the embeddings-to-chat recipe this endpoint sits in.
Embeddings: the vectors you retrieve candidates with.
Models: discover tiers at runtime.
Errors: the error shape.