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

Servers

Production server

http://memory.papr.ai/

v1

Operations

Memory

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": {}
}

Get Memory V1

Request

Retrieve 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

curl -i -X GET \
  'http://memory.papr.ai/v1/memory/{memory_id}' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Memory successfully retrieved

Bodyapplication/json

codeinteger(Code)

HTTP status code

Default 200

Example: 200

statusstring(Status)

'success' or 'error'

Default "success"

Example: "success"

dataSearchResult (object) or null

Search results if successful

Example: {"memories":[],"nodes":[]}

Any of:

Search results 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

search_idSearch Id (string) or Search Id (null)(Search Id)

Unique identifier for this search query, maps to QueryLog objectId in Parse Server

Example: "abc123def456"

Any of:

Unique identifier for this search query, maps to QueryLog objectId in Parse Server

string(Search Id)

Unique identifier for this search query, maps to QueryLog objectId in Parse Server

Response

application/json

{
  "code": 200,
  "data": {
    "memories": [],
    "nodes": []
  },
  "search_id": "abc123def456",
  "status": "success"
}

Add Memory Batch V1

Request

Add multiple memory items in a batch 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')

The API validates individual memory 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.

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

Internal user ID for all memories in the batch. If not provided, developer's user ID will be used.

Example: "internal_user_id_12345"

Any of:

Internal user ID for all memories in the batch. If not provided, developer's user ID will be used.

string(User Id)

Internal user ID for all memories in the batch. If not provided, developer's user ID will be used.

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

External user ID for all memories in the batch. If provided and user_id is not, will be resolved to internal user ID.

Example: "external_user_abcde"

Any of:

External user ID for all memories in the batch. If provided and user_id is not, will be resolved to internal user ID.

string(External User Id)

External user ID for all memories in the batch. If provided and user_id is not, will be resolved to internal user ID.

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

Optional organization ID for multi-tenant batch memory scoping. When provided, all memories in the batch are associated with this organization.

Any of:

Optional organization ID for multi-tenant batch memory scoping. When provided, all memories in the batch are associated with this organization.

string(Organization Id)

Optional organization ID for multi-tenant batch memory scoping. When provided, all memories in the batch are associated with this organization.

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

Optional namespace ID for multi-tenant batch memory scoping. When provided, all memories in the batch are associated with this namespace.

Any of:

Optional namespace ID for multi-tenant batch memory scoping. When provided, all memories in the batch are associated with this namespace.

string(Namespace Id)

Optional namespace ID for multi-tenant batch memory scoping. When provided, all memories in the batch are associated with this namespace.

memoriesArray of objects(Memories)[ 1 .. 50 ] itemsrequired

List of memory items to add in batch

Example: [{"content":"Meeting notes from the product planning session","metadata":{"createdAt":"2024-03-21T10:00:00Z","emoji tags":"📊,💡,📝","emotion tags":"focused, productive","hierarchical structures":"Business/Planning/Product","topics":"product, planning"},"type":"text"},{"content":"Follow-up tasks from the planning meeting","metadata":{"createdAt":"2024-03-21T11:00:00Z","emoji tags":"✅,📋","emotion tags":"organized","hierarchical structures":"Business/Tasks/Planning","topics":"tasks, planning"},"type":"text"}]

memories[].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.

memories[].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"

memories[].typestring(MemoryType)

Memory item type; defaults to 'text' if omitted

Default "text"

Enum"text""code_snippet""document"

Example: "text"

memories[].metadataMemoryMetadata (object) or null

Metadata used in Neo4J and Pinecone for a memory item. Include role and category here.

Any of:

Metadata used in Neo4J and Pinecone for a memory item. Include role and category here.

memories[].contextArray of Context (objects) or Context (null)(Context)

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

Any of:

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

memories[].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)

memories[].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.

memories[].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.

batch_sizeBatch Size (integer) or Batch Size (null)(Batch Size)

Number of items to process in parallel

Default 10

Example: 10

Any of:

Number of items to process in parallel

[ 1 .. 50 ]

integer(Batch Size)[ 1 .. 50 ]

Number of items to process in parallel

Default 10

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

Optional webhook URL to notify when batch processing is complete. The webhook will receive a POST request with batch completion details.

Any of:

Optional webhook URL to notify when batch processing is complete. The webhook will receive a POST request with batch completion details.

string(Webhook Url)

Optional webhook URL to notify when batch processing is complete. The webhook will receive a POST request with batch completion details.

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

