API Reference
/
v1
/
Rerank search results using holographic scoring

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
Languages
Servers
Production server
https://memoryserver-staging-223473570766.us-west1.run.app/

v1

Operations

Batch transform multiple items

Request

Transform up to 50 items in a single request. Same as /transform but batched.

Bodyapplication/jsonrequired
itemsArray of objects(Items)<= 50 itemsrequired

Items to transform (max 50)

items[].​idstring(Id)required

Unique identifier for this item

items[].​contentstring(Content)required

Text content for metadata extraction

items[].​embeddingArray of numbers(Embedding)required

Base embedding vector

items[].​context_metadataContext Metadata (object) or Context Metadata (null)(Context Metadata)

Optional context metadata for this item (createdAt, sourceType, etc.)

Any of:

Optional context metadata for this item (createdAt, sourceType, etc.)

domainDomain (string) or Domain (null)(Domain)

Domain for all items

Default "general"
Any of:

Domain for all items

string(Domain)

Domain for all items

Default "general"
frequency_schema_idFrequency Schema Id (string) or Frequency Schema Id (null)(Frequency Schema Id)

Schema override for all items

Any of:

Schema override for all items

string(Frequency Schema Id)

Schema override for all items

outputArray of Output (strings) or Output (null)(Output)

Which output fields to return for each item

Any of:

Which output fields to return for each item

curl -i -X POST \
  https://memoryserver-staging-223473570766.us-west1.run.app/v1/holographic/transform/batch \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "items": [
      {
        "id": "string",
        "content": "string",
        "embedding": [
          0
        ],
        "context_metadata": {}
      }
    ],
    "domain": "general",
    "frequency_schema_id": "string",
    "output": [
      "base"
    ]
  }'

Responses

Successful Response

Bodyapplication/json
statusstring(Status)
Default "success"
resultsArray of objects(Results)required
results[].​idstring(Id)required
results[].​dataobject(TransformData)required

Inner data for transform response — only requested fields are populated.

results[].​data.​baseArray of Base (numbers) or Base (null)(Base)

Original embedding echoed back

Any of:

Original embedding echoed back

results[].​data.​rotation_v1Array of Rotation V1 (numbers) or Rotation V1 (null)(Rotation V1)

Rotation V1 transform (same dims as input)

Any of:

Rotation V1 transform (same dims as input)

results[].​data.​rotation_v2Array of Rotation V2 (numbers) or Rotation V2 (null)(Rotation V2)

Rotation V2 transform (same dims as input)

Any of:

Rotation V2 transform (same dims as input)

results[].​data.​rotation_v3Array of Rotation V3 (numbers) or Rotation V3 (null)(Rotation V3)

Rotation V3 transform (recommended for search, same dims as input)

Any of:

Rotation V3 transform (recommended for search, same dims as input)

results[].​data.​concatArray of Concat (numbers) or Concat (null)(Concat)

Concatenation transform (input_dims + 196)

Any of:

Concatenation transform (input_dims + 196)

results[].​data.​phasesArray of Phases (numbers) or Phases (null)(Phases)

14 raw phase values for on-device reconstruction and fast-path rerank

Any of:

14 raw phase values for on-device reconstruction and fast-path rerank

results[].​data.​metadataMetadata (object) or Metadata (null)(Metadata)

LLM-extracted metadata keyed by frequency field name

Any of:

LLM-extracted metadata keyed by frequency field name

results[].​data.​metadata_embeddingsMetadata Embeddings (object) or Metadata Embeddings (null)(Metadata Embeddings)

Per-frequency metadata embeddings

Any of:

Per-frequency metadata embeddings

results[].​data.​domainstring(Domain)required

Domain used for this transform

results[].​data.​frequency_schema_idstring(Frequency Schema Id)required

Exact frequency schema ID used

results[].​data.​base_diminteger(Base Dim)required

Input embedding dimensionality

results[].​data.​timing_msnumber(Timing Ms)required

Server-side processing time in milliseconds

totalinteger(Total)required
timing_msnumber(Timing Ms)required
Response
application/json
{
  "status": "success",
  "results": [
    { … }
  ],
  "total": 0,
  "timing_ms": 0
}

Rerank search results using holographic scoring

Request

The simplest entry point — zero infrastructure needed. Send your search query and candidate results, get back better-ranked results using CAESAR ensemble.

