---
title: "Rerank candidate documents against a query"
method: POST
path: "/v1/graph/rerank"
tags: ["v1", "Graph (CAESAR-8)"]
---

# Rerank candidate documents against a query

`POST /v1/graph/rerank`

## Request body

- GraphRerankRequest — Rerank candidate documents against a query. Simple usage: pass query as string and documents as strings. Optimized usage: pass query as QueryItem with pre-computed artifacts from /v1/graph/transform to skip LLM extraction (~10x faster).
  - `query` union, required — Query text (string) or QueryItem with pre-computed artifacts.
    - string
    - QueryItem — Query with optional pre-computed artifacts from /v1/graph/transform. Similar to DocumentInput but for queries. Pass pre-computed artifacts to skip LLM extraction and embedding for faster reranking.
      - `text` string, required — Query text.
      - `embedding` number[], nullable — Pre-computed base embedding. Skips embedder call.
      - `signals` object, nullable — Pre-extracted signal band-name -> text. Skips LLM extractor.
      - `signal_embeddings` object, nullable — Pre-computed signal band-name -> vector. Skips per-band embed.
      - `phases` number[], nullable — Pre-computed per-frequency phase angles (14-dim).
      - `rot_v3` number[], nullable — Pre-computed rotation v3 vector.
      - `concat_embedding` number[], nullable — Pre-computed concat reconstruction.
  - `documents` union[], required — Candidate documents (string or DocumentInput with pre-computed artifacts).
    - union
      - string
      - DocumentInput — Object form of a document (when developer wants to attach an id/metadata). Either ``embedding`` or ``text`` should be set; both are accepted by the rerank pipeline. ``metadata`` round-trips into the response if requested. BYO artifact fields (``signals``, ``signal_embeddings``, ``phases``, ``rot_v3``, ``concat_embedding``) are all optional and let callers skip the per-doc extract+embed pass at scoring time. They map 1:1 to the producer fields returned by /v1/graph/transform.
        - `id` string, nullable — Stable doc identifier echoed back in results.
        - `text` string, nullable — Document text (if not BYOE).
        - `embedding` number[], nullable — Pre-computed base embedding (BYOE). Qwen 2560-d expected.
        - `metadata` object, nullable — Free-form user metadata, echoed back if return_documents=true.
        - `signals` object, nullable — Pre-extracted signal band-name -> text. If provided, the LLM extractor is skipped for this doc.
        - `signal_embeddings` object, nullable — Pre-computed signal band-name -> vector (typically 384d sbert). If provided, per-band embedding step is skipped.
        - `phases` number[], nullable — Pre-computed per-frequency phase angles (14-dim). If provided, phase computation is skipped.
        - `rot_v3` number[], nullable — Pre-computed rotation v3 vector.
        - `concat_embedding` number[], nullable — Pre-computed concat reconstruction.
  - `top_k` integer, nullable — Return at most this many results. Defaults to len(documents).
  - `domain_id` string, nullable — Domain shortname or full schema id controlling which frequency bands and extraction rules are used. Built-in shortnames: "general" (default), "code", "cosqa", "codetrans", "codetransocean", "codetransocean_hybrid", "text2sql", "scifact", "nfcorpus", "fiqa", "legal", "medical", "ecommerce", "coffee_shops". You can also pass a full schema id (e.g. "code_search:cosqa:2.0.0") or a custom domain_id registered via POST /v1/graph/domains.
  - `method` 'fast' | 'enhanced' — Public: enhanced (CAESAR-8) or max (CE+entailment). Accepts deprecated 'fast'/'enhanced' aliases.
  - `signal_embedder` 'sbert' | 'qwen' — Embedder for per-band signal vectors when extracting query/docs. 'sbert' (384d, default) is ~10x cheaper to store than 'qwen' (2560d). Must match the embedder used for any BYO signal_embeddings.
  - `signal_filters` object, nullable — Hard cutoffs on per-frequency signals, e.g. {'domain_match': 0.6}. Docs below are dropped.
  - `signal_multipliers` object, nullable — Per-frequency scoring weight multipliers. Keys may be field names (e.g. 'claim_stance', 'causal_verb') or Hz-strings (e.g. '19.0'). Values: 'auto' (default) or 1.0 = unchanged, 2.0 = 2x boost, 0.0 = disable that band. Fields not specified default to 'auto'. Stacks on top of the schema-level FrequencyField.weight multipliers; request-level overrides win on conflict.
  - `routing_config` GraphDomainRoutingConfig — Domain-scoped CAESAR-VIII routing overrides (stored on graph_domains).
    - `disabled_rules` string[], nullable — Global SciFact routing rule names to skip for this domain (e.g. 'DANGER_LOW_RSG_LOW_PHI').
    - `enabled_rule_packs` string[], nullable — Named domain rule packs to run after global rules (e.g. 'cosqa_caesar8_v2').
    - `threshold_overrides` object, nullable — Optional CaesarConfig field overrides keyed by threshold name (e.g. {'cmas_c4_trust_jaccard_threshold': 0.95}).
    - `enhanced_initial_source` string, nullable — CAESAR-VIII initial source for the CE-on path. Domain defaults may pin 'caesar4_5_v4a' on code_search for public enhanced; public max overrides to 'caesar7' unless this field is set.
    - `holographic_floor` boolean, nullable — When true, never return a ranking worse than max(v4a, baseline) unless CE gate (ce_gate_min_phi) passes.
    - `ce_gate_min_phi` number, nullable — Minimum phi to allow caesar7/baseline_rerank to bypass holographic floor.
    - `egr_lambda_ce` number, nullable — Stacked EGR entailment fusion weight (0–1). Lower for code domains.
    - `caesar4_source` string, nullable — Which ranking is exposed as rankings['caesar4'] to CAESAR-VIII rules (c4_c7_diverge, etc.). Accepts 'v4a' (default — alias to family-routed v4a / v3a fallback), 'v3a' (force v3a only), or 'legacy' (SKIP the alias; keep the original Jaccard / trust-score selection at rankings['caesar4'] and stash a copy at rankings['_caesar4_legacy']). Use 'legacy' to A/B C-VIII rules against the original SciFact calibration semantics. Label-free in all modes.
  - `return_signal_scores` boolean — If true, each result carries `signal_scores` (method-level scores like `base_sim`, `caesar8_score`) and `signal_scores_by_band` (per-frequency band alignments such as `key_apis`, `language`).
  - `return_documents` boolean — If true, echo back each input document in the result.
  - `return_debug` boolean — If true, include CAESAR meta-signals + timing in `meta.debug`.

