Get Memory Status

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://memoryserver-staging-223473570766.us-west1.run.app/

v1

Operations

Add Memory V1

Request

Add a new memory item to the system with size validation and background processing.

Authentication Required: One of the following authentication methods must be used:

Bearer token in Authorization header
API Key in X-API-Key header
Session token in X-Session-Token header

Required Headers:

Content-Type: application/json
X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')

Role-Based Memory Categories:

User memories: preference, task, goal, facts, context
Assistant memories: skills, learning

New Metadata Fields:

metadata.role: Optional field to specify who generated the memory (user or assistant)
metadata.category: Optional field for memory categorization based on role
Both fields are stored within metadata at the same level as topics, location, etc.

The API validates content size against MAX_CONTENT_LENGTH environment variable (defaults to 15000 bytes).

Query

skip_background_processingboolean(Skip Background Processing)

If True, skips adding background tasks for processing

Default false

enable_holographicboolean(Enable Holographic)

If True, applies holographic neural transforms and stores in holographic collection

Default false

frequency_schema_idFrequency Schema Id (string) or Frequency Schema Id (null)(Frequency Schema Id)

Frequency schema for holographic embedding (e.g. 'cosqa', 'scifact'). Required when enable_holographic=True. Call GET /v1/frequencies to see available schemas.

Any of:

Frequency schema for holographic embedding (e.g. 'cosqa', 'scifact'). Required when enable_holographic=True. Call GET /v1/frequencies to see available schemas.

string(Frequency Schema Id)

Frequency schema for holographic embedding (e.g. 'cosqa', 'scifact'). Required when enable_holographic=True. Call GET /v1/frequencies to see available schemas.

formatFormat (string) or Format (null)(Format)

Response format. Use 'omo' for Open Memory Object standard format (portable across platforms).

Any of:

Response format. Use 'omo' for Open Memory Object standard format (portable across platforms).

string(Format)

Response format. Use 'omo' for Open Memory Object standard format (portable across platforms).

webhook_urlWebhook Url (string) or Webhook Url (null)(Webhook Url)

Webhook URL to notify when background processing completes. Receives POST with {event, memory_id, status, completed_at}.

Any of:

Webhook URL to notify when background processing completes. Receives POST with {event, memory_id, status, completed_at}.

string(Webhook Url)

Webhook URL to notify when background processing completes. Receives POST with {event, memory_id, status, completed_at}.

webhook_secretWebhook Secret (string) or Webhook Secret (null)(Webhook Secret)

Secret for webhook HMAC authentication. Sent as X-Webhook-Secret header and used to generate X-Webhook-Signature.

Any of:

Secret for webhook HMAC authentication. Sent as X-Webhook-Secret header and used to generate X-Webhook-Signature.

string(Webhook Secret)

Secret for webhook HMAC authentication. Sent as X-Webhook-Secret header and used to generate X-Webhook-Signature.

Bodyapplication/jsonrequired

memory_policyMemoryPolicy (object) or null

Unified policy for graph generation and OMO safety. Use mode='auto' (LLM extraction, constraints applied if provided) or 'manual' (exact nodes). Includes consent, risk, and ACL settings. If schema_id is set, schema's memory_policy is used as defaults.

Any of:

link_toLink To (string) or Array of Link To (strings) or Link To (object) or Link To (null)(Link To)

Shorthand DSL for node/edge constraints. Expands to memory_policy.node_constraints and edge_constraints. Formats: - String: 'Task:title' (semantic match on Task.title) - List: ['Task:title', 'Person:email'] (multiple constraints) - Dict: {'Task:title': {'set': {...}}} (with options) Syntax: - Node: 'Type:property', 'Type:prop=value' (exact), 'Type:prop~value' (semantic) - Edge: 'Source->EDGE->Target:property' (arrow syntax) - Via: 'Type.via(EDGE->Target:prop)' (relationship traversal) - Special: '$this', '$previous', '$context:N' Example: 'SecurityBehavior->MITIGATES->TacticDef:name' with {'create': 'never'}

Any of:

string(Link To)

contentstring(Content)required

The content of the memory item you want to add to memory

Example: "Meeting with John Smith from Acme Corp about the Q4 project timeline"

typestring(MemoryType)

