Skip to main content
POST
/
v3
/
documents
/
batch
Batch add documents
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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',
        containerTags: ['<string>'],
        customId: 'doc-api-rate-limits',
        metadata: {source: 'upload', language: 'en'},
        taskType: 'memory',
        filepath: '/documents/reports/file.pdf',
        filterByMetadata: {department: 'engineering', region: 'us'},
        entityContext: 'User\'s name is {XYZ}'
      }
    ],
    content: null
  })
};

fetch('https://api.supermemory.ai/v3/documents/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "results": [
    {
      "id": "<string>",
      "status": "<string>",
      "error": "<string>",
      "details": "<string>"
    }
  ],
  "failed": 123,
  "success": 123
}

Documentation Index

Fetch the complete documentation index at: https://supermemory.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
documents
required
Required array length: 1 - 600 elements
​
containerTag
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.

Maximum string length: 100
Pattern: ^[a-zA-Z0-9_:-]+$
Example:

"user_alex"

​
containerTags
string[]
deprecated

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

Maximum string length: 100
Pattern: ^[a-zA-Z0-9_:-]+$
​
metadata
object

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" }
​
taskType
enum<string>

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

Available options:
memory,
superrag
Example:

"memory"

​
filepath
string

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"

​
filterByMetadata
object

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"
}
​
entityContext
string

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

Maximum string length: 1500
Example:

"User's name is {XYZ}"

​
content
null

Response

Documents added successfully

​
results
object[]
required

Array of results for each document in the batch

​
failed
number
required

Count of documents that failed to add

​
success
number
required

Count of documents successfully added