Optional secret key for webhook authentication. If provided, will be included in the webhook request headers as 'X-Webhook-Secret'.

Any of:

Optional secret key for webhook authentication. If provided, will be included in the webhook request headers as 'X-Webhook-Secret'.

string(Webhook Secret)

Optional secret key for webhook authentication. If provided, will be included in the webhook request headers as 'X-Webhook-Secret'.

property name*anyadditional property

curl -i -X POST \
  'http://memory.papr.ai/v1/memory/batch?skip_background_processing=false' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "batch_size": 10,
    "external_user_id": "external_user_abcde",
    "memories": [
      {
        "content": "Meeting notes from the product planning session",
        "metadata": {
          "createdAt": "2024-03-21T10:00:00Z",
          "emoji tags": "📊,💡,📝",
          "emotion tags": "focused, productive",
          "hierarchical structures": "Business/Planning/Product",
          "topics": "product, planning"
        },
        "type": "text"
      },
      {
        "content": "Follow-up tasks from the planning meeting",
        "metadata": {
          "createdAt": "2024-03-21T11:00:00Z",
          "emoji tags": "✅,📋",
          "emotion tags": "organized",
          "hierarchical structures": "Business/Tasks/Planning",
          "topics": "tasks, planning"
        },
        "type": "text"
      }
    ],
    "user_id": "internal_user_id_12345"
  }'

Responses

Memories successfully added

Bodyapplication/json

codeinteger(Code)

HTTP status code for the batch operation

Default 200

statusstring(Status)

'success', 'partial', or 'error'

Default "success"

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

Human-readable status message

Any of:

Human-readable status message

string(Message)

Human-readable status message

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

Batch-level error message, if any

Any of:

Batch-level error message, if any

string(Error)

Batch-level error message, if any

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

successfulArray of objects(Successful)

List of successful add responses

errorsArray of objects(Errors)

List of errors for failed items

total_processedinteger(Total Processed)

Default 0

total_successfulinteger(Total Successful)

Default 0

total_failedinteger(Total Failed)

Default 0

total_content_sizeinteger(Total Content Size)

Default 0

total_storage_sizeinteger(Total Storage Size)

Default 0

Response

application/json

{
  "code": 200,
  "status": "success",
  "message": "string",
  "error": "string",
  "details": {},
  "successful": [
    { … }
  ],
  "errors": [
    { … }
  ],
  "total_processed": 0,
  "total_successful": 0,
  "total_failed": 0,
  "total_content_size": 0,
  "total_storage_size": 0
}

Delete All Memories V1

Request

Delete all memory items for a user.

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

User Resolution:

If only API key is provided: deletes memories for the developer
If user_id or external_user_id is provided: resolves and deletes memories for that user
Uses the same user resolution logic as other endpoints

Required Headers:

X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')

WARNING: This operation cannot be undone. All memories for the resolved user will be permanently deleted.

Query

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

Optional user ID to delete memories for (if not provided, uses authenticated user)

Any of:

Optional user ID to delete memories for (if not provided, uses authenticated user)

string(User Id)

Optional user ID to delete memories for (if not provided, uses authenticated user)

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

Optional external user ID to resolve and delete memories for

Any of:

Optional external user ID to resolve and delete memories for

string(External User Id)

Optional external user ID to resolve and delete memories for

skip_parseboolean(Skip Parse)

Skip Parse Server deletion

Default false

curl -i -X DELETE \
  'http://memory.papr.ai/v1/memory/all?external_user_id=string&skip_parse=false&user_id=string' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

All memories successfully deleted

Bodyapplication/json

codeinteger(Code)

HTTP status code for the batch operation

Default 200

statusstring(Status)

'success', 'partial', or 'error'

Default "success"

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

Human-readable status message

Any of:

Human-readable status message

string(Message)

Human-readable status message

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

Batch-level error message, if any

Any of:

Batch-level error message, if any

string(Error)

Batch-level error message, if any

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

successfulArray of objects(Successful)

List of successful add responses

errorsArray of objects(Errors)

List of errors for failed items

total_processedinteger(Total Processed)

Default 0

total_successfulinteger(Total Successful)

Default 0

total_failedinteger(Total Failed)

Default 0

total_content_sizeinteger(Total Content Size)

Default 0

total_storage_sizeinteger(Total Storage Size)

Default 0

Response

application/json

{
  "code": 200,
  "status": "success",
  "message": "string",
  "error": "string",
  "details": {},
  "successful": [
    { … }
  ],
  "errors": [
    { … }
  ],
  "total_processed": 0,
  "total_successful": 0,
  "total_failed": 0,
  "total_content_size": 0,
  "total_storage_size": 0
}

