---
title: "Add Memory Batch V1"
method: POST
path: "/v1/memory/batch"
tags: ["v1", "Memory"]
---

# Add Memory Batch V1

`POST /v1/memory/batch`

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 parameters

- `skip_background_processing` boolean — If True, skips adding background tasks for processing

## Request body

- BatchMemoryRequest — Request model for batch adding memories
  - `graph_generation` GraphGeneration — Graph generation configuration
    - `mode` 'auto' | 'manual' — Graph generation modes
    - `auto` AutoGraphGeneration — AI-powered graph generation with optional guidance
      - `schema_id` string, nullable — Force AI to use this specific schema instead of auto-selecting
      - `simple_schema_mode` boolean — Limit AI to system + one user schema for consistency
      - `property_overrides` PropertyOverrideRule[], nullable — Override specific property values in AI-generated nodes with match conditions
        - `nodeLabel` string, required — Node type to apply overrides to (e.g., 'User', 'SecurityBehavior')
        - `match` object, nullable — Optional conditions that must be met for override to apply. If not provided, applies to all nodes of this type
        - `set` object, required — Properties to set/override on matching nodes
    - `manual` ManualGraphGeneration — Complete manual control over graph structure
      - `nodes` GraphOverrideNode[], required — Exact nodes to create
        - `id` string, required — **REQUIRED**: Unique identifier for this node. Must be unique within this request. Relationships reference this via source_node_id/target_node_id. Example: 'person_john_123', 'finding_cve_2024_1234'
        - `label` string, required — **REQUIRED**: Node type from your UserGraphSchema. View available types at GET /v1/schemas. System types: Memory, Person, Company, Project, Task, Insight, Meeting, Opportunity, Code
        - `properties` object, required — **REQUIRED**: Node properties matching your UserGraphSchema definition. Must include: (1) All required properties from your schema, (2) unique_identifiers if defined (e.g., 'email' for Person) to enable MERGE deduplication. View schema requirements at GET /v1/schemas
      - `relationships` GraphOverrideRelationship[] — Exact relationships to create
        - `source_node_id` string, required — **REQUIRED**: Must exactly match the 'id' field of a node defined in the 'nodes' array of this request
        - `target_node_id` string, required — **REQUIRED**: Must exactly match the 'id' field of a node defined in the 'nodes' array of this request
        - `relationship_type` string, required — **REQUIRED**: Relationship type from your UserGraphSchema. View available types at GET /v1/schemas. System types: WORKS_FOR, WORKS_ON, HAS_PARTICIPANT, DISCUSSES, MENTIONS, RELATES_TO, CREATED_BY
        - `properties` object, nullable — Optional relationship properties (e.g., {'since': '2024-01-01', 'role': 'manager'})
  - `user_id` string, nullable — Internal user ID for all memories in the batch. If not provided, developer's user ID will be used.
  - `external_user_id` string, nullable — External user ID for all memories in the batch. If provided and user_id is not, will be resolved to internal user ID.
  - `organization_id` string, nullable — Optional organization ID for multi-tenant batch memory scoping. When provided, all memories in the batch are associated with this organization.
  - `namespace_id` string, nullable — Optional namespace ID for multi-tenant batch memory scoping. When provided, all memories in the batch are associated with this namespace.
  - `memories` AddMemoryRequest[], required — List of memory items to add in batch
    - `graph_generation` GraphGeneration — Graph generation configuration
      - `mode` 'auto' | 'manual' — Graph generation modes
      - `auto` AutoGraphGeneration — AI-powered graph generation with optional guidance
        - `schema_id` string, nullable — Force AI to use this specific schema instead of auto-selecting
        - `simple_schema_mode` boolean — Limit AI to system + one user schema for consistency
        - `property_overrides` PropertyOverrideRule[], nullable — Override specific property values in AI-generated nodes with match conditions
          - `nodeLabel` string, required — Node type to apply overrides to (e.g., 'User', 'SecurityBehavior')
          - `match` object, nullable — Optional conditions that must be met for override to apply. If not provided, applies to all nodes of this type
          - `set` object, required — Properties to set/override on matching nodes
      - `manual` ManualGraphGeneration — Complete manual control over graph structure
        - `nodes` GraphOverrideNode[], required — Exact nodes to create
          - `id` string, required — **REQUIRED**: Unique identifier for this node. Must be unique within this request. Relationships reference this via source_node_id/target_node_id. Example: 'person_john_123', 'finding_cve_2024_1234'
          - `label` string, required — **REQUIRED**: Node type from your UserGraphSchema. View available types at GET /v1/schemas. System types: Memory, Person, Company, Project, Task, Insight, Meeting, Opportunity, Code
          - `properties` object, required — **REQUIRED**: Node properties matching your UserGraphSchema definition. Must include: (1) All required properties from your schema, (2) unique_identifiers if defined (e.g., 'email' for Person) to enable MERGE deduplication. View schema requirements at GET /v1/schemas
        - `relationships` GraphOverrideRelationship[] — Exact relationships to create
          - `source_node_id` string, required — **REQUIRED**: Must exactly match the 'id' field of a node defined in the 'nodes' array of this request
          - `target_node_id` string, required — **REQUIRED**: Must exactly match the 'id' field of a node defined in the 'nodes' array of this request
          - `relationship_type` string, required — **REQUIRED**: Relationship type from your UserGraphSchema. View available types at GET /v1/schemas. System types: WORKS_FOR, WORKS_ON, HAS_PARTICIPANT, DISCUSSES, MENTIONS, RELATES_TO, CREATED_BY
          - `properties` object, nullable — Optional relationship properties (e.g., {'since': '2024-01-01', 'role': 'manager'})
    - `content` string, required — The content of the memory item you want to add to memory
    - `type` 'text' | 'code_snippet' | 'document' — Valid memory types
    - `metadata` MemoryMetadata — Metadata for memory request
      - `hierarchical_structures` string, nullable — Hierarchical structures to enable navigation from broad topics to specific ones
      - `createdAt` string, nullable — ISO datetime when the memory was created
      - `location` string, nullable
      - `topics` string[], nullable
      - `emoji tags` string[], nullable
      - `emotion tags` string[], nullable
      - `conversationId` string, nullable
      - `sourceUrl` string, nullable
      - `role` 'user' | 'assistant' — Role of the message sender
      - `category` union — Memory category based on role. For users: preference, task, goal, fact, context. For assistants: skills, learning, task, goal, fact, context.
        - 'preference' | 'task' | 'goal' | 'fact' | 'context' — Memory categories for user messages
        - 'skills' | 'learning' | 'task' | 'goal' | 'fact' | 'context' — Memory categories for assistant messages
      - `user_id` string, nullable
      - `external_user_id` string, nullable
      - `external_user_read_access` string[], nullable
      - `external_user_write_access` string[], nullable
      - `user_read_access` string[], nullable
      - `user_write_access` string[], nullable
      - `workspace_read_access` string[], nullable
      - `workspace_write_access` string[], nullable
      - `role_read_access` string[], nullable
      - `role_write_access` string[], nullable
      - `pageId` string, nullable
      - `sourceType` string, nullable
      - `workspace_id` string, nullable
      - `upload_id` string, nullable — Upload ID for document processing workflows
      - `organization_id` string, nullable
      - `namespace_id` string, nullable
      - `sessionId` string, nullable
      - `post` string, nullable
      - `userMessage` string, nullable
      - `assistantMessage` string, nullable
      - `relatedGoals` string[], nullable
      - `relatedUseCases` string[], nullable
      - `relatedSteps` string[], nullable
      - `goalClassificationScores` number[], nullable
      - `useCaseClassificationScores` number[], nullable
      - `stepClassificationScores` number[], nullable
      - `customMetadata` object, nullable — Optional object for arbitrary custom metadata fields. Only string, number, boolean, or list of strings allowed. Nested dicts are not allowed.
    - `context` ContextItem[], nullable — Context can be conversation history or any relevant context for a memory item
      - `role` 'user' | 'assistant', required
      - `content` string, required
    - `relationships_json` RelationshipItem[], nullable — Array of relationships that we can use in Graph DB (neo4J)
      - `relation_type` string, required
      - `related_item_id` string, nullable
      - `relationship_type` 'previous_memory_item_id' | 'all_previous_memory_items' | 'link_to_id' — Enum for relationship types
      - `related_item_type` string, nullable — Legacy field - not used in processing
      - `metadata` object
    - `organization_id` string, nullable — Optional organization ID for multi-tenant memory scoping. When provided, memory is associated with this organization.
    - `namespace_id` string, nullable — Optional namespace ID for multi-tenant memory scoping. When provided, memory is associated with this namespace.
  - `batch_size` integer, nullable — Number of items to process in parallel
  - `webhook_url` string, nullable — Optional webhook URL to notify when batch processing is complete. The webhook will receive a POST request with batch completion details.
  - `webhook_secret` string, nullable — Optional secret key for webhook authentication. If provided, will be included in the webhook request headers as 'X-Webhook-Secret'.

