Aswin-Ram-K · Sep 23, 2026
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
@@ -218,6 +218,23 @@
 							{
 								"group": "Migration Guides",
 								"pages": [
+									{
+										"group": "V3/V4 to V5",
+										"icon": "arrow-up-right",
+										"pages": [
+											"migration/api-v5",
+											"migration/api-v5-document-writes",
+											"migration/api-v5-document-updates",
+											"migration/api-v5-document-reads",
+											"migration/api-v5-recall",
+											"migration/api-v5-profiles",
+											"migration/api-v5-memory-forgetting",
+											"migration/api-v5-settings",
+											"migration/api-v5-organization",
+											"migration/api-v5-filters",
+											"migration/api-v5-rollout"
+										]
+									},
 									{
 										"group": "From another provider",
 										"icon": "truck",

diff --git a/apps/docs/migration/api-v5-document-reads.mdx b/apps/docs/migration/api-v5-document-reads.mdx
@@ -0,0 +1,11 @@
+---
+title: "Reading and deleting content on V5"
+description: "Fetching documents, listing resources, and deleting documents or memories"
+sidebarTitle: "Reading content"
+---
+
+import ContentManagement from "/snippets/api-v5-content-management.mdx";
+
+## Migration details
+
+<ContentManagement />
diff --git a/apps/docs/migration/api-v5-document-updates.mdx b/apps/docs/migration/api-v5-document-updates.mdx
@@ -0,0 +1,11 @@
+---
+title: "Updating documents and files on V5"
+description: "Pick deliberately between appending, replacing, and touching only metadata"
+sidebarTitle: "Updating documents"
+---
+
+import DocumentUpdates from "/snippets/api-v5-document-updates.mdx";
+
+## Migration details
+
+<DocumentUpdates />
diff --git a/apps/docs/migration/api-v5-document-writes.mdx b/apps/docs/migration/api-v5-document-writes.mdx
@@ -0,0 +1,11 @@
+---
+title: "Writing documents on V5"
+description: "Single, batch, and file ingestion that keeps legacy append semantics"
+sidebarTitle: "Ingesting documents"
+---
+
+import DocumentIngestion from "/snippets/api-v5-document-ingestion.mdx";
+
+## Migration details
+
+<DocumentIngestion />
diff --git a/apps/docs/migration/api-v5-filters.mdx b/apps/docs/migration/api-v5-filters.mdx
@@ -0,0 +1,11 @@
+---
+title: "Metadata filters on V5"
+description: "Turning loose legacy filter objects into expressions the server validates"
+sidebarTitle: "Filter expressions"
+---
+
+import Filters from "/snippets/api-v5-filters.mdx";
+
+## Migration details
+
+<Filters />
diff --git a/apps/docs/migration/api-v5-memory-forgetting.mdx b/apps/docs/migration/api-v5-memory-forgetting.mdx
@@ -0,0 +1,11 @@
+---
+title: "Forgetting memories on V5"
+description: "Exact and semantic deletion now share a single response contract"
+sidebarTitle: "Forgetting memories"
+---
+
+import MemoryForgetting from "/snippets/api-v5-memory-forgetting.mdx";
+
+## Migration details
+
+<MemoryForgetting />
diff --git a/apps/docs/migration/api-v5-organization.mdx b/apps/docs/migration/api-v5-organization.mdx
@@ -0,0 +1,11 @@
+---
+title: "Organization settings on V5"
+description: "What remains is the shared context string and a read-only namespace count"
+sidebarTitle: "Organization context"
+---
+
+import Organization from "/snippets/api-v5-organization.mdx";
+
+## Migration details
+
+<Organization />
diff --git a/apps/docs/migration/api-v5-profiles.mdx b/apps/docs/migration/api-v5-profiles.mdx
@@ -0,0 +1,11 @@
+---
+title: "Profiles and buckets on V5"
+description: "Profiles no longer take search parameters; buckets get their own resource"
+sidebarTitle: "Profiles & buckets"
+---
+
+import Profiles from "/snippets/api-v5-profiles.mdx";
+
+## Migration details
+
+<Profiles />
diff --git a/apps/docs/migration/api-v5-recall.mdx b/apps/docs/migration/api-v5-recall.mdx
@@ -0,0 +1,11 @@
+---
+title: "Searching on V5"
+description: "Modes, filters, attachments, changed defaults, and response readers"
+sidebarTitle: "Searching"
+---
+
+import Search from "/snippets/api-v5-search.mdx";
+
+## Migration details
+
+<Search />
diff --git a/apps/docs/migration/api-v5-rollout.mdx b/apps/docs/migration/api-v5-rollout.mdx
@@ -0,0 +1,11 @@
+---
+title: "Checking parity, then rolling out V5"
+description: "Establish behavioral parity, account for intended differences, and cut over safely"
+sidebarTitle: "Parity and rollout"
+---
+
+import Rollout from "/snippets/api-v5-rollout.mdx";
+
+## Migration details
+
+<Rollout />
diff --git a/apps/docs/migration/api-v5-settings.mdx b/apps/docs/migration/api-v5-settings.mdx
@@ -0,0 +1,11 @@
+---
+title: "Container tags become namespaces"
+description: "Listing namespaces, editing their settings, deleting them, and moving their content"
+sidebarTitle: "Namespace lifecycle"
+---
+
+import Namespaces from "/snippets/api-v5-namespaces.mdx";
+
+## Migration details
+
+<Namespaces />
diff --git a/apps/docs/migration/api-v5.mdx b/apps/docs/migration/api-v5.mdx
@@ -0,0 +1,63 @@
+---
+title: "Moving a V3/V4 integration onto V5"
+description: "Move existing API integrations onto the namespace-scoped V5 surface"
+sidebarTitle: "V3/V4 to V5"
+icon: "arrow-up-right"
+---
+
+import Overview from "/snippets/api-v5-overview.mdx";
+import DocumentIngestion from "/snippets/api-v5-document-ingestion.mdx";
+import DocumentUpdates from "/snippets/api-v5-document-updates.mdx";
+import ContentManagement from "/snippets/api-v5-content-management.mdx";
+import Search from "/snippets/api-v5-search.mdx";
+import Profiles from "/snippets/api-v5-profiles.mdx";
+import MemoryForgetting from "/snippets/api-v5-memory-forgetting.mdx";
+import Namespaces from "/snippets/api-v5-namespaces.mdx";
+import Organization from "/snippets/api-v5-organization.mdx";
+import Filters from "/snippets/api-v5-filters.mdx";
+import Rollout from "/snippets/api-v5-rollout.mdx";
+import Completion from "/snippets/api-v5-completion.mdx";
+
+<Overview />
+
+## Document ingestion
+
+<DocumentIngestion />
+
+## Document updates
+
+<DocumentUpdates />
+
+## Content management
+
+<ContentManagement />
+
+## Search
+
+<Search />
+
+## Profiles and buckets
+
+<Profiles />
+
+## Memory forgetting
+
+<MemoryForgetting />
+
+## Namespaces
+
+<Namespaces />
+
+## Organization settings
+
+<Organization />
+
+## Typed filters
+
+<Filters />
+
+## Verification and rollout
+
+<Rollout />
+
+<Completion />
diff --git a/apps/docs/snippets/api-v5-completion.mdx b/apps/docs/snippets/api-v5-completion.mdx
@@ -0,0 +1,29 @@
+## Agent migration prompt
+
+```text
+Move this repository off the legacy Supermemory V3/V4 API and onto V5. Begin by
+taking inventory: list every call site still targeting a legacy route. Then work
+through the per-domain guides linked from this page. Address exactly one
+namespace in each request. Where a default differs between the two versions,
+state it in the request rather than relying on whatever the server supplies.
+Bring response readers up to date as well. Back the change with contract tests
+that exercise old and new side by side. Leave application routes unprefixed, and
+leave connector routes alone. When an operation has been dropped, name it as
+dropped rather than manufacturing a stand-in.
+```
+
+## Operations without a direct replacement
+
+- **Direct memory creation and version updates** (`POST /v4/memories`,
+  `PATCH /v4/memories`): ingest or replace a source document instead.
+- **Organization bucket suggestion** (`POST /v3/settings/suggest-buckets`) and
+  **organization reset** (`POST /v3/settings/reset`): not part of the V5 public
+  surface.
+- **Connector routes** that still use `/v3`: unchanged; do not rewrite them.
+
+## Where to go next
+
+- [Authentication](/authentication) — unchanged bearer keys
+- [Search guide](/recall/search)
+- [Memory operations](/recall/memory-operations)
+- [API reference](/api-reference/overview) — legacy V3/V4 reference
diff --git a/apps/docs/snippets/api-v5-content-management.mdx b/apps/docs/snippets/api-v5-content-management.mdx
@@ -0,0 +1,105 @@
+In V5, retrieving, listing, and deleting all happen inside one namespace you name
+explicitly.
+
+### Retrieve a document and its derived context
+
+<CodeGroup>
+```bash Legacy
+GET /v3/documents/{id}
+GET /v3/documents/{id}/chunks
+```
+
+```bash V5
+GET /ns/{namespace}/document/{id}?attach=chunks&attach=memories
+```
+</CodeGroup>
+
+Supply `attach` more than once to pull in chunks, memories, or both. An
+attachment you never asked for is simply **missing** from the payload, whereas one
+you did ask for that found nothing comes back as an **empty array**. The
+difference is real: `result.chunks === undefined` and `result.chunks.length === 0`
+do not mean the same thing.
+
+The lifecycle fields have moved beneath `system`:
+
+```json
+{"system":{"status":"done","createdAt":"...","updatedAt":"..."}}
+```
+
+Legacy `GET /v3/documents/{id}` returned `status`, `createdAt`, and `updatedAt`
+as top-level fields, and needed a separate `GET /v3/documents/{id}/chunks` call
+for chunk data. V5 folds both into one request.
+
+### List documents, chunks, or memories
+
+<CodeGroup>
+```bash Legacy
+POST /v3/documents/list
+POST /v4/memories/list
+```
+
+```bash V5
+POST /ns/{namespace}/list/{type}?page=1&limit=100&sort=createdAt&order=desc
+{}
+```
+</CodeGroup>
+
+Give `type` one of `documents`, `chunks`, or `memories`. Paging and ordering move
+into the **query string**; the body carries nothing beyond an optional `filter`.
+
+Whichever type you ask for, the response carries `documents`, `chunks`,
+`memories`, and `pagination` — but only the array you selected has entries in it.
+Code that used to pull `memories` out of a document list has to read `documents`
+now.
+
+<Note>
+  This is the one place where the legacy and V5 shapes diverge most sharply.
+  `ListMemoriesQuerySchema` in this repository takes `page`, `limit`, `sort`,
+  `order`, and a **stringified** `filters` value in the query string; V5 keeps
+  the paging controls in the query string but moves filtering into a typed body
+  field.
+</Note>
+
+### Delete documents
+
+<CodeGroup>
+```bash Legacy
+DELETE /v3/documents/{id}
+DELETE /v3/documents/bulk
+```
+
+```bash V5
+DELETE /ns/{namespace}/document
+{"ids":["doc_1","external_id_2"]}
+```
+</CodeGroup>
+
+The V5 array accepts **1–100** Supermemory or caller-defined IDs. Inspect both
+`deletedCount` **and** per-ID `errors`: HTTP success can still include partial
+failures. The legacy bulk schema capped `ids` at 100 as well, so the limit is
+unchanged — but the legacy single-delete route is gone, and one call now covers
+both cases.
+
+### Forget memories
+
+| Legacy intent | V5 operation |
+| --- | --- |
+| Forget exact IDs | `DELETE /ns/{namespace}/memories` with `{"ids":[...]}` |
+| Find memories by meaning | `DELETE /ns/{namespace}/memories/semantic` with `{"query":"...","dryRun":true}` |
+
+Both answer with `{ count, matches, errors }`. To delete semantically without
+drift, preview under `dryRun: true`, inspect the returned IDs, and send that exact
+list to the exact-ID endpoint.
+
+The full dry-run, approval, response, and audit flow lives in
+[memory forgetting](./api-v5-memory-forgetting).
+
+### Verification
+
+- Assert that requested-but-empty attachments are `[]` while omitted attachments
+  are absent.
+- Paginate each resource type until `currentPage >= totalPages`; confirm
+  unselected arrays stay empty.
+- Verify chunk rows carry their parent `documentId`.
+- Try a document delete that only partly succeeds, and a semantic dry run.
+- Verify an ID cannot read, list, or delete content outside its namespace.