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

# Migrate document ingestion to v5

> Upgrade single, batch, and file ingestion without changing append behavior

## 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

<CodeGroup>
  ```bash Legacy theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  POST /v3/documents
  {"content":"new turn","customId":"conv_1","containerTag":"user_1"}
  ```

  ```bash v5 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  POST /ns/user_1/document
  {"content":"new turn","id":"conv_1","dreaming":"dynamic"}
  ```
</CodeGroup>

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

<CodeGroup>
  ```json Legacy theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {"documents":["first","second"],"containerTag":"user_1"}
  ```

  ```json v5 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {"documents":[{"content":"first","id":"doc_1"},{"content":"second","id":"doc_2"}]}
  ```
</CodeGroup>

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

<CodeGroup>
  ```ts Legacy theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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" })
  ```

  ```ts v5 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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" }),
  })
  ```
</CodeGroup>

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.