Migrate document and file updates to v5

On v3 or v4? Run npx supermemory@latest migrate, or read the full v5 migration guide.

Migration details

v5 makes the difference between adding new information and replacing the canonical source explicit.

Choose the correct write

Intent	Operation	Content behavior
Add information to a stable caller ID	`POST /ns/{namespace}/document`	Append/diff
Replace text or URL content	`PATCH /ns/{namespace}/document/{id}`	Replace and reprocess
Update only metadata, context, or date	Same `PATCH` without `content`	Canonical content unchanged
Replace a source file and its user metadata	`POST /ns/{namespace}/document/file/{id}`	Full replacement and reprocess
Partially update a file or its supporting fields	`PATCH /ns/{namespace}/document/file/{id}`	Omitted fields remain unchanged

Update text or URL content

PATCH /v3/documents/doc_1
{"content":"corrected source","metadata":{"revision":2}}

PATCH /ns/user_1/document/doc_1
{"content":"corrected source","metadata":{"revision":2},"dreaming":"dynamic"}

The v5 body accepts any non-empty subset of content, supportingContext, metadata, or date, plus optional taskType and dreaming (which alone do not count as a change). group is an ingestion-side setting: it picks which existing memories serve as context while content is processed, so changing it only takes effect when the document is re-ingested. Send it together with content. Supplying content makes it the new canonical source; facts supported only by the previous source can disappear after reprocessing.

Replace a file-backed document

POST /ns/user_1/document/file/doc_1
Content-Type: multipart/form-data

file=@corrected.pdf
metadata={"revision":2}
dreaming=dynamic

POST requires file and replaces the canonical source plus caller metadata, including date. Omitted metadata and date are cleared. supportingContext is stored on the namespace, so omitting it leaves the namespace’s existing context unchanged. Use it when the submitted request is the complete new representation of the file-backed document.

Partially update a file-backed document

PATCH /ns/user_1/document/file/doc_1
Content-Type: multipart/form-data

metadata={"reviewed":true}
dreaming=dynamic

PATCH changes only supplied fields. Include file to replace the source while retaining omitted supporting fields, or omit file for metadata-, context-, or date-only changes. Like the JSON update, group only takes effect when the file is re-ingested, so send it together with file. metadata and group are JSON-encoded strings; supportingContext and date are plain strings.

There is no public v5 PUT /ns/{namespace}/document/file/{id} operation. Use POST for a complete replacement and PATCH for a partial update.

With the SDK

await client.documents.update("doc_1", {
  content: "corrected source",
  metadata: { revision: 2 },
})

await supermemory.documents.update("user_1", "doc_1", {
  content: "corrected source",
  metadata: { revision: 2 },
})

await supermemory.documents.replaceWithFile("user_1", "doc_1", {
  file,
  metadata: JSON.stringify({ revision: 2 }),
})

await supermemory.documents.updateFile("user_1", "doc_1", {
  metadata: JSON.stringify({ reviewed: true }),
})

replaceWithFile is the POST full replacement and requires file. updateFile is the PATCH partial update; file is optional and metadata merges key by key.

IDs and scope

The path id may be the Supermemory document ID or your caller-defined ID. It is resolved only inside {namespace}; an ID from another namespace is not a cross-namespace update mechanism.

Processing and conflicts

Content or file replacement is accepted before downstream processing completes. A namespace merge in progress or a conflicting internal file path returns 409; retry a merge conflict after the merge finishes.

Verification

Patch metadata alone and confirm document content and derived facts remain intact.
Patch content and confirm the new source is canonical after processing.
Replace a file with POST and confirm omitted user metadata is cleared.
Patch a file-backed document and confirm omitted fields remain unchanged.
Attempt the same ID in another namespace and confirm the update is rejected or not found.

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Migration details

Choose the correct write

Update text or URL content

Replace a file-backed document

Partially update a file-backed document

With the SDK

IDs and scope

Processing and conflicts

Verification

​Migration details

​Choose the correct write

​Update text or URL content

​Replace a file-backed document

​Partially update a file-backed document

​With the SDK

​IDs and scope

​Processing and conflicts

​Verification

Migration details

Choose the correct write

Update text or URL content

Replace a file-backed document

Partially update a file-backed document

With the SDK

IDs and scope

Processing and conflicts

Verification