API Reference
/
Sync

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

Memory

Operations

User

Operations

Feedback

Operations

Sync

Operations

Get Sync Tiers

Request

Return initial Tier 0 (goals/OKRs/use-cases --> tier 0 memories) and Tier 1 (hot memories) for the requesting user/workspace.

This is a minimal initial implementation to enable SDK integration. It uses simple heuristics and will be enhanced with analytics-driven selection.

Bodyapplication/jsonrequired
max_tier0integer(Max Tier0)[ 0 .. 2000 ]

Max Tier 0 items (goals/OKRs/use-cases)

Default 300
Example: 300
max_tier1integer(Max Tier1)[ 0 .. 5000 ]

Max Tier 1 items (hot memories)

Default 1000
Example: 1000
workspace_idWorkspace Id (string) or Workspace Id (null)(Workspace Id)

Optional workspace id to scope tiers

Example: "workspace_123"
Any of:

Optional workspace id to scope tiers

string(Workspace Id)

Optional workspace id to scope tiers

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

Optional internal user ID to filter tiers 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.

Example: "internal_user_123"
Any of:

Optional internal user ID to filter tiers 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 tiers 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 tiers by a specific external user. If both user_id and external_user_id are provided, user_id takes precedence.

Example: "external_user_abc"
Any of:

Optional external user ID to filter tiers 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 tiers 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 scoping. When provided, tiers are scoped to memories within this organization.

Any of:

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

string(Organization Id)

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

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

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

Any of:

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

string(Namespace Id)

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

include_embeddingsboolean(Include Embeddings)

Include embeddings in the response. Format controlled by embedding_format parameter.

Default false
embedding_formatstring(EmbeddingFormat)

Embedding format: 'int8' (quantized, 4x smaller, default for efficiency), 'float32' (full precision, recommended for CoreML/ANE fp16 models). Only applies to Tier1; Tier0 always uses float32 when embeddings are included.

Default "int8"
Enum"int8""float32"
embed_modelstring(Embed Model)

Embedding model hint: 'sbert' or 'bigbird' or 'Qwen4B'

Default "Qwen4B"
Example: "sbert"
embed_limitinteger(Embed Limit)[ 0 .. 1000 ]

Max items to embed per tier to control latency

Default 200
Example: 200
curl -i -X POST \
  http://memory.papr.ai/v1/sync/tiers \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "embed_limit": 200,
    "embed_model": "sbert",
    "external_user_id": "external_user_abc",
    "include_embeddings": false,
    "max_tier0": 300,
    "max_tier1": 1000,
    "user_id": "internal_user_123",
    "workspace_id": "workspace_123"
  }'

Responses

Tier assignments returned

Bodyapplication/json
codeinteger(Code)

HTTP status code

Default 200
Example: 200
statusstring(Status)

'success' or 'error'

Default "success"
Example: "success"
tier0Array of objects(Tier0)

Tier 0 items (goals/OKRs/use-cases)

Example: [{"content":"Improve API performance","id":"goal_123","metadata":{"class":"goal","sourceType":"papr"},"topics":["performance","api"],"type":"goal"}]
tier1Array of objects(Tier1)

Tier 1 items (hot memories)

Example: [{"content":"Customer complained about slow API response times","id":"memory_456","metadata":{"sourceType":"papr"},"topics":["customer","api","performance"],"type":"text"}]
transitionsArray of objects(Transitions)

Transition items between tiers

Example: []
next_cursorNext Cursor (string) or Next Cursor (null)(Next Cursor)

Cursor for pagination

Any of:

Cursor for pagination

string(Next Cursor)

Cursor for pagination

has_moreboolean(Has More)

Whether there are more items available

Default false
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,
  "has_more": false,
  "status": "success",
  "tier0": [
    { … }
  ],
  "tier1": [
    { … }
  ],
  "transitions": []
}

Get Sync Delta

Request

Return upserts/deletes since the provided cursor for a user/workspace. Cursor is an opaque watermark over updatedAt and objectId.

Query
cursorCursor (string) or Cursor (null)(Cursor)

Opaque cursor from previous sync

Any of:

Opaque cursor from previous sync

string(Cursor)

Opaque cursor from previous sync

limitinteger(Limit)[ 1 .. 1000 ]
Default 200
workspace_idWorkspace Id (string) or Workspace Id (null)(Workspace Id)
Any of:
string(Workspace Id)
include_embeddingsboolean(Include Embeddings)
Default false
curl -i -X GET \
  'http://memory.papr.ai/v1/sync/delta?cursor=string&include_embeddings=false&limit=200&workspace_id=string' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Delta since cursor returned

Bodyapplication/json
property name*anyadditional property
Response
application/json
{}

Schema Management

Operations

Messages

Operations

Document

Operations

GraphQL

Operations