## Response `200`

Successful Response

- GraphRerankResponse
  - `id` string, required — Request id for log correlation.
  - `results` ServicesHolographicEmbeddingGraphModelsRerankResultItem[], required
    - `index` integer, required — Position in the input documents array.
    - `id` string, nullable — Doc id if input was an object, else null.
    - `relevance_score` number, required — Final ranked score — the real similarity from the CAESAR-8 routed method.
    - `score_method` string, nullable — Which method CAESAR-8 routed to for this query (e.g. 'caesar7', 'baseline_rerank'). Tells you what kind of signal `relevance_score` reflects.
    - `signal_scores` object, nullable — Stable, documented signals (only if return_signal_scores=true). Always includes `base_sim` and `caesar8_score`. On `enhanced` method, also includes `rot_k{32,128,256,512}_sim` low-rank rotation variants.
    - `signal_scores_by_band` object, nullable — Per-band signal similarities, keyed by band name (e.g. {'causal_agent': 0.83, 'causal_verb': 0.91}). Only set if return_signal_scores=true and the pipeline computed gated SFI.
    - `debug_scores` object, nullable — Kitchen-sink: every *_sim signal computed by the pipeline. Only if return_debug=true. NOT a stable contract — keys may change.
    - `document` DocumentInput — Object form of a document (when developer wants to attach an id/metadata). Either ``embedding`` or ``text`` should be set; both are accepted by the rerank pipeline. ``metadata`` round-trips into the response if requested. BYO artifact fields (``signals``, ``signal_embeddings``, ``phases``, ``rot_v3``, ``concat_embedding``) are all optional and let callers skip the per-doc extract+embed pass at scoring time. They map 1:1 to the producer fields returned by /v1/graph/transform.
      - `id` string, nullable — Stable doc identifier echoed back in results.
      - `text` string, nullable — Document text (if not BYOE).
      - `embedding` number[], nullable — Pre-computed base embedding (BYOE). Qwen 2560-d expected.
      - `metadata` object, nullable — Free-form user metadata, echoed back if return_documents=true.
      - `signals` object, nullable — Pre-extracted signal band-name -> text. If provided, the LLM extractor is skipped for this doc.
      - `signal_embeddings` object, nullable — Pre-computed signal band-name -> vector (typically 384d sbert). If provided, per-band embedding step is skipped.
      - `phases` number[], nullable — Pre-computed per-frequency phase angles (14-dim). If provided, phase computation is skipped.
      - `rot_v3` number[], nullable — Pre-computed rotation v3 vector.
      - `concat_embedding` number[], nullable — Pre-computed concat reconstruction.
  - `meta` GraphMeta, required
    - `domain_id` string, required
    - `method_used` 'enhanced' | 'max' | 'fast', required
    - `billed_units` integer — Mini interactions consumed.
    - `usage` object, nullable — Cohere/Voyage-compatible usage block, e.g. {'search_units': 1, 'docs_scored': 100}. Populated for /v1/graph/rerank and /v1/graph/search.
    - `timing_ms` object — Latency breakdown in milliseconds. Top-level keys: `services_init`, `pipeline`, `total`. Optional `phases` is a nested dict with per-stage timings: query_processing, retrieval, rerank, caesar_routing.
    - `debug` object, nullable — Debug payload when return_debug=true. Includes: `selection_signals` (scalar routing inputs), `v3a_routing` / `v4a_routing` (method selection diagnostics), `routing_signals` (method_bgrs, method_t1lrs, pool quality), `spread_signals` (gauss/sfi/hcond spread boosters), `signal_multipliers`, `signal_weights`, `signal_weights_sparse`, `routing_config`, `domain_method_priors`, `doc_scores` (per-doc method score vectors), `router_state` (v4a EMA snapshot), `rule_fired`, `zone`, `caesar8_mode`. Per-phase timings live in `timing_ms.phases`.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/papr-ai/apis/papr-memory-api.md) · [All operations](https://skmtc.net/papr-ai/apis/papr-memory-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/papr-ai/papr-memory-api/revisions/b553be9aad37/schema)