Rerank

POST /v1/rerank takes a query and a list of candidate documents and returns them reordered by relevance, each with a score. Use it as the final stage of a retrieval pipeline: a fast first stage (vector search, BM25 or your existing store) pulls a top-k pool, then /v1/rerank scores that pool before you show results, accept a match or feed them to a generator.

How it works

/v1/rerank serves the rerank model flinq-rerank-2.0, a cross-encoder. It reads the query and each document together in a single pass, so it sees how specific query and document tokens relate. Its relevance_score is a calibrated relevance probability between 0 and 1: a score of 0.9 means the same thing for every query.

Request

/v1/rerank is a flinq-native endpoint, called with a plain HTTP client. model is required: flinq-rerank-2.0.

curl

curl https://api.flinq.ai/v1/rerank \
  -H "Authorization: Bearer flq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flinq-rerank-2.0",
    "query": "Stahlbetondecke d = 20 cm, C25/30, XC1",
    "documents": [
      "Ortbetondecke Stahlbeton, Dicke 20 cm, Beton C25/30, Expositionsklasse XC1",
      "Filigrandecke Stahlbeton, Elementdicke 5 cm, statisch mitwirkend",
      "Trapezblechdecke verzinkt, Stützweite 3,0 m"
    ],
    "task": "lv_matching",
    "top_k": 3
  }'

Python

import requests

r = requests.post(
    "https://api.flinq.ai/v1/rerank",
    headers={"Authorization": "Bearer flq_your_key_here"},
    json={
        "model": "flinq-rerank-2.0",
        "query": "Stahlbetondecke d = 20 cm, C25/30, XC1",
        "documents": [
            "Ortbetondecke Stahlbeton, Dicke 20 cm, Beton C25/30, Expositionsklasse XC1",
            "Filigrandecke Stahlbeton, Elementdicke 5 cm, statisch mitwirkend",
            "Trapezblechdecke verzinkt, Stützweite 3,0 m",
        ],
        "task": "lv_matching",
        "top_k": 3,
    },
)
ranked = r.json()["data"]  # sorted by relevance_score, index points into documents

JavaScript

const r = await fetch('https://api.flinq.ai/v1/rerank', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer flq_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'flinq-rerank-2.0',
    query: 'Stahlbetondecke d = 20 cm, C25/30, XC1',
    documents: [
      'Ortbetondecke Stahlbeton, Dicke 20 cm, Beton C25/30, Expositionsklasse XC1',
      'Filigrandecke Stahlbeton, Elementdicke 5 cm, statisch mitwirkend',
      'Trapezblechdecke verzinkt, Stützweite 3,0 m',
    ],
    task: 'lv_matching',
    top_k: 3,
  }),
});
const { data: ranked } = await r.json();

Response

{
  "object": "rerank",
  "model": "flinq-rerank-2.0",
  "data": [
    {
      "index": 0,
      "relevance_score": 0.9312,
      "text": "Ortbetondecke Stahlbeton, Dicke 20 cm, Beton C25/30, Expositionsklasse XC1"
    },
    {
      "index": 1,
      "relevance_score": 0.0874,
      "text": "Filigrandecke Stahlbeton, Elementdicke 5 cm, statisch mitwirkend"
    },
    {
      "index": 2,
      "relevance_score": 0.0021,
      "text": "Trapezblechdecke verzinkt, Stützweite 3,0 m"
    }
  ],
  "usage": { "prompt_tokens": 71, "total_tokens": 71 },
  "truncated": [],
  "warnings": []
}

Each hit keeps the original index into your documents array, a relevance_score (higher is more relevant), and the text. The scores above are illustrative.

No-match threshold

Take the best hit and accept it only above a threshold. Start around 0.5, then tune the cutoff on a hand-checked sample of your own data: raise it if wrong matches get through, lower it if correct ones end up in the no-match pile.

THRESHOLD = 0.5  # tune on a hand-checked sample

def best_match(query, candidates):
    r = requests.post(
        "https://api.flinq.ai/v1/rerank",
        headers={"Authorization": "Bearer flq_your_key_here"},
        json={"model": "flinq-rerank-2.0", "query": query,
              "documents": candidates, "task": "lv_matching", "top_k": 1},
    )
    r.raise_for_status()
    hit = r.json()["data"][0]
    if hit["relevance_score"] < THRESHOLD:
        return None  # no candidate matches
    return hit

Image documents

documents may contain images as OpenAI chat content parts, mixed with texts. The query is always text. Hits for image documents return "text": null; map them back through index.

{
  "model": "flinq-rerank-2.0",
  "query": "Attikaanschluss Flachdach mit Abdichtung, Schnitt",
  "documents": [
    { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgo..." } },
    { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQSkZJ..." } }
  ],
  "task": "image_search"
}

The image rules (formats, size limits, visual-token billing) are the same as on /v1/embeddings.

Parameters

Parameter	Type	Required	Default	Description
model	string	yes	—	flinq-rerank-2.0. An embedding model returns 422; unknown ids return 404.
query	string	yes	—	The text the pool is scored against. Never truncated: over 1,024 tokens it returns 422.
documents	array	yes	—	Candidate pool from your first retrieval stage: texts and image parts. Up to 128 documents; 422 over it. Each text document may have up to 3,000 tokens; over it returns 422, or is truncated with "truncation": "auto".
task	string	no	"retrieval"	lv_matching, image_search or retrieval. Selects the instruction the query is read with.
top_k	integer	no	all	How many of the reranked hits to return. Omit it to get the full pool reordered.
truncation	string	no	"error"	"auto" truncates over-limit text documents at the limit and lists them in truncated. The query is never truncated.

Headers. Authorization: Bearer flq_... (required); Idempotency-Key (optional) deduplicates the charge on retries.

Response fields.

Field	Type	Description
data[i].index	integer	Position of the hit in your documents array — map results back through this, not through text.
data[i].relevance_score	float	Calibrated relevance probability in [0, 1], usable as a threshold. Higher is more relevant.
data[i].text	string or null	The document text, echoed back; null for image documents.
usage.total_tokens	integer	Billed tokens (below).
truncated	integer[]	Indices of documents truncated under "truncation": "auto".
warnings	string[]	Human-readable notes.

Billing. Rerank is billed on tokens(query) + Σ tokens(documents), at EUR 0.40 / 1M, with image documents counted as their visual tokens. The query is charged once per request, so the pool size drives the cost. Keep pools pre-filtered to a top-k shortlist rather than reranking a whole corpus.