Memory item type; defaults to 'text' if omitted

Default "text"

Enum"text""code_snippet""document"

Example: "text"

namespace_idNamespace Id (string) or Namespace Id (null)(Namespace Id)

Optional namespace ID for multi-tenant memory scoping. When provided, memory is associated with this namespace.

Any of:

Optional namespace ID for multi-tenant memory scoping. When provided, memory is associated with this namespace.

string(Namespace Id)

Optional namespace ID for multi-tenant memory scoping. When provided, memory is associated with this namespace.

external_user_idExternal User Id (string) or External User Id (null)(External User Id)

Your application's user identifier. This is the primary way to identify users. Use this for your app's user IDs (e.g., 'user_alice_123', UUID, email). Papr will automatically resolve or create internal users as needed.

Any of:

string(External User Id)

metadataMemoryMetadata (object) or null

Metadata used in graph and vector store for a memory item. Include role and category here.

Example: {"conversationId":"conv-123","createdAt":"2024-10-04T10:00:00Z","emoji_tags":"📅,👥,📋","emotion_tags":"focused, productive","external_user_id":"external_user_123","external_user_read_access":["external_user_123","external_user_789"],"external_user_write_access":["external_user_123"],"hierarchical_structures":"Business/Meetings/Project Planning","location":"Conference Room A","sourceUrl":"https://calendar.example.com/meeting/123","topics":["product","planning"]}

Any of:

Metadata used in graph and vector store for a memory item. Include role and category here.

contextArray of Context (objects) or Context (null)(Context)

Conversation history context for this memory. Use for providing message history when adding a memory. Format: [{role: 'user'|'assistant', content: '...'}]

Example: [{"content":"Let's discuss the Q4 project timeline with John","role":"user"},{"content":"I'll help you prepare for the timeline discussion. What are your key milestones?","role":"assistant"}]

Any of:

Conversation history context for this memory. Use for providing message history when adding a memory. Format: [{role: 'user'|'assistant', content: '...'}]

graph_generationGraphGeneration (object) or nullDeprecated

DEPRECATED: Use 'memory_policy' instead. Legacy graph generation configuration. If both memory_policy and graph_generation are provided, memory_policy takes precedence.

Any of:

Deprecated

DEPRECATED: Use 'memory_policy' instead. Legacy graph generation configuration. If both memory_policy and graph_generation are provided, memory_policy takes precedence.

organization_idOrganization Id (string) or Organization Id (null)(Organization Id)Deprecated

DEPRECATED - Internal only. Auto-populated from API key scope. Do not set manually. The organization is resolved automatically from the API key's associated organization.

Any of:

Deprecated

DEPRECATED - Internal only. Auto-populated from API key scope. Do not set manually. The organization is resolved automatically from the API key's associated organization.

string(Organization Id)

DEPRECATED - Internal only. Auto-populated from API key scope. Do not set manually. The organization is resolved automatically from the API key's associated organization.

user_idUser Id (string) or User Id (null)(User Id)Deprecated

DEPRECATED: Use 'external_user_id' instead. Internal Papr Parse user ID. Most developers should not use this field directly.

Any of:

Deprecated

DEPRECATED: Use 'external_user_id' instead. Internal Papr Parse user ID. Most developers should not use this field directly.

string(User Id)

DEPRECATED: Use 'external_user_id' instead. Internal Papr Parse user ID. Most developers should not use this field directly.

relationships_jsonArray of Relationships Json (objects) or Relationships Json (null)(Relationships Json)Deprecated

DEPRECATED: Use 'memory_policy' instead. Migration options: 1. Specific memory: relationships=[{source: '$this', target: 'mem_123', type: 'FOLLOWS'}] 2. Previous memory: link_to_previous_memory=True 3. Related memories: link_to_related_memories=3

Any of:

Deprecated

