API Reference
/
v1

Papr Memory API (1.0.0)

API for managing memory, context, and retrieval for AI agents or apps 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
http://memory.papr.ai/

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
Bodyapplication/jsonrequired
graph_generationGraphGeneration (object) or null

Graph generation configuration. Defaults to auto mode with AI-selected schema.

Any of:

Graph generation configuration. Defaults to auto mode with AI-selected schema.

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"
metadataMemoryMetadata (object) or null

Metadata used in Neo4J and Pinecone 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 Neo4J and Pinecone for a memory item. Include role and category here.

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

Context can be conversation history or any relevant context for a memory item

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:

Context can be conversation history or any relevant context for a memory item

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

Array of relationships that we can use in Graph DB (neo4J)

Any of:

Array of relationships that we can use in Graph DB (neo4J)

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

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

Any of:

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

string(Organization Id)

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

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.

curl -i -X POST \
  'http://memory.papr.ai/v1/memory?skip_background_processing=false' \
  -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": [
    { … }
  ]
}

Update Memory V1

Request

Update an existing memory item by ID.

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

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

Path
memory_idstring(Memory Id)required
Bodyapplication/jsonrequired
contentContent (string) or Content (null)(Content)

The new content of the memory item

Example: "Updated meeting notes from the product planning session"
Any of:

The new content of the memory item

string(Content)

The new content of the memory item

typeMemoryType (string) or null

Content type of the memory item

Example: "text"
Any of:

Content type of the memory item

string(MemoryType)

Content type of the memory item

Enum"text""code_snippet""document"
metadataMemoryMetadata (object) or null

Updated metadata for Neo4J and Pinecone

Example: {"emoji tags":"📊,💡,📝,✨","emotion tags":"focused, productive, satisfied","hierarchical structures":"Business/Planning/Product/Updates","topics":"product, planning, updates"}
Any of:

Updated metadata for Neo4J and Pinecone

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

Updated context for the memory item

Example: [{"content":"Let's update the Q2 product roadmap","role":"user"},{"content":"I'll help you update the roadmap. What changes would you like to make?","role":"assistant"}]
Any of:

Updated context for the memory item

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

Updated relationships for Graph DB (neo4J)

Example: [{"metadata":{"relevance":"high"},"related_item_id":"previous_memory_item_id","related_item_type":"TextMemoryItem","relation_type":"updates"}]
Any of:

Updated relationships for Graph DB (neo4J)

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

Optional organization ID for multi-tenant memory scoping. When provided, update is scoped to memories within this organization.

Any of:

Optional organization ID for multi-tenant memory scoping. When provided, update is scoped to memories within this organization.

string(Organization Id)

Optional organization ID for multi-tenant memory scoping. When provided, update is scoped to memories within this organization.

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

Optional namespace ID for multi-tenant memory scoping. When provided, update is scoped to memories within this namespace.

Any of:

Optional namespace ID for multi-tenant memory scoping. When provided, update is scoped to memories within this namespace.

string(Namespace Id)

Optional namespace ID for multi-tenant memory scoping. When provided, update is scoped to memories within this namespace.

curl -i -X PUT \
  'http://memory.papr.ai/v1/memory/{memory_id}' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "content": "Updated meeting notes from the product planning session",
    "context": [
      {
        "content": "Let'\''s update the Q2 product roadmap",
        "role": "user"
      },
      {
        "content": "I'\''ll help you update the roadmap. What changes would you like to make?",
        "role": "assistant"
      }
    ],
    "metadata": {
      "emoji tags": "📊,💡,📝,✨",
      "emotion tags": "focused, productive, satisfied",
      "hierarchical structures": "Business/Planning/Product/Updates",
      "topics": "product, planning, updates"
    },
    "relationships_json": [
      {
        "metadata": {
          "relevance": "high"
        },
        "related_item_id": "previous_memory_item_id",
        "related_item_type": "TextMemoryItem",
        "relation_type": "updates"
      }
    ],
    "type": "text"
  }'

Responses

Memory successfully updated

Bodyapplication/json
codeinteger(Code)

HTTP status code

Default 200
statusstring(Status)

'success' or 'error'

Default "success"
memory_itemsArray of Memory Items (objects) or Memory Items (null)(Memory Items)

List of updated memory items if successful

Any of:

List of updated 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

messageMessage (string) or Message (null)(Message)

Status message

Any of:

Status message

string(Message)

Status message

status_objSystemUpdateStatus (object) or null

System update status (pinecone, neo4j, parse)

Any of:

System update status (pinecone, neo4j, parse)

Response
application/json
{
  "code": 200,
  "status": "success",
  "memory_items": [
    { … }
  ],
  "error": "string",
  "details": {},
  "message": "string",
  "status_obj": {
    "pinecone": false,
    "neo4j": false,
    "parse": false
  }
}

Delete Memory V1

Request

Delete a memory item by ID.

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:

  • X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
Path
memory_idstring(Memory Id)required
Query
skip_parseboolean(Skip Parse)

Skip Parse Server deletion

Default false
curl -i -X DELETE \
  'http://memory.papr.ai/v1/memory/{memory_id}?skip_parse=false' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Memory successfully deleted

Bodyapplication/json
codeinteger(Code)

HTTP status code

Default 200
statusstring(Status)

'success' or 'error'

Default "success"
messageMessage (string) or Message (null)(Message)
Any of:
string(Message)
errorError (string) or Error (null)(Error)
Any of:
string(Error)
memoryIdstring(Memoryid)
Default ""
objectIdstring(Objectid)
Default ""
deletion_statusDeletionStatus (object) or null
Any of:
detailsDetails (any) or Details (null)(Details)
Any of:
any(Details)
Response
application/json
{
  "code": 200,
  "status": "success",
  "message": "string",
  "error": "string",
  "memoryId": "",
  "objectId": "",
  "deletion_status": {
    "pinecone": false,
    "neo4j": false,
    "parse": false,
    "qdrant": false
  },
  "details": {}
}

Memory

Operations

User

Operations

Feedback

Operations

Document

Operations

Schema Management

Operations

GraphQL

Operations