Auto-detection: candidates with phases use the fast path (~2-5ms each). Candidates with only content use the cold path (~100ms each, includes LLM extraction). You can mix both in a single request.

Bodyapplication/jsonrequired
querystring(Query)required

The search query text

Example: "How does troponin relate to myocardial infarction?"
query_embeddingArray of Query Embedding (numbers) or Query Embedding (null)(Query Embedding)

Query embedding in the same space as candidate embeddings. If provided, used for cosine similarity. If omitted, computed server-side (Qwen 2560d).

Any of:

Query embedding in the same space as candidate embeddings. If provided, used for cosine similarity. If omitted, computed server-side (Qwen 2560d).

query_phasesArray of Query Phases (numbers) or Query Phases (null)(Query Phases)

Pre-computed query phases from a prior /transform call. If provided alongside query_embedding, skips LLM extraction entirely (hot path).

Any of:

Pre-computed query phases from a prior /transform call. If provided alongside query_embedding, skips LLM extraction entirely (hot path).

query_metadata_embeddingsQuery Metadata Embeddings (object) or Query Metadata Embeddings (null)(Query Metadata Embeddings)

Pre-computed query metadata embeddings from a prior /transform call (keyed by frequency string, e.g. '0.1'). Required for full HCond scoring with phase alignment.

Any of:

Pre-computed query metadata embeddings from a prior /transform call (keyed by frequency string, e.g. '0.1'). Required for full HCond scoring with phase alignment.

candidatesArray of objects(Candidates)<= 100 itemsrequired

Candidate documents to rerank (max 100)

Example: [{"content":"Troponin is a cardiac biomarker released during myocardial injury...","id":"doc_1"},{"content":"Aspirin reduces platelet aggregation...","id":"doc_2"}]
candidates[].​idstring(Id)required

Unique identifier

candidates[].​contentContent (string) or Content (null)(Content)

Text content. Required for cold path (LLM extraction + cross-encoder).

Any of:

Text content. Required for cold path (LLM extraction + cross-encoder).

string(Content)

Text content. Required for cold path (LLM extraction + cross-encoder).

candidates[].​embeddingArray of Embedding (numbers) or Embedding (null)(Embedding)

Base embedding. If missing and content provided, computed server-side.

Any of:

Base embedding. If missing and content provided, computed server-side.

candidates[].​phasesArray of Phases (numbers) or Phases (null)(Phases)

Pre-computed phases from a prior /transform call. Enables fast path.

Any of:

Pre-computed phases from a prior /transform call. Enables fast path.

candidates[].​metadata_embeddingsMetadata Embeddings (object) or Metadata Embeddings (null)(Metadata Embeddings)

Pre-computed SBERT metadata embeddings from a prior /transform call (keyed by frequency string, e.g. '0.1'). Enables full HCond scoring.

Any of:

Pre-computed SBERT metadata embeddings from a prior /transform call (keyed by frequency string, e.g. '0.1'). Enables full HCond scoring.

candidates[].​context_metadataContext Metadata (object) or Context Metadata (null)(Context Metadata)

Optional context metadata for cold-path LLM extraction (createdAt, sourceType, etc.)

Any of:

Optional context metadata for cold-path LLM extraction (createdAt, sourceType, etc.)

candidates[].​scoreScore (number) or Score (null)(Score)

Original retrieval score (used as a signal in ensemble methods)

Any of:

Original retrieval score (used as a signal in ensemble methods)

number(Score)

Original retrieval score (used as a signal in ensemble methods)

domainDomain (string) or Domain (null)(Domain)

Domain for frequency schema

Default "general"
Example: "biomedical"
Any of:

Domain for frequency schema

string(Domain)

Domain for frequency schema

Default "general"
frequency_schema_idFrequency Schema Id (string) or Frequency Schema Id (null)(Frequency Schema Id)

Schema override

Any of:

Schema override

string(Frequency Schema Id)

Schema override

top_kinteger(Top K)[ 1 .. 100 ]

Number of results to return

Default 10
Example: 10
optionsRerankOptions (object) or null

Reranking options

Any of:

Reranking options

