API Reference
/
v1
/
Search V1

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
http://memory.papr.ai/

v1

Operations

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

Response Format Options: Choose between standard JSON or TOON (Token-Oriented Object Notation) format:

  • JSON (default): Standard JSON response format
  • TOON: Optimized format achieving 30-60% token reduction for LLM contexts
    • Use response_format=toon query parameter
    • Returns text/plain with TOON-formatted content
    • Ideal for LLM integrations to reduce API costs and latency
    • Maintains semantic clarity while minimizing token usage
    • Example: /v1/memory/search?response_format=toon

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
  • Use response_format: toon when integrating with LLMs to reduce token costs by 30-60%

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
response_formatstring(ResponseFormat)

Response format: 'json' (default) or 'toon' (Token-Oriented Object Notation for 30-60% token reduction in LLM contexts)

Default "json"
Enum"json""toon"
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."
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
external_user_idExternal User Id (string) or External User Id (null)(External User Id)

Your application's user identifier to filter search results. This is the primary way to identify users. Use this for your app's user IDs (e.g., 'user_alice_123', UUID, email).

Example: "external_user_123"
Any of:

Your application's user identifier to filter search results. This is the primary way to identify users. Use this for your app's user IDs (e.g., 'user_alice_123', UUID, email).

string(External User Id)

Your application's user identifier to filter search results. This is the primary way to identify users. Use this for your app's user IDs (e.g., 'user_alice_123', UUID, email).

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:

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.

string(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.

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:

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.

reranking_configRerankingConfig (object) or null

Optional reranking configuration. If provided, enables reranking with specified provider (OpenAI or Cohere) and model. If not provided but rank_results=True, uses default OpenAI reranking.

Any of:

Optional reranking configuration. If provided, enables reranking with specified provider (OpenAI or Cohere) and model. If not provided but rank_results=True, uses default OpenAI reranking.

holographic_configHolographicConfig (object) or null

Optional holographic neural embedding configuration. Enables H-COND (Holographic CONDitional) phase alignment scoring for improved semantic relevance. Uses 13 brain-inspired frequency bands.

Any of:

Optional holographic neural embedding configuration. Enables H-COND (Holographic CONDitional) phase alignment scoring for improved semantic relevance. Uses 13 brain-inspired frequency bands.

omo_filterOMOFilter (object) or null

Optional OMO (Open Memory Object) safety filter. Filter search results by consent level and/or risk level. Use this to exclude memories without proper consent or flagged content from search results.

Any of:

Optional OMO (Open Memory Object) safety filter. Filter search results by consent level and/or risk level. Use this to exclude memories without proper consent or flagged content from search results.

rank_resultsboolean(Rank Results)Deprecated

DEPRECATED: Use 'reranking_config' instead. 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. Migration: Replace 'rank_results: true' with 'reranking_config: {reranking_enabled: true, reranking_provider: "cohere", reranking_model: "rerank-v3.5"}'

Default false
Example: true
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.

curl -i -X POST \
  'http://memory.papr.ai/v1/memory/search?max_memories=20&max_nodes=15&response_format=json' \
  -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"
}

Create User

Request

Create a new user or link existing user to developer

Headers
X-API-Keystring(X-Api-Key)required
Bodyapplication/jsonrequired
emailEmail (string) or Email (null)(Email)
Example: "user@example.com"
Any of:
string(email)(Email)
external_idstring(External Id)required
Example: "user123"
metadataMetadata (object) or Metadata (null)(Metadata)
Example: {"name":"John Doe","preferences":{"theme":"dark"}}
Any of:
typestring(UserType)
Default "developerUser"
Enum"developerUser""user""agent"
Example: "developerUser"
curl -i -X POST \
  http://memory.papr.ai/v1/user \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -d '{
    "email": "user@example.com",
    "external_id": "user123",
    "metadata": {
      "name": "John Doe",
      "preferences": {
        "theme": "dark"
      }
    },
    "type": "developerUser"
  }'

Responses

Successful Response

Bodyapplication/json
codeinteger(Code)required

HTTP status code

Example: 200
statusstring(Status)required

'success' or 'error'

Example: "success"
user_idUser Id (string) or User Id (null)(User Id)
Example: "abc123"
Any of:
string(User Id)
emailEmail (string) or Email (null)(Email)
Example: "user@example.com"
Any of:
string(Email)
external_idExternal Id (string) or External Id (null)(External Id)
Example: "user123"
Any of:
string(External Id)
metadataMetadata (object) or Metadata (null)(Metadata)
Example: {"name":"John Doe","preferences":{"theme":"dark"}}
Any of:
created_atCreated At (string) or Created At (null)(Created At)
Example: "2024-03-20T10:00:00.000Z"
Any of:
string(Created At)
updated_atUpdated At (string) or Updated At (null)(Updated At)
Example: "2024-03-20T10:00:00.000Z"
Any of:
string(Updated At)
errorError (string) or Error (null)(Error)
Any of:
string(Error)
detailsDetails (any) or Details (null)(Details)
Any of:
any(Details)
Response
application/json
{
  "code": 200,
  "created_at": "2024-03-20T10:00:00.000Z",
  "email": "user@example.com",
  "external_id": "user123",
  "metadata": {
    "name": "John Doe",
    "preferences": { … }
  },
  "status": "success",
  "updated_at": "2024-03-20T10:00:00.000Z",
  "user_id": "abc123"
}

Memory

Operations

User

Operations

Feedback

Operations

Schema Management

Operations

Messages

Operations

omo

Operations

Sync

Operations

Telemetry

Operations

Document

Operations

GraphQL

Operations

Authentication

Operations