Search V1

Request

Search through memories with authentication required.

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

Custom Schema Support: This endpoint supports both system-defined and custom user-defined node types:

System nodes: Memory, Person, Company, Project, Task, Insight, Meeting, Opportunity, Code
Custom nodes: Defined by developers via UserGraphSchema (e.g., Developer, Product, Customer, Function)

When custom schema nodes are returned:

Each custom node includes a schema_id field referencing the UserGraphSchema
The response includes a schemas_used array listing all schema IDs used
Use GET /v1/schemas/{schema_id} to retrieve full schema definitions including:
- Node type definitions and properties
- Relationship type definitions and constraints
- Validation rules and requirements

Recommended Headers:

Accept-Encoding: gzip

The API supports response compression for improved performance. Responses larger than 1KB will be automatically compressed when this header is present.

HIGHLY RECOMMENDED SETTINGS FOR BEST RESULTS:

Set enable_agentic_graph: true for intelligent, context-aware search that can understand ambiguous references
Use max_memories: 15-20 for comprehensive memory coverage
Use max_nodes: 10-15 for comprehensive graph entity relationships

Agentic Graph Benefits: When enabled, the system can understand vague references by first identifying specific entities from your memory graph, then performing targeted searches. For example:

"customer feedback" → identifies your customers first, then finds their specific feedback
"project issues" → identifies your projects first, then finds related issues
"team meeting notes" → identifies your team members first, then finds meeting notes
"code functions" → identifies your functions first, then finds related code

Role-Based Memory Filtering: Filter memories by role and category using metadata fields:

metadata.role: Filter by "user" or "assistant"
metadata.category: Filter by category (user: preference, task, goal, facts, context | assistant: skills, learning)

User Resolution Precedence:

If both user_id and external_user_id are provided, user_id takes precedence.
If only external_user_id is provided, it will be resolved to the internal user.
If neither is provided, the authenticated user is used.

Query

max_memoriesinteger(Max Memories)[ 10 .. 50 ]

HIGHLY RECOMMENDED: Maximum number of memories to return. Use at least 15-20 for comprehensive results. Lower values (5-10) may miss relevant information. Default is 20 for optimal coverage.

Default 20

max_nodesinteger(Max Nodes)[ 10 .. 50 ]

HIGHLY RECOMMENDED: Maximum number of neo nodes to return. Use at least 10-15 for comprehensive graph results. Lower values may miss important entity relationships. Default is 15 for optimal coverage.

Default 15

Headers

Accept-Encodingstring

Recommended to use 'gzip' for response compression

Default gzip

Bodyapplication/jsonrequired

querystring(Query)required

Detailed search query describing what you're looking for. For best results, write 2-3 sentences that include specific details, context, and time frame. Examples: 'Find recurring customer complaints about API performance from the last month. Focus on issues where customers specifically mentioned timeout errors or slow response times in their conversations.' 'What are the main issues and blockers in my current projects? Focus on technical challenges and timeline impacts.' 'Find insights about team collaboration and communication patterns from recent meetings and discussions.'

Example: "Find recurring customer complaints about API performance from the last month. Focus on issues that multiple customers have mentioned and any specific feature requests or workflow improvements they've suggested."

rank_resultsboolean(Rank Results)

Whether to enable additional ranking of search results. Default is false because results are already ranked when using an LLM for search (recommended approach). Only enable this if you're not using an LLM in your search pipeline and need additional result ranking.

Default false

Example: true

enable_agentic_graphboolean(Enable Agentic Graph)

HIGHLY RECOMMENDED: Enable agentic graph search for intelligent, context-aware results. When enabled, the system can understand ambiguous references by first identifying specific entities from your memory graph, then performing targeted searches. Examples: 'customer feedback' → identifies your customers first, then finds their specific feedback; 'project issues' → identifies your projects first, then finds related issues; 'team meeting notes' → identifies team members first, then finds meeting notes. This provides much more relevant and comprehensive results. Set to false only if you need faster, simpler keyword-based search.

Default false

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

Optional internal user ID to filter search results by a specific user. If not provided, results are not filtered by user. If both user_id and external_user_id are provided, user_id takes precedence.

Any of:

Optional internal user ID to filter search results by a specific user. If not provided, results are not filtered by user. If both user_id and external_user_id are provided, user_id takes precedence.

string(User Id)