curl -i -X POST \
  https://memoryserver-staging-223473570766.us-west1.run.app/v1/holographic/rerank \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "candidates": [
      {
        "content": "Troponin is a cardiac biomarker released during myocardial injury...",
        "id": "doc_1"
      },
      {
        "content": "Aspirin reduces platelet aggregation...",
        "id": "doc_2"
      }
    ],
    "domain": "biomedical",
    "query": "How does troponin relate to myocardial infarction?",
    "top_k": 10
  }'

Responses

Successful Response

Bodyapplication/json
statusstring(Status)
Default "success"
dataobject(RerankData)required
data.​rankingsArray of objects(Rankings)required
data.​rankings[].​idstring(Id)required
data.​rankings[].​rankinteger(Rank)required
data.​rankings[].​scorenumber(Score)required

Ensemble score

data.​rankings[].​original_scoreOriginal Score (number) or Original Score (null)(Original Score)

Original retrieval score if provided

Any of:

Original retrieval score if provided

number(Original Score)

Original retrieval score if provided

data.​rankings[].​pathstring(Path)required

'fast' (phases provided) or 'cold' (content-only)

data.​rankings[].​scoresScores (object) or Scores (null)(Scores)

Per-method score breakdown (if return_scores=true)

Any of:

Per-method score breakdown (if return_scores=true)

data.​rankings[].​frequency_scoresFrequency Scores (object) or Frequency Scores (null)(Frequency Scores)

Per-frequency-field alignment scores (when options.include_frequency_scores=true).

Any of:

Per-frequency-field alignment scores (when options.include_frequency_scores=true).

data.​ensemble_usedstring(Ensemble Used)required
data.​domainstring(Domain)required
data.​timing_msnumber(Timing Ms)required
data.​optimization_hintOptimization Hint (string) or Optimization Hint (null)(Optimization Hint)

Present when cold path was used. Suggests storing phases for faster reranking.

Any of:

Present when cold path was used. Suggests storing phases for faster reranking.

string(Optimization Hint)

Present when cold path was used. Suggests storing phases for faster reranking.

Response
application/json
{
  "status": "success",
  "data": {
    "rankings": [ … ],
    "ensemble_used": "string",
    "domain": "string",
    "timing_ms": 0,
    "optimization_hint": "string"
  }
}

Extract metadata only (for on-device transform)

Request

Extracts frequency metadata from text content without requiring an embedding. Returns metadata + phases that can be used with the on-device SDK for local transforms. Call this once per document at index time, then use phases locally for scoring.

Bodyapplication/jsonrequired
contentstring(Content)required

Text content for metadata extraction

domainDomain (string) or Domain (null)(Domain)

Domain for frequency schema

Default "general"
Any of:

Domain for frequency schema

string(Domain)

Domain for frequency schema

Default "general"
frequency_schema_idFrequency Schema Id (string) or Frequency Schema Id (null)(Frequency Schema Id)

Schema override

Any of:

Schema override

string(Frequency Schema Id)

Schema override

context_metadataContext Metadata (object) or Context Metadata (null)(Context Metadata)

Optional context metadata (createdAt, sourceType, etc.) to improve extraction.

Any of:

Optional context metadata (createdAt, sourceType, etc.) to improve extraction.

curl -i -X POST \
  https://memoryserver-staging-223473570766.us-west1.run.app/v1/holographic/metadata \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "content": "string",
    "domain": "general",
    "frequency_schema_id": "string",
    "context_metadata": {}
  }'

Responses

Successful Response

Bodyapplication/json
statusstring(Status)
Default "success"
dataobject(MetadataData)required
data.​metadataobject(Metadata)required

LLM-extracted metadata keyed by frequency field name

data.​metadata.​property name*anyadditional property
data.​phasesArray of numbers(Phases)required

14 phase values for on-device transform

data.​domainstring(Domain)required
data.​frequency_schema_idstring(Frequency Schema Id)required
data.​timing_msnumber(Timing Ms)required
Response
application/json
{
  "status": "success",
  "data": {
    "metadata": {},
    "phases": [ … ],
    "domain": "string",
    "frequency_schema_id": "string",
    "timing_ms": 0
  }
}

Memory

Operations

Memory Status

Operations

User

Operations

Feedback

Operations

Schema Management

Operations

Messages

Operations

omo

Operations

Namespace

Operations

Frequency Schemas

Operations

Holographic Transform

Operations

Instance Configuration

Operations

AI Proxy

Operations

Sync

Operations

Telemetry

Operations

Document

Operations

GraphQL

Operations

Authentication

Operations