Rerank documents

Reorders input documents by relevance to a query.

POST /v1/rerank

Error

A valid request URL is required to generate request examples

200

{
  "results": [
    {
      "index": 1,
      "relevance_score": 123,
      "document": {
        "text": "<string>",
        "id": "<string>",
        "meta": {}
      }
    }
  ],
  "model": "<string>",
  "id": "<string>",
  "usage": {
    "prompt_tokens": 123,
    "prompt_tokens_details": {
      "text_tokens": 123,
      "audio_tokens": 123,
      "image_tokens": 123,
      "cached_read_tokens": 123,
      "cached_write_tokens": 123
    },
    "completion_tokens": 123,
    "completion_tokens_details": {
      "text_tokens": 123,
      "accepted_prediction_tokens": 123,
      "audio_tokens": 123,
      "citation_tokens": 123,
      "num_search_queries": 123,
      "reasoning_tokens": 123,
      "image_tokens": 123,
      "rejected_prediction_tokens": 123
    },
    "total_tokens": 123,
    "cost": {
      "input_tokens_cost": 123,
      "output_tokens_cost": 123,
      "reasoning_tokens_cost": 123,
      "citation_tokens_cost": 123,
      "search_queries_cost": 123,
      "request_cost": 123,
      "total_cost": 123
    }
  },
  "extra_fields": {
    "request_type": "<string>",
    "model_requested": "<string>",
    "model_deployment": "<string>",
    "latency": 123,
    "chunk_index": 123,
    "raw_request": {},
    "raw_response": {},
    "cache_debug": {
      "cache_hit": true,
      "cache_id": "<string>",
      "hit_type": "<string>",
      "requested_provider": "<string>",
      "requested_model": "<string>",
      "provider_used": "<string>",
      "model_used": "<string>",
      "input_tokens": 123,
      "threshold": 123,
      "similarity": 123
    }
  }
}

{
  "event_id": "<string>",
  "type": "<string>",
  "is_bifrost_error": true,
  "status_code": 123,
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "event_id": "<string>"
  },
  "extra_fields": {
    "model_requested": "<string>",
    "request_type": "<string>"
  }
}

{
  "event_id": "<string>",
  "type": "<string>",
  "is_bifrost_error": true,
  "status_code": 123,
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "event_id": "<string>"
  },
  "extra_fields": {
    "model_requested": "<string>",
    "request_type": "<string>"
  }
}

Authorizations

BearerAuthBasicAuthVirtualKeyAuthApiKeyAuth

Authorization · string · header · required

Bearer token authentication. Use your provider API key or Bifrost authentication token. Virtual keys (prefixed with sk-bf-) can also be passed here.

Body

application/json

model · string · required

Model in provider/model format

Example:

"cohere/rerank-v3.5"

query · string · required

Query used to score and reorder documents

Minimum string length: 1

documents · object[] · required

Documents to rerank

Minimum array length: 1

Show child attributes

fallbacks · string[]

Fallback models in provider/model format

top_n · integer

Maximum number of ranked results to return

Required range: x >= 1

max_tokens_per_doc · integer

Maximum tokens to consider per document (provider-dependent)

Required range: x >= 1

priority · integer

Request priority hint (provider-dependent)

return_documents · boolean

Whether to include document content in each result

Response

200

application/json

Successful response

results · object[] · required

Ranked results ordered by relevance score descending

Show child attributes

model · string · required

Model used to perform reranking

id · string

Unique identifier for the rerank response

usage · object

Token usage information

Show child attributes

extra_fields · object

Additional fields included in responses

Show child attributes