List available domains (builtins + caller's custom domains)

Papr Memory API (1.0.0)

API for managing personal 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

Rerank candidate documents against a query

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)

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.

Default "general"

Any of:

string(Domain Id)

Default "general"

methodstring(Method)

Public: enhanced or max (CE reranker). 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 available domains (builtins + caller's custom 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[].catalog_configDomainCatalogConfig (object) or null

Catalog settings (see DomainCatalogConfig).

Any of:

Catalog settings (see DomainCatalogConfig).

domains[].catalogDomainCatalog (object) or null

Curated catalog of signal values in this domain's frequency space.

Any of:

Curated catalog of signal values in this domain's frequency space.

domains[].catalog_bufferArray of objects(Catalog Buffer)

Buffered raw signals awaiting LLM clustering (internal).

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": [
    { … }
  ]
}

Create a custom domain

Request

Bodyapplication/jsonrequired

domain_idstring(Domain Id)required

Custom id, e.g. 'acme:support_tickets:1.0.0'.

namestring(Name)required

Human-readable domain name.

descriptionstring(Description)required

What this domain models.

signalsArray of objects(Signals)non-emptyrequired

Per-domain signal definitions.

signals[].namestring(Name)required

Snake_case signal identifier.

signals[].descriptionstring(Description)required

Human prompt used by extractor.

signals[].weightnumber(Weight)

Relative weight in the fusion.

Default 1

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.

signals[].typestring(Type)

Extraction / phase type for this signal.

Default "text"

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

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.

signals[].requiredboolean(Required)

Warn when missing at extract time.

Default false

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

Domain-level default signal weight multipliers. Applied automatically on every rerank/search request for this domain (unless the caller supplies their own signal_multipliers, which take priority). Keys are field names (e.g. 'key_claim') or Hz-strings (e.g. '70.0'). Values: 0.0 = disable band, 1.0 = unchanged, 2.0 = 2× boost.

Any of:

routing_configGraphDomainRoutingConfig (object) or null

Domain-level CAESAR-VIII routing config: disabled global rules, enabled domain rule packs, optional threshold overrides.

Any of:

Domain-level CAESAR-VIII routing config: disabled global rules, enabled domain rule packs, optional threshold overrides.

catalog_configDomainCatalogConfig (object) or null

Catalog settings. When enabled (default), raw signal values are auto-accumulated on every transform call and periodically clustered by an LLM for introspection. Pass {enabled: false} to disable.

Any of:

Catalog settings. When enabled (default), raw signal values are auto-accumulated on every transform call and periodically clustered by an LLM for introspection. Pass {enabled: false} to disable.

curl -i -X POST \
  https://memory.papr.ai/v1/graph/domains \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "domain_id": "string",
    "name": "string",
    "description": "string",
    "signals": [
      {
        "name": "string",
        "description": "string",
        "weight": 1,
        "frequency_hz": 0,
        "type": "enum",
        "allowed_values": [
          "string"
        ],
        "required": false
      }
    ],
    "signal_multipliers": {
      "property1": 0,
      "property2": 0
    },
    "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"
    },
    "catalog_config": {
      "enabled": true,
      "refresh_every_n": 50
    }
  }'

Responses

Successful Response

Bodyapplication/json

domain_idstring(Domain Id)required

namestring(Name)required

descriptionstring(Description)required

signalsArray of objects(Signals)required

signals[].namestring(Name)required

Snake_case signal identifier.

signals[].descriptionstring(Description)required

Human prompt used by extractor.

signals[].weightnumber(Weight)

Relative weight in the fusion.

Default 1

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.

signals[].typestring(Type)

Extraction / phase type for this signal.

Default "text"

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

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.

signals[].requiredboolean(Required)

Warn when missing at extract time.

Default false

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

routing_configGraphDomainRoutingConfig (object) or null

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

Any of:

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

catalog_configDomainCatalogConfig (object) or null

Catalog settings (see DomainCatalogConfig).

Any of:

Catalog settings (see DomainCatalogConfig).

catalogDomainCatalog (object) or null

Curated catalog of signal values in this domain's frequency space.

Any of:

Curated catalog of signal values in this domain's frequency space.

catalog_bufferArray of objects(Catalog Buffer)

Buffered raw signals awaiting LLM clustering (internal).

builtinboolean(Builtin)

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

Default false

created_atCreated At (string) or Created At (null)(Created At)

Any of:

string(Created At)

owner_user_idOwner User Id (string) or Owner User Id (null)(Owner User Id)

Any of:

string(Owner User Id)

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.

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.

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

{
  "domain_id": "string",
  "name": "string",
  "description": "string",
  "signals": [
    { … }
  ],
  "signal_multipliers": {
    "property1": 0,
    "property2": 0
  },
  "routing_config": {
    "disabled_rules": [ … ],
    "enabled_rule_packs": [ … ],
    "threshold_overrides": { … },
    "enhanced_initial_source": "string",
    "holographic_floor": true,
    "ce_gate_min_phi": 0,
    "egr_lambda_ce": 0,
    "caesar4_source": "string"
  },
  "catalog_config": {
    "enabled": true,
    "refresh_every_n": 50
  },
  "catalog": {
    "entity_clusters": [ … ],
    "relationship_patterns": [ … ],
    "domain_distribution": { … },
    "signal_value_counts": { … },
    "total_documents": 0,
    "last_refreshed": "string",
    "last_updated": "string"
  },
  "catalog_buffer": [
    { … }
  ],
  "builtin": false,
  "created_at": "string",
  "owner_user_id": "string",
  "owner_workspace_id": "string",
  "owner_organization_id": "string",
  "owner_namespace_id": "string"
}

Memory

Operations

Memory Status

Operations

User

Operations

Feedback

Operations

Schema Management

Operations

Messages

Operations

omo

Operations

Namespace

Operations

Frequency Schemas

Operations

Holographic Transform (Deprecated)

Operations

Graph (CAESAR-8)

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

Rerank candidate documents against a query

Request

Responses

Was this helpful?

List available domains (builtins + caller's custom domains)

Request

Responses

Was this helpful?

Create a custom domain

Request

Responses

Was this helpful?

Memory

Memory Status

User

Feedback

Schema Management

Messages

omo

Namespace

Frequency Schemas

Holographic Transform (Deprecated)

Graph (CAESAR-8)

Graph Domains

Instance Configuration

AI Proxy

Sync

Telemetry

Document

GraphQL

Authentication

Papr Memory API (1.0.0)

Authentication

v1

Rerank candidate documents against a query

RequestExpand all

Responses

Was this helpful?

List available domains (builtins + caller's custom domains)

Request

Responses

Was this helpful?

Create a custom domain

RequestExpand all

Responses

Was this helpful?

Memory

Memory Status

User

Feedback

Schema Management

Messages

omo

Namespace

Frequency Schemas

Holographic Transform (Deprecated)

Graph (CAESAR-8)

Graph Domains

Instance Configuration

AI Proxy

Sync

Telemetry

Document

GraphQL

Authentication

Request

Request