v37

latestOpenAPI 3.1.0raw.githubusercontent.com2026-06-1170194628.0 KB

Memory

Add Memory V1

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

post/v1/memory

Query parameters

skip_background_processingboolean

If True, skips adding background tasks for processing

formatstring nullable

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

webhook_urlstring nullable

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

webhook_secretstring nullable

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

Request body

contentstring required

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

type'text' | 'code_snippet' | 'document'

Valid memory types

organization_idstring nullable

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.

namespace_idstring nullable

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

external_user_idstring nullable

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.

user_idstring nullable

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

Example request

{
  "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"
    }
  ],
  "external_user_id": "user_alice_123",
  "metadata": {
    "conversationId": "conv-123",
    "customMetadata": {
      "meeting_type": "planning",
      "project_id": "q4-roadmap"
    },
    "emoji_tags": [
      "📅",
      "👥",
      "📋"
    ],
    "emotion_tags": [
      "focused",
      "productive"
    ],
    "hierarchical_structures": "Business/Meetings/Project Planning",
    "location": "Conference Room A",
    "sourceUrl": "https://calendar.example.com/meeting/123",
    "topics": [
      "product",
      "planning",
      "meetings"
    ]
  },
  "policy": {
    "acl": {
      "read": [
        "external_user:user_alice_123"
      ],
      "write": [
        "external_user:user_alice_123"
      ]
    },
    "consent": "implicit",
    "graph": {
      "link_to": [
        "Person:name~John Smith",
        "Company:name~Acme Corp",
        "Meeting:title~Q4 project timeline"
      ],
      "mode": "auto"
    },
    "risk": "none",
    "transform_embedding": {
      "domain_id": "general",
      "mode": "auto"
    }
  },
  "type": "text"
}

Response

Memory successfully added

codeinteger

HTTP status code

statusstring

'success' or 'error'

errorstring nullable

Error message if failed

{"stackTrail":"components:schemas:AddMemoryResponse:properties:details:anyOf","oasType":"schema","type":"unknown","title":"Details","description":"Additional error details or context","nullable":true}