Rerank documents

Papr Memory API (1.0.0)

API for managing enterprise context and memory items with authentication and user-specific data.

Authentication

This API supports three authentication methods:

API Key: Include your API key in the X-API-Key header
```
X-API-Key: <your-api-key>
```
Session Token: Include your session token in the X-Session-Token header
```
X-Session-Token: <your-session-token>
```
Bearer Token: Include your OAuth2 token from Auth0 in the Authorization header
```
Authorization: Bearer <token>
```

All endpoints require one of these authentication methods.

Download OpenAPI description

index.json

index.yaml

Servers

Production server

https://memory.papr.ai/

v1

Operations

Transform text to graph embeddings

Request

Vector-store agnostic producer.

Returns everything you'd want to index in any vector DB -- base embedding, 14-band extracted signals, per-band SBERT/Qwen embeddings, phases, and optional rot_v3 / concat reconstructions.

Uses the SAME extraction + embedding path as /v1/graph/rerank uses for queries, so artifacts produced here can be scored by /v1/graph/rerank without any drift.

Bodyapplication/jsonrequired

textstring(Text)required

Source text to transform.

embeddingArray of Embedding (numbers) or Embedding (null)(Embedding)

Optional caller-provided base embedding (Qwen 2560-d). If omitted, the server computes it.

Any of:

Optional caller-provided base embedding (Qwen 2560-d). If omitted, the server computes it.

domain_idDomain Id (string) or Domain Id (null)(Domain Id)

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.

Any of:

string(Domain Id)

metadataMetadata (object) or Metadata (null)(Metadata)

Free-form user metadata to attach (optional, not used for scoring).

Any of:

Free-form user metadata to attach (optional, not used for scoring).

signal_embedderstring(Signal Embedder)

Embedder for per-band signal vectors. 'sbert' (384d, default) is ~10x cheaper to store than 'qwen' (2560d, matched to base).

Default "sbert"

Enum"sbert""qwen"

return_rot_v3boolean(Return Rot V3)

If true, include the rot_v3 vector in the response.

Default false

return_concatboolean(Return Concat)

If true, include the base + bands concatenation embedding.

Default false

curl -i -X POST \
  https://memory.papr.ai/v1/graph/transform \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "text": "string",
    "embedding": [
      0
    ],
    "domain_id": "string",
    "metadata": {},
    "signal_embedder": "sbert",
    "return_rot_v3": false,
    "return_concat": false
  }'

Responses

Successful Response

Bodyapplication/json

phasesArray of numbers(Phases)required

Per-frequency phase angles (14-dim).

embeddingArray of numbers(Embedding)required

Base embedding (normalized Qwen 2560-d).

signalsobject(Signals)

Signal band-name -> extracted text (e.g. {'docstring': '...', 'function_name': '...'}).

signal_embeddingsobject(Signal Embeddings)

Signal band-name -> embedding vector (384-d sbert or 2560-d qwen).

rot_v3Array of Rot V3 (numbers) or Rot V3 (null)(Rot V3)

Rotation v3 vector (only when return_rot_v3=true).

Any of:

Rotation v3 vector (only when return_rot_v3=true).

concat_embeddingArray of Concat Embedding (numbers) or Concat Embedding (null)(Concat Embedding)

Base + bands concatenation (only when return_concat=true).

Any of:

Base + bands concatenation (only when return_concat=true).

idstring(Id)required

Request id for log correlation.

domain_idstring(Domain Id)required

Domain used for extraction.

metaobject(Meta)

Timing and stats.

Response

application/json

{
  "phases": [
    0
  ],
  "embedding": [
    0
  ],
  "signals": {
    "property1": "string",
    "property2": "string"
  },
  "signal_embeddings": {
    "property1": [ … ],
    "property2": [ … ]
  },
  "rot_v3": [
    0
  ],
  "concat_embedding": [
    0
  ],
  "id": "string",
  "domain_id": "string",
  "meta": {}
}

Rerank documents

Request

Bodyapplication/jsonrequired

queryQuery (string) or QueryItem (object)(Query)required

Query text (string) or QueryItem with pre-computed artifacts.

Any of:

Query text (string) or QueryItem with pre-computed artifacts.

string(Query)

Query text (string) or QueryItem with pre-computed artifacts.

documentsArray of strings or DocumentInput (object)(Documents)required

Candidate documents (string or DocumentInput with pre-computed artifacts).

Any of:

string

top_kTop K (integer) or Top K (null)(Top K)

Return at most this many results. Defaults to len(documents).

Any of:

Return at most this many results. Defaults to len(documents).

[ 1 .. 2000 ]

integer(Top K)[ 1 .. 2000 ]

Return at most this many results. Defaults to len(documents).

domain_idDomain Id (string) or Domain Id (null)(Domain Id)

Default "general"

Any of:

string(Domain Id)

