Rerank by relevance scores API

Sorts candidates by externally supplied cross-encoder scores and reports new ranks plus per-item rank deltas vs the retrieval order. Answers 'How do I re-rank results by my reranker scores?', 'How much did each result move?'.

Price$0.01per request

MethodPOST

Route/v1/retrieval/rerank-by-scores

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

rerankcross-encoderrerankingscoresretrievalsortragrelevance

API URLhttps://x402.hexl.dev/v1/retrieval/rerank-by-scores

Integration docs

Example request

{
  "items": [
    {
      "id": "a",
      "retrievalRank": 0,
      "score": 0.1
    },
    {
      "id": "b",
      "retrievalRank": 1,
      "score": 0.9
    }
  ]
}

Example response

{
  "reranked": [
    {
      "id": "b",
      "score": 0.9,
      "newRank": 0,
      "previousRank": 1,
      "rankDelta": 1
    },
    {
      "id": "a",
      "score": 0.1,
      "newRank": 1,
      "previousRank": 0,
      "rankDelta": -1
    }
  ],
  "totalItems": 2,
  "topK": 2
}

Input schema

{
  "type": "object",
  "required": [
    "items"
  ],
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "topK": {
      "type": "number"
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}