Migrate document ingestion to v5

Migration details

v5 moves document scope into the URL and keeps repeated caller IDs attached to one evolving document.

Rename common fields

Legacy	v5	Location
`containerTag`	`{namespace}`	Path
`customId`	`id`	JSON body
`entityContext`	`supportingContext`	JSON/form body
`filterByMetadata`	`group`	JSON/form body
`documentDate`	`date`	JSON/form body
`taskType`, `dreaming`	unchanged	JSON/form body

Add or append one document

POST /v3/documents
{"content":"new turn","customId":"conv_1","containerTag":"user_1"}

POST /ns/user_1/document
{"content":"new turn","id":"conv_1","dreaming":"dynamic"}

The response remains an acceptance result with id and status. Its status is the document’s processing state after the request: queued when new work was queued, otherwise the document’s current state (for example done for an unchanged duplicate, or failed for a metadata-only update to a failed document). Possible values: unknown, queued, extracting, chunking, embedding, indexing, done, failed. Repeating the v5 request with id: "conv_1" adds or diffs the new content into that document; it does not silently replace the canonical source.

Batch ingestion

{"documents":["first","second"],"containerTag":"user_1"}

{"documents":[{"content":"first","id":"doc_1"},{"content":"second","id":"doc_2"}]}

Send the v5 body to POST /ns/user_1/document/batch. The array accepts 1–600 document objects. taskType and dreaming sit at the top level of the body, next to documents, and apply to every item; document content, ID, context, metadata, grouping, and date stay per item. results lists accepted documents first, in request order, then failed ones; match each result by id, or by url for a failed item with no ID. Inspect count (accepted), failed, and every item in results; each item’s status is the document’s processing state (unknown, queued, extracting, chunking, embedding, indexing, done, or failed), or error when that item failed, and a batch can contain successful and failed items together.

File ingestion

Replace POST /v3/documents/file with POST /ns/{namespace}/document/file. Continue using multipart/form-data:

Part	Encoding
`file`	Binary file
`supportingContext`, `date`	Plain strings
`metadata`, `group`	JSON-encoded strings
`taskType`, `dreaming`	Plain strings
`fileType`, `mimeType`	Plain strings, only when inference is insufficient

The API acknowledges the file after durable acceptance, with status set as for a JSON add. Extraction, indexing, and memory formation continue asynchronously; poll the document rather than assuming the first response means processing is complete.

Processing choices

taskType: "memory" extracts long-term memories; taskType: "superrag" indexes source context without memory generation.
dreaming: "dynamic" (default) groups related documents into coherent memory units.
dreaming: "instant" processes each document independently and bills one extra operation per document.
Memories appear quickly only with dreaming: "instant". Under dynamic, a fresh namespace can show zero memories and an empty profile for several minutes. Use instant for quickstarts and parity tests.

These options go in the JSON body (or as form fields for file routes). Ingest routes take no query parameters; sending one returns 400.

With the SDK

await client.add({
  content: "new turn",
  customId: "conv_1",
  containerTag: "user_1",
  metadata: { source: "chat" },
})

await client.documents.batchAdd({
  documents: [{ content: "first" }, { content: "second" }],
  containerTag: "user_1",
})

await client.documents.uploadFile({ file, containerTag: "user_1" })

await client.add("user_1", {
  content: "new turn",
  id: "conv_1",
  metadata: { source: "chat" },
  dreaming: "instant",
})

await client.documents.batchAdd("user_1", {
  documents: [
    { content: "first", id: "doc_1" },
    { content: "second", id: "doc_2" },
  ],
})

await client.documents.uploadFile("user_1", {
  file,
  metadata: JSON.stringify({ source: "upload" }),
})

The namespace is the first argument on every call. taskType and dreaming sit next to content in the same object. uploadFile is multipart, so metadata is a JSON string there, not an object.

Verification

Ingest text, a public URL, and a file, then wait for each document to finish processing.
Repeat a caller-defined ID and confirm append/diff behavior instead of replacement.
Submit a mixed-success batch and verify each result matches its document by ID, with per-item errors.
Confirm metadata and grouping remain filterable after processing.

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Migration details

Rename common fields

Add or append one document

Batch ingestion

File ingestion

Processing choices

With the SDK

Verification

​Migration details

​Rename common fields

​Add or append one document

​Batch ingestion

​File ingestion

​Processing choices

​With the SDK

​Verification

Migration details

Rename common fields

Add or append one document

Batch ingestion

File ingestion

Processing choices

With the SDK

Verification