Optional internal user ID to filter search results by a specific user. If not provided, results are not filtered by user. If both user_id and external_user_id are provided, user_id takes precedence.

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

Optional external user ID to filter search results by a specific external user. If both user_id and external_user_id are provided, user_id takes precedence.

Example: "external_user_123"

Any of:

Optional external user ID to filter search results by a specific external user. If both user_id and external_user_id are provided, user_id takes precedence.

string(External User Id)

Optional external user ID to filter search results by a specific external user. If both user_id and external_user_id are provided, user_id takes precedence.

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

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

Any of:

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

string(Organization Id)

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

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

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

Any of:

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

string(Namespace Id)

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

schema_idSchema Id (string) or Schema Id (null)(Schema Id)

Optional user-defined schema ID to use for this search. If provided, this schema (plus system schema) will be used for query generation. If not provided, system will automatically select relevant schema based on query content.

Any of:

string(Schema Id)

simple_schema_modeboolean(Simple Schema Mode)

If true, uses simple schema mode: system schema + ONE most relevant user schema. This ensures better consistency between add/search operations and reduces query complexity. Recommended for production use.

Default false

metadataMemoryMetadata (object) or null

Optional metadata filter. Any field in MemoryMetadata (including custom fields) can be used for filtering.

Any of:

Optional metadata filter. Any field in MemoryMetadata (including custom fields) can be used for filtering.

search_overrideSearchOverrideSpecification (object) or null

OPTIONAL: Override automatic search query generation with your own exact graph pattern and filters. ⚡ AUTOMATIC BY DEFAULT: If not provided, the system automatically generates optimized Cypher queries using AI - no action required! 🎯 USE WHEN: You want precise control over search patterns, have specific graph traversals in mind, or want to bypass AI query generation for performance. 📋 VALIDATION: All patterns and filters must comply with your schema definitions.

Any of:

curl -i -X POST \
  'http://memory.papr.ai/v1/memory/search?max_memories=20&max_nodes=15' \
  -H 'Accept-Encoding: gzip' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "enable_agentic_graph": false,
    "external_user_id": "external_user_123",
    "query": "Find recurring customer complaints about API performance from the last month. Focus on issues that multiple customers have mentioned and any specific feature requests or workflow improvements they'\''ve suggested.",
    "rank_results": true
  }'

Responses

Successfully retrieved memories

Bodyapplication/json

codeinteger(Code)

HTTP status code

Default 200

Example: 200

statusstring(Status)

'success' or 'error'

Default "success"

Example: "success"

dataSearchResult (object) or null

Search results if successful

Example: {"memories":[],"nodes":[]}

Any of:

Search results 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

search_idSearch Id (string) or Search Id (null)(Search Id)

Unique identifier for this search query, maps to QueryLog objectId in Parse Server

Example: "abc123def456"

Any of:

Unique identifier for this search query, maps to QueryLog objectId in Parse Server

string(Search Id)

Unique identifier for this search query, maps to QueryLog objectId in Parse Server

Response

application/json

Standard response when only system-defined node types are found

{
  "code": 200,
  "status": "success",
  "data": {
    "memories": [ … ],
    "nodes": [ … ]
  },
  "search_id": "search-789"
}

User

Operations

Feedback

Operations

Document

Operations

Schema Management

Operations

GraphQL

Operations

Papr Memory API (1.0.0)

Authentication

v1

Memory

Add Memory V1

Request

Responses

Was this helpful?

Update Memory V1

Request

Responses

Was this helpful?

Delete Memory V1

Request

Responses

Was this helpful?

Get Memory V1

Request

Responses

Was this helpful?

Add Memory Batch V1

Request

Responses

Was this helpful?

Delete All Memories V1

Request

Responses

Was this helpful?

Search V1

Request

Responses

Was this helpful?

User

Feedback

Document

Schema Management

GraphQL

Papr Memory API (1.0.0)

Authentication

v1

Memory

Add Memory V1

RequestExpand all

Responses

Was this helpful?

Update Memory V1

RequestExpand all

Responses

Was this helpful?

Delete Memory V1

Request

Responses

Was this helpful?

Get Memory V1

Request

Responses

Was this helpful?

Add Memory Batch V1

RequestExpand all

Responses

Was this helpful?

Delete All Memories V1

RequestExpand all

Responses

Was this helpful?

Search V1

RequestExpand all

Responses

Was this helpful?

User

Feedback

Document

Schema Management

GraphQL

Request

Request

Request

Request

Request