Batch add documents

POST/v3/documents/batch

Add multiple documents in a single request. Each document can have any content type (text, url, file, etc.) and metadata

Body ParametersJSONExpand Collapse

documents: array of object { content, containerTag, containerTags, 8 more } or array of string

One of the following:

array of object { content, containerTag, containerTags, 8 more }

content: string

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.

containerTag: optional string

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.

maxLength100

DeprecatedcontainerTags: optional array of string

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

customId: optional string

Optional custom ID of the document. This could be an ID from your database that will uniquely identify this document.

documentDate: optional string

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.

dreaming: optional "instant" or "dynamic"

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.

One of the following:

"instant"

"dynamic"

entityContext: optional string

Optional entity context for this container tag. Max 1500 characters. Used during document processing to guide memory extraction.

maxLength1500

filepath: optional string

Optional file path for the document (e.g., ‘/documents/reports/file.pdf’). Used by supermemoryfs to map documents to filesystem paths.

filterByMetadata: optional map[string or number or boolean or array of string]

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.

One of the following:

string

number

boolean

array of string

metadata: optional map[string or number or boolean or array of string]

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.

One of the following:

string

number

boolean

array of string

taskType: optional "memory" or "superrag"

Task type: “memory” (default) for full context layer with SuperRAG built in, “superrag” for managed RAG as a service.

One of the following:

"memory"

"superrag"

array of string

containerTag: optional string

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.

maxLength100

DeprecatedcontainerTags: optional array of string

content: optional unknown

documentDate: optional string

dreaming: optional "instant" or "dynamic"

One of the following:

"instant"

"dynamic"

entityContext: optional string

Optional entity context for this container tag. Max 1500 characters. Used during document processing to guide memory extraction.

maxLength1500

filepath: optional string

Optional file path for the document (e.g., ‘/documents/reports/file.pdf’). Used by supermemoryfs to map documents to filesystem paths.

filterByMetadata: optional map[string or number or boolean or array of string]

One of the following:

string

number

boolean

array of string

metadata: optional map[string or number or boolean or array of string]

One of the following:

string

number

boolean

array of string

taskType: optional "memory" or "superrag"

Task type: “memory” (default) for full context layer with SuperRAG built in, “superrag” for managed RAG as a service.

One of the following:

"memory"

"superrag"

ReturnsExpand Collapse

failed: number

Count of documents that failed to add

results: array of object { id, status, details, 2 more }

Array of results for each document in the batch

id: string

Unique identifier of the document (empty string for failed items)

status: string

Status of the document (e.g. ‘done’, ‘queued’, ‘error’)

details: optional string

Additional error details when status is ‘error’

error: optional string

Error message when status is ‘error’

url: optional string

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).

success: number

Count of documents successfully added

Batch add documents

curl https://api.supermemory.ai/v3/documents/batch \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
    -d "{
          \"documents\": [
            {
              \"content\": \"Our API rate limits are 100 req/min on free and 1000 on pro. Clients should use exponential backoff on 429s.\"
            }
          ],
          \"containerTag\": \"user_alex\",
          \"documentDate\": \"2025-03-14\",
          \"dreaming\": \"instant\",
          \"entityContext\": \"User's name is {XYZ}\",
          \"filepath\": \"/documents/reports/file.pdf\",
          \"filterByMetadata\": {
            \"department\": \"engineering\",
            \"region\": \"us\"
          },
          \"metadata\": {
            \"source\": \"upload\",
            \"language\": \"en\"
          },
          \"taskType\": \"memory\"
        }"

{
  "failed": 0,
  "results": [
    {
      "id": "id",
      "status": "status",
      "details": "details",
      "error": "error",
      "url": "url"
    }
  ],
  "success": 0
}

Returns Examples

{
  "failed": 0,
  "results": [
    {
      "id": "id",
      "status": "status",
      "details": "details",
      "error": "error",
      "url": "url"
    }
  ],
  "success": 0
}