v1
/
Transform text to graph embeddings

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
arazzo.json
arazzo.yaml
Languages
Servers
Production server
https://memory.papr.ai/

v1

Operations

Create Namespace Api Key

Request

Mint a new API key bound to the given namespace. Caller must authenticate with any API key belonging to the same organization (typically the org-wide / default-namespace key).

Security: The full key is returned exactly once in this response. Store it immediately — it cannot be retrieved later. Subsequent reads expose only the masked key_prefix.

Path
namespace_idstring(Namespace Id)required
Headers
X-API-Keystring(X-Api-Key)required
Bodyapplication/jsonrequired
namestring(Name)[ 1 .. 128 ] charactersrequired

Human-readable name for the API key (shown in admin UIs).

Example: "Acme Production API Key"
environmentstring(Environment)

Environment label: development, staging, or production.

Default "production"
Enum"development""staging""production"
Example: "production"
permissionsArray of strings(Permissions)[ 1 .. 3 ] items

Permissions granted by this key. Must be a subset of ['read', 'write', 'delete'].

Items Enum"read""write""delete"
Example: ["read","write","delete"]
curl -i -X POST \
  'https://memory.papr.ai/v1/namespace/{namespace_id}/api-keys' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -d '{
    "environment": "production",
    "name": "Acme Production API Key",
    "permissions": [
      "read",
      "write",
      "delete"
    ]
  }'

Responses

API key created

Bodyapplication/json
codeinteger(Code)

HTTP status code

Default 200
statusstring(Status)

'success' or 'error'

Default "success"
dataNamespaceApiKeyItem (object) or null

The newly created API key, including the full key string (only on creation).

Any of:

The newly created API key, including the full key string (only on creation).

errorError (string) or Error (null)(Error)

Error message if failed

Any of:

Error message if failed

string(Error)

Error message if failed

detailsDetails (any) or Details (null)(Details)

Additional error details. NEVER contains the API key.

Any of:

Additional error details. NEVER contains the API key.

any(Details)

Additional error details. NEVER contains the API key.

Response
application/json
{
  "code": 200,
  "status": "success",
  "data": {
    "objectId": "string",
    "key": "string",
    "key_prefix": "string",
    "name": "string",
    "namespace_id": "string",
    "organization_id": "string",
    "environment": "string",
    "permissions": [ … ],
    "is_active": true,
    "createdAt": "string"
  },
  "error": "string",
  "details": {}
}

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:

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.

string(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.

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)

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:

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.

string(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"
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:

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_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:

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.

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:

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.

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

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