Default "general"

methodstring(Method)

Public: enhanced (CAESAR-8) or max (CE+entailment). Accepts deprecated 'fast'/'enhanced' aliases.

Default "fast"

Enum"fast""enhanced"

signal_embedderstring(Signal Embedder)

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.

Default "sbert"

Enum"sbert""qwen"

signal_filtersSignal Filters (object) or Signal Filters (null)(Signal Filters)

Hard cutoffs on per-frequency signals, e.g. {'domain_match': 0.6}. Docs below are dropped.

Any of:

Hard cutoffs on per-frequency signals, e.g. {'domain_match': 0.6}. Docs below are dropped.

signal_multipliersSignal Multipliers (object) or Signal Multipliers (null)(Signal Multipliers)

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.

Any of:

routing_configGraphDomainRoutingConfig (object) or null

Per-request CAESAR-VIII routing overrides. Stacks on top of domain defaults and MongoDB graph_domains.routing_config.

Any of:

Per-request CAESAR-VIII routing overrides. Stacks on top of domain defaults and MongoDB graph_domains.routing_config.

return_signal_scoresboolean(Return Signal Scores)

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).

Default false

return_documentsboolean(Return Documents)

If true, echo back each input document in the result.

Default false

return_debugboolean(Return Debug)

If true, include CAESAR meta-signals + timing in meta.debug.

Default false

curl -i -X POST \
  https://memory.papr.ai/v1/graph/rerank \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "query": "string",
    "documents": [
      "string"
    ],
    "top_k": 1,
    "domain_id": "general",
    "method": "fast",
    "signal_embedder": "sbert",
    "signal_filters": {
      "property1": 0,
      "property2": 0
    },
    "signal_multipliers": {},
    "routing_config": {
      "disabled_rules": [
        "string"
      ],
      "enabled_rule_packs": [
        "string"
      ],
      "threshold_overrides": {
        "property1": 0,
        "property2": 0
      },
      "enhanced_initial_source": "string",
      "holographic_floor": true,
      "ce_gate_min_phi": 0,
      "egr_lambda_ce": 0,
      "caesar4_source": "string"
    },
    "return_signal_scores": false,
    "return_documents": false,
    "return_debug": false
  }'

Responses

Successful Response

Bodyapplication/json

idstring(Id)required

Request id for log correlation.

resultsArray of objects(Results)required

results[].indexinteger(Index)required

Position in the input documents array.

results[].idId (string) or Id (null)(Id)

Doc id if input was an object, else null.

Any of:

Doc id if input was an object, else null.

string(Id)

Doc id if input was an object, else null.

results[].relevance_scorenumber(Relevance Score)required

Final ranked score — the real similarity from the CAESAR-8 routed method.

results[].score_methodScore Method (string) or Score Method (null)(Score Method)

Which method CAESAR-8 routed to for this query (e.g. 'caesar7', 'baseline_rerank'). Tells you what kind of signal relevance_score reflects.

Any of:

Which method CAESAR-8 routed to for this query (e.g. 'caesar7', 'baseline_rerank'). Tells you what kind of signal relevance_score reflects.

string(Score Method)

Which method CAESAR-8 routed to for this query (e.g. 'caesar7', 'baseline_rerank'). Tells you what kind of signal relevance_score reflects.

results[].signal_scoresSignal Scores (object) or Signal Scores (null)(Signal Scores)

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.

Any of:

results[].signal_scores_by_bandSignal Scores By Band (object) or Signal Scores By Band (null)(Signal Scores By Band)

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.

Any of:

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.

results[].debug_scoresDebug Scores (object) or Debug Scores (null)(Debug Scores)

Kitchen-sink: every *_sim signal computed by the pipeline. Only if return_debug=true. NOT a stable contract — keys may change.

Any of:

Kitchen-sink: every *_sim signal computed by the pipeline. Only if return_debug=true. NOT a stable contract — keys may change.

results[].documentDocumentInput (object) or null

Echoed input doc (only if return_documents=true).

Any of:

Echoed input doc (only if return_documents=true).

metaobject(GraphMeta)required

meta.domain_idstring(Domain Id)required

meta.method_usedstring(Method Used)required

Enum"enhanced""max""fast"

meta.billed_unitsinteger(Billed Units)

Mini interactions consumed.

Default 0

meta.usageUsage (object) or Usage (null)(Usage)

Cohere/Voyage-compatible usage block, e.g. {'search_units': 1, 'docs_scored': 100}. Populated for /v1/graph/rerank and /v1/graph/search.

Any of:

Cohere/Voyage-compatible usage block, e.g. {'search_units': 1, 'docs_scored': 100}. Populated for /v1/graph/rerank and /v1/graph/search.

meta.timing_msobject(Timing Ms)

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.

meta.debugDebug (object) or Debug (null)(Debug)

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.

