> ## Documentation Index > Fetch the complete documentation index at: https://supermemory-personal-brain-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Batch add documents > Add multiple documents in a single request. Each document can have any content type (text, url, file, etc.) and metadata ## OpenAPI ````yaml https://api.supermemory.ai/v4/openapi post /v3/documents/batch openapi: 3.1.0 info: title: supermemory API description: >- The Memory API for the AI era. OpenAPI operations include x-codeSamples for the official TypeScript and Python SDKs (Mintlify-compatible). version: 3.0.0 servers: - description: Production Server url: https://api.supermemory.ai security: - bearerAuth: [] tags: - name: Ingest description: Ingest documents, files, URLs, conversations, and other content - name: Recall (Search) description: >- Semantic recall across your content — supports memories, hybrid, and documents modes - name: Profiles description: >- Entity profiles for users, participants, or any entity — includes profile search - name: Content Management description: List, get, update, and delete content and memories - name: Container Tags description: List and manage container tags (spaces) — settings, merge, and delete - name: Connections description: External service integrations - name: Settings description: Organization settings - name: Documents description: List, get, and search documents paths: /v3/documents/batch: post: tags: - Ingest summary: Batch add documents description: >- Add multiple documents in a single request. Each document can have any content type (text, url, file, etc.) and metadata operationId: postV3DocumentsBatch requestBody: required: true content: application/json: schema: type: object properties: containerTag: description: >- Optional tag this document should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to group documents. example: user_alex type: string maxLength: 100 pattern: ^[a-zA-Z0-9_:-]+$ containerTags: description: >- (DEPRECATED: Use containerTag instead) Optional tags this document should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to group documents. deprecated: true x-hidden: true type: array items: type: string maxLength: 100 pattern: ^[a-zA-Z0-9_:-]+$ metadata: description: >- Optional metadata for the document. This is used to store additional information about the document. You can use this to store any additional information you need about the document. Metadata can be filtered through. Keys must be strings and are case sensitive. Values can be strings, numbers, or booleans. You cannot nest objects. example: source: upload language: en type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: number - type: boolean - type: array items: type: string taskType: description: >- Task type: "memory" (default) for full context layer with SuperRAG built in, "superrag" for managed RAG as a service. example: memory type: string enum: - memory - superrag filepath: description: >- Optional file path for the document (e.g., '/documents/reports/file.pdf'). Used by supermemoryfs to map documents to filesystem paths. example: /documents/reports/file.pdf x-hidden: true type: string filterByMetadata: description: >- Optional metadata filter scoping which existing memories are pulled as context during ingestion. Scalar values match exactly (AND across keys); array values match ANY (OR within key). Only memories whose source documents match this filter are used as context. example: department: engineering region: us type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: number - type: boolean - type: array items: type: string documentDate: description: >- When this document's content is from, as opposed to when it was uploaded. Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves relative dates ('yesterday', 'last quarter') against this instead of the ingestion time, and documents in a batch are processed oldest-first so newer facts correctly supersede older ones. Set this whenever you backfill historical content. example: '2025-03-14' type: string entityContext: description: >- Optional entity context for this container tag. Max 1500 characters. Used during document processing to guide memory extraction. example: User's name is {XYZ} type: string maxLength: 1500 dreaming: description: >- Processing mode. "dynamic" (default) groups related documents together so memories form from coherent, logical units rather than one isolated entry at a time. "instant" processes each document on its own right away, and bills one extra operation per document. example: instant type: string enum: - instant - dynamic documents: anyOf: - minItems: 1 maxItems: 600 type: array items: type: object properties: containerTag: description: >- Optional tag this document should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to group documents. example: user_alex type: string maxLength: 100 pattern: ^[a-zA-Z0-9_:-]+$ containerTags: description: >- (DEPRECATED: Use containerTag instead) Optional tags this document should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to group documents. deprecated: true x-hidden: true type: array items: type: string maxLength: 100 pattern: ^[a-zA-Z0-9_:-]+$ content: type: string description: >- The content to extract and process into a document. This can be a URL to a website, a PDF, an image, or a video. Plaintext: Any plaintext format URL: A URL to a website, PDF, image, or video We automatically detect the content type from the url's response format. example: >- Our API rate limits are 100 req/min on free and 1000 on pro. Clients should use exponential backoff on 429s. customId: description: >- Optional custom ID of the document. This could be an ID from your database that will uniquely identify this document. example: doc-api-rate-limits type: string metadata: description: >- Optional metadata for the document. This is used to store additional information about the document. You can use this to store any additional information you need about the document. Metadata can be filtered through. Keys must be strings and are case sensitive. Values can be strings, numbers, or booleans. You cannot nest objects. example: source: upload language: en type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: number - type: boolean - type: array items: type: string taskType: description: >- Task type: "memory" (default) for full context layer with SuperRAG built in, "superrag" for managed RAG as a service. example: memory type: string enum: - memory - superrag filepath: description: >- Optional file path for the document (e.g., '/documents/reports/file.pdf'). Used by supermemoryfs to map documents to filesystem paths. example: /documents/reports/file.pdf x-hidden: true type: string filterByMetadata: description: >- Optional metadata filter scoping which existing memories are pulled as context during ingestion. Scalar values match exactly (AND across keys); array values match ANY (OR within key). Only memories whose source documents match this filter are used as context. example: department: engineering region: us type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: number - type: boolean - type: array items: type: string documentDate: description: >- When this document's content is from, as opposed to when it was uploaded. Accepts YYYY-MM-DD or a full ISO 8601 timestamp. Memory extraction resolves relative dates ('yesterday', 'last quarter') against this instead of the ingestion time, and documents in a batch are processed oldest-first so newer facts correctly supersede older ones. Set this whenever you backfill historical content. example: '2025-03-14' type: string entityContext: description: >- Optional entity context for this container tag. Max 1500 characters. Used during document processing to guide memory extraction. example: User's name is {XYZ} type: string maxLength: 1500 dreaming: description: >- Processing mode. "dynamic" (default) groups related documents together so memories form from coherent, logical units rather than one isolated entry at a time. "instant" processes each document on its own right away, and bills one extra operation per document. example: instant type: string enum: - instant - dynamic required: - content - minItems: 1 maxItems: 600 type: array items: type: string description: >- The content to extract and process into a document. This can be a URL to a website, a PDF, an image, or a video. Plaintext: Any plaintext format URL: A URL to a website, PDF, image, or video We automatically detect the content type from the url's response format. example: >- Our API rate limits are 100 req/min on free and 1000 on pro. Clients should use exponential backoff on 429s. content: type: 'null' required: - documents responses: '200': content: application/json: schema: type: object required: - results - failed - success properties: results: type: array items: type: object required: - id - status properties: id: type: string description: >- Unique identifier of the document (empty string for failed items) status: type: string description: >- Status of the document (e.g. 'done', 'queued', 'error') error: type: string description: Error message when status is 'error' details: type: string description: Additional error details when status is 'error' url: type: string description: >- URL of the failed item, when it had one. Only present on failed items, where it may be the only way to tell which input the error belongs to (the id falls back to 'unknown' when the input had neither an id nor a customId). additionalProperties: false description: Array of results for each document in the batch failed: type: number description: Count of documents that failed to add success: type: number description: Count of documents successfully added additionalProperties: false description: Documents added successfully '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '402': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Document token limit reached '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error x-codeSamples: - lang: typescript label: TypeScript SDK source: |- import Supermemory from "supermemory"; const client = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY, }); const res = await client.documents.batchAdd({ documents: [ { content: "Q3 roadmap notes", containerTag: "user_123", customId: "doc_roadmap", }, { content: "Gift policy for VP promotions", containerTag: "user_123", customId: "doc_gifts", }, ], }); console.log(res); - lang: python label: Python SDK source: |- from supermemory import Supermemory client = Supermemory() # uses SUPERMEMORY_API_KEY res = client.documents.batch_add( documents=[ { "content": "Q3 roadmap notes", "container_tag": "user_123", "custom_id": "doc_roadmap", }, { "content": "Gift policy for VP promotions", "container_tag": "user_123", "custom_id": "doc_gifts", }, ], ) print(res) - lang: bash label: cURL source: |- curl -X POST "https://api.supermemory.ai/v3/documents/batch" \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "documents": [ { "content": "Q3 roadmap notes", "containerTag": "user_123", "customId": "doc_roadmap" } ] }' components: schemas: ErrorResponse: type: object properties: error: type: string description: Error message example: Invalid request parameters details: type: string description: Additional error details example: Query must be at least 1 character long required: - error securitySchemes: bearerAuth: scheme: bearer type: http ````