Rerank

API version

2026-11-11 (latest)next (preview)

PreviewDownload OpenAPI (JSON)Versioning

Preview

next shows changes that are not released or not stable yet. Use the current version for production integrations.

Rerank documents

POST /api/v1/llm/v1/rerank

Cohere-compatible reranking with nebula-rerank: orders up to 256 documents by relevance to a query. Metered on input tokens at the flat Nebula input rate. Requires llm:access.

Authentication

• API key in X-API-Key
• API key or session token in Authorization: Bearer

Headers

• Idempotency-Key string

  Run this exact request at most once in 24 hours. A replay with the same key and the same body, from the same organization, user and API key, is refused with 409 before any model call. See the Idempotency guide.

  Minimum length

  1

Request body

application/json Required

• model string

  Default

  nebula-rerank

• query string Required
• documents array of strings Required

  Maximum items

  256

• top_n integer or null

  Minimum

  1

• return_documents boolean

  Default

  false

Responses

• 200 Ranked results.

  application/json

  Body (application/json)

  • id string
  • model string

    Always

    nebula-rerank

  • results array of objects
    3 fields in results

    • index integer

      Position of the document in your request.

    • relevance_score number
    • document object

      Present when return_documents is true.

      1 field in document

      • text string
  • usage object
    2 fields in usage

    • prompt_tokens integer
    • total_tokens integer
• 400 The request was malformed or failed a server-side check.Error envelope
• 401 Missing, invalid, expired or revoked credentials.Error envelope
• 402 The organization has no spendable credit, or its self-service spend cap is reached. Top up or raise the cap in the console. This status currently carries message: "Error" and code: "INTERNAL_9001"; rely on the HTTP status.Error envelope
• 403 The credential is valid but lacks a required scope or permission.Error envelope
• 409 This exact request (same Idempotency-Key and body) already ran, so it was not run again. Send a new Idempotency-Key to run it again.Error envelope
• 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

  application/json

  Headers

  • X-Request-ID string

    The request's correlation id (yours, or one BreachLine generated). Quote it to support.

  • Retry-After integer

    Seconds to wait before retrying.

  Body (application/json)

  • detail string Required
  • retry_after integer Required

    Always

    60

• 503 A dependency is temporarily unavailable. Retry with backoff; honour Retry-After when present.Error envelope

Example

cURLCopy

curl -X POST "https://api.breachline.io/api/v1/llm/v1/rerank" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Which finding affects authentication?",
    "documents": [
      "Missing rate limit on the password reset endpoint",
      "Verbose server banner on the marketing site"
    ],
    "top_n": 1
  }'

Example 200 responseCopy

{
  "id": "string",
  "model": "nebula-rerank",
  "results": [
    {
      "index": 0,
      "relevance_score": 0,
      "document": {
        "text": "string"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "total_tokens": 0
  }
}