curl -i -X POST \
  'https://memoryserver-staging-223473570766.us-west1.run.app/v1/memory?enable_holographic=false&format=string&frequency_schema_id=string&skip_background_processing=false&webhook_secret=string&webhook_url=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "content": "Meeting with John Smith from Acme Corp about the Q4 project timeline",
    "context": [
      {
        "content": "Let'\''s discuss the Q4 project timeline with John",
        "role": "user"
      },
      {
        "content": "I'\''ll help you prepare for the timeline discussion. What are your key milestones?",
        "role": "assistant"
      }
    ],
    "graph_override": {
      "nodes": [
        {
          "id": "person_john_smith",
          "label": "Person",
          "properties": {
            "name": "John Smith",
            "role": "Project Manager",
            "description": "Senior PM at Acme Corp"
          }
        },
        {
          "id": "company_acme_corp",
          "label": "Company",
          "properties": {
            "name": "Acme Corp",
            "description": "Client company for Q4 project"
          }
        }
      ],
      "relationships": [
        {
          "properties": {
            "role": "Project Manager"
          },
          "relationship_type": "WORKS_FOR",
          "source_node_id": "person_john_smith",
          "target_node_id": "company_acme_corp"
        }
      ]
    },
    "metadata": {
      "conversationId": "conv-123",
      "createdAt": "2024-10-04T10:00:00Z",
      "emoji_tags": "📅,👥,📋",
      "emotion_tags": "focused, productive",
      "external_user_id": "external_user_123",
      "external_user_read_access": [
        "external_user_123",
        "external_user_789"
      ],
      "external_user_write_access": [
        "external_user_123"
      ],
      "hierarchical_structures": "Business/Meetings/Project Planning",
      "location": "Conference Room A",
      "sourceUrl": "https://calendar.example.com/meeting/123",
      "topics": [
        "product",
        "planning"
      ]
    },
    "type": "text"
  }'

Responses

Memory successfully added

Bodyapplication/json

codeinteger(Code)

HTTP status code

Default 200

statusstring(Status)

'success' or 'error'

Default "success"

dataArray of Data (objects) or Data (null)(Data)

List of memory items if successful

Any of:

List of memory items if successful

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 or context

Any of:

Additional error details or context

any(Details)

Additional error details or context

Response

application/json

{
  "code": 200,
  "status": "success",
  "data": [
    { … }
  ]
}

Get Memory Status

Request

Get processing status for a memory item.

Returns the current processing lifecycle stage:

queued — Accepted, waiting to be processed
quick_saved — Quick add complete (stored in DB + vector store), background processing pending
processing — Background processing in progress (graph indexing, Neo4j nodes, enrichment)
completed — All processing finished
failed — Processing failed

Use this endpoint to poll for completion after adding a memory. For real-time updates, connect to WebSocket at /ws/memory-status/{memory_id}.

Path

memory_idstring(Memory Id)required

curl -i -X GET \
  'https://memoryserver-staging-223473570766.us-west1.run.app/v1/memory/status/{memory_id}' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Memory processing status

Bodyapplication/json

property name*anyadditional property

Response

application/json

{}

Get Batch Memory Status

Request

Get processing status for a batch of memories.

Returns overall batch progress and per-memory status breakdown. The batch_id is returned in the POST /v1/memory/batch response.

For real-time updates, connect to WebSocket at /ws/memory-status.

Path

batch_idstring(Batch Id)required

curl -i -X GET \
  'https://memoryserver-staging-223473570766.us-west1.run.app/v1/memory/batch/status/{batch_id}' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Batch processing status

Bodyapplication/json

property name*anyadditional property

Response

application/json

{}

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

Papr Memory API (1.0.0)

Authentication

v1

Add Memory V1

Request

Responses

Was this helpful?

Get Memory Status

Request

Responses

Was this helpful?

Get Batch Memory Status

Request

Responses

Was this helpful?

Memory

Memory Status

User

Feedback

Schema Management

Messages

omo

Namespace

Frequency Schemas

Holographic Transform

Instance Configuration

AI Proxy

Sync

Telemetry

Document

GraphQL

Authentication

Papr Memory API (1.0.0)

Authentication

v1

Add Memory V1

RequestExpand all

Responses

Was this helpful?

Get Memory Status

Request

Responses

Was this helpful?

Get Batch Memory Status

Request

Responses

Was this helpful?

Memory

Memory Status

User

Feedback

Schema Management

Messages

omo

Namespace

Frequency Schemas

Holographic Transform

Instance Configuration

AI Proxy

Sync

Telemetry

Document

GraphQL

Authentication

Request