## Response `200`

Memories successfully added

- BatchMemoryResponse
  - `code` integer — HTTP status code for the batch operation
  - `status` string — 'success', 'partial', or 'error'
  - `message` string, nullable — Human-readable status message
  - `error` string, nullable — Batch-level error message, if any
  - `details` unknown
  - `successful` AddMemoryResponse[] — List of successful add responses
    - `code` integer — HTTP status code
    - `status` string — 'success' or 'error'
    - `data` AddMemoryItem[], nullable — List of memory items if successful
      - `memoryId` string, required
      - `createdAt` string, date-time, required
      - `objectId` string, required
      - `memoryChunkIds` string[]
    - `error` string, nullable — Error message if failed
    - `details` unknown
  - `errors` BatchMemoryError[] — List of errors for failed items
    - `index` integer, required
    - `error` string, required
    - `code` integer, nullable
    - `status` string, nullable
    - `details` unknown
  - `total_processed` integer
  - `total_successful` integer
  - `total_failed` integer
  - `total_content_size` integer
  - `total_storage_size` integer

## Other responses

- `207` — Partial success - some memories failed
- `400` — Bad request
- `401` — Unauthorized
- `403` — Subscription limit reached
- `413` — Content too large
- `415` — Unsupported Media Type
- `422` — Validation Error
- `500` — Internal server error

## Changes

- **2025-11-07** `14ff13755871` — 13 info
  - added the new optional request property `graph_generation`
  - added the new optional request property `memories/items/graph_generation`
  - added the new optional request property `memories/items/metadata/anyOf[subschema #1: MemoryMetadata]/category`
  - added the new optional request property `memories/items/metadata/anyOf[subschema #1: MemoryMetadata]/namespace_id`
  - …9 more

[Change history](https://skmtc.dev/papr-ai/apis/papr-memory-api/changes/v1/memory/batch/post.md)

---

[API](https://skmtc.dev/papr-ai/apis/papr-memory-api.md) · [All operations](https://skmtc.dev/papr-ai/apis/papr-memory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/papr-ai/apis/papr-memory-api/revisions/34b5e739fd20?raw)