Any of:

Response

application/json

{
  "id": "string",
  "results": [
    { … }
  ],
  "meta": {
    "domain_id": "string",
    "method_used": "enhanced",
    "billed_units": 0,
    "usage": {},
    "timing_ms": {},
    "debug": {}
  }
}

List domains

Request

curl -i -X GET \
  https://memory.papr.ai/v1/graph/domains \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Successful Response

Bodyapplication/json

domainsArray of objects(Domains)required

domains[].domain_idstring(Domain Id)required

domains[].namestring(Name)required

domains[].descriptionstring(Description)required

domains[].signalsArray of objects(Signals)required

domains[].signals[].namestring(Name)required

Snake_case signal identifier.

domains[].signals[].descriptionstring(Description)required

Human prompt used by extractor.

domains[].signals[].weightnumber(Weight)

Relative weight in the fusion.

Default 1

domains[].signals[].frequency_hzFrequency Hz (number) or Frequency Hz (null)(Frequency Hz)

Hz band mapping (0.1 … 70.0). Auto-assigned if omitted.

Any of:

Hz band mapping (0.1 … 70.0). Auto-assigned if omitted.

number(Frequency Hz)

Hz band mapping (0.1 … 70.0). Auto-assigned if omitted.

domains[].signals[].typestring(Type)

Extraction / phase type for this signal.

Default "text"

Enum"enum""text""numeric""date""boolean""multi_value_text"

domains[].signals[].allowed_valuesArray of Allowed Values (strings) or Allowed Values (null)(Allowed Values)

For type='enum': allowed vocabulary.

Any of:

For type='enum': allowed vocabulary.

domains[].signals[].requiredboolean(Required)

Warn when missing at extract time.

Default false

domains[].signal_multipliersSignal Multipliers (object) or Signal Multipliers (null)(Signal Multipliers)

Domain-level default signal multipliers (see GraphDomainCreate).

Any of:

Domain-level default signal multipliers (see GraphDomainCreate).

domains[].routing_configGraphDomainRoutingConfig (object) or null

Domain-level CAESAR-VIII routing config (see GraphDomainRoutingConfig).

Any of:

Domain-level CAESAR-VIII routing config (see GraphDomainRoutingConfig).

domains[].builtinboolean(Builtin)

True for built-in domains shipped with Papr (read-only).

Default false

domains[].created_atCreated At (string) or Created At (null)(Created At)

Any of:

string(Created At)

domains[].owner_user_idOwner User Id (string) or Owner User Id (null)(Owner User Id)

Any of:

string(Owner User Id)

domains[].owner_workspace_idOwner Workspace Id (string) or Owner Workspace Id (null)(Owner Workspace Id)

Workspace that owns this domain. Domains are scoped to workspace when set.

Any of:

Workspace that owns this domain. Domains are scoped to workspace when set.

string(Owner Workspace Id)

Workspace that owns this domain. Domains are scoped to workspace when set.

domains[].owner_organization_idOwner Organization Id (string) or Owner Organization Id (null)(Owner Organization Id)

Organization that owns this domain.

Any of:

Organization that owns this domain.

string(Owner Organization Id)

Organization that owns this domain.

domains[].owner_namespace_idOwner Namespace Id (string) or Owner Namespace Id (null)(Owner Namespace Id)

Namespace this domain belongs to, if any.

Any of:

Namespace this domain belongs to, if any.

string(Owner Namespace Id)

Namespace this domain belongs to, if any.

Response

application/json

{
  "domains": [
    { … }
  ]
}

Memory

Operations

Memory Status

Operations

User

Operations

Feedback

Operations

Schema Management

Operations

Messages

Operations

omo

Operations

Namespace

Operations

Graph

Operations

Graph Domains

Operations

Instance Configuration

Operations

AI Proxy

Operations

Sync

Operations

Telemetry

Operations

Document

Operations

GraphQL

Operations

Authentication

Operations

Papr Memory API (1.0.0)

Authentication

v1

Transform text to graph embeddings

Request

Responses

Was this helpful?

Rerank documents

Request

Responses

Was this helpful?

List domains

Request

Responses

Was this helpful?

Memory

Memory Status

User

Feedback

Schema Management

Messages

omo

Namespace

Graph

Graph Domains

Instance Configuration

AI Proxy

Sync

Telemetry

Document

GraphQL

Authentication

Papr Memory API (1.0.0)

Authentication

v1

Transform text to graph embeddings

RequestExpand all

Responses

Was this helpful?

Rerank documents

RequestExpand all

Responses

Was this helpful?

List domains

Request

Responses

Was this helpful?

Memory

Memory Status

User

Feedback

Schema Management

Messages

omo

Namespace

Graph

Graph Domains

Instance Configuration

AI Proxy

Sync

Telemetry

Document

GraphQL

Authentication

Request

Request