docs(api): add V3/V4 to V5 migration guide (#1691)

Document every migrated workflow, request and response change, typed-filter conversion, verification strategy, and rollout step so agents can upgrade integrations deterministically.
2026-10-08 03:08:21 +00:00 · 2026-10-06 16:48:36 +00:00 · 2026-10-06 16:48:36 +00:00 · 3b84713097
commit 3b84713097
parent 9c1257039e
35 changed files with 1019 additions and 14 deletions
--- a/apps/docs/api-reference/overview.mdx
+++ b/apps/docs/api-reference/overview.mdx
@ -4,6 +4,10 @@ description: "Interactive reference for the Supermemory HTTP API: ingest, search
 icon: "/icons/hugeicons/plug-socket.svg"
 ---

+<Warning>
+This is the legacy v3/v4 reference. v3 and v4 are deprecated and will be shut down on **December 31, 2026**. Move to [v5](/v5/api-reference/overview) before then. The [migration guide](/migration/api-v5) maps every legacy call to its v5 equivalent.
+</Warning>
+
 This is the **contract-level** reference for Supermemory: methods, paths, parameters, and the playground.

 For narrative guides (when to use what, patterns, SDKs), start with the [Quickstart](/quickstart) and [Using supermemory](/ingestion/add-memories).
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@ -1,5 +1,9 @@
 {
 	"$schema": "https://mintlify.com/docs.json",
+	"banner": {
+		"content": "**v3 and v4 are deprecated and will be shut down on December 31, 2026.** Move to v5 before then. [Read the migration guide](/migration/api-v5).",
+		"dismissible": true
+	},
 	"api": {
 		"examples": {
 			"defaults": "required",
@ -247,6 +251,23 @@
 							{
 								"group": "Migration guides",
 								"pages": [
+									{
+										"group": "Supermemory API upgrades",
+										"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": "/icons/hugeicons/delivery-truck-01.svg",
@ -293,7 +314,7 @@
 						"icon": "/icons/hugeicons/plug-socket.svg",
 						"versions": [
 							{
-								"version": "Legacy (V3, V4)",
+								"version": "Legacy (v3, v4)",
 								"openapi": "https://api.supermemory.ai/v4/openapi",
 								"pages": [
 									"api-reference/overview",
@ -391,7 +412,7 @@
 								]
 							},
 							{
-								"version": "Latest (V5)",
+								"version": "Latest (v5)",
 								"default": true,
 								"openapi": {
 									"source": "https://api.supermemory.ai/v5/openapi",
--- a/apps/docs/migration/api-v5-document-reads.mdx
+++ b/apps/docs/migration/api-v5-document-reads.mdx
@ -0,0 +1,11 @@
+---
+title: "Migrate content management to v5"
+description: "Upgrade document retrieval, resource lists, and document or memory deletion"
+sidebarTitle: "Content management"
+---
+
+import ContentManagement from "/snippets/api-v5-content-management.mdx";
+
+## Migration details
+
+<ContentManagement />
--- a/apps/docs/migration/api-v5-document-updates.mdx
+++ b/apps/docs/migration/api-v5-document-updates.mdx
@ -0,0 +1,11 @@
+---
+title: "Migrate document and file updates to v5"
+description: "Choose append, replacement, or metadata-only updates deliberately"
+sidebarTitle: "Document updates"
+---
+
+import DocumentUpdates from "/snippets/api-v5-document-updates.mdx";
+
+## Migration details
+
+<DocumentUpdates />
--- a/apps/docs/migration/api-v5-document-writes.mdx
+++ b/apps/docs/migration/api-v5-document-writes.mdx
@ -0,0 +1,11 @@
+---
+title: "Migrate document ingestion to v5"
+description: "Upgrade single, batch, and file ingestion without changing append behavior"
+sidebarTitle: "Document ingestion"
+---
+
+import DocumentIngestion from "/snippets/api-v5-document-ingestion.mdx";
+
+## Migration details
+
+<DocumentIngestion />
--- a/apps/docs/migration/api-v5-filters.mdx
+++ b/apps/docs/migration/api-v5-filters.mdx
@ -0,0 +1,11 @@
+---
+title: "Migrate metadata filters to v5"
+description: "Convert legacy Query filters into strict, type-safe v5 filter expressions"
+sidebarTitle: "Typed filters"
+---
+
+import Filters from "/snippets/api-v5-filters.mdx";
+
+## Migration details
+
+<Filters />
--- a/apps/docs/migration/api-v5-memory-forgetting.mdx
+++ b/apps/docs/migration/api-v5-memory-forgetting.mdx
@ -0,0 +1,11 @@
+---
+title: "Migrate memory forgetting to v5"
+description: "Replace legacy exact and semantic forgetting with one response contract"
+sidebarTitle: "Memory forgetting"
+---
+
+import MemoryForgetting from "/snippets/api-v5-memory-forgetting.mdx";
+
+## Migration details
+
+<MemoryForgetting />
--- a/apps/docs/migration/api-v5-organization.mdx
+++ b/apps/docs/migration/api-v5-organization.mdx
@ -0,0 +1,11 @@
+---
+title: "Migrate organization settings to v5"
+description: "Reduce organization settings to shared context and namespace count"
+sidebarTitle: "Organization settings"
+---
+
+import Organization from "/snippets/api-v5-organization.mdx";
+
+## Migration details
+
+<Organization />
--- a/apps/docs/migration/api-v5-profiles.mdx
+++ b/apps/docs/migration/api-v5-profiles.mdx
@ -0,0 +1,11 @@
+---
+title: "Migrate profiles and buckets to v5"
+description: "Separate profile retrieval from search and manage namespace-owned buckets"
+sidebarTitle: "Profiles and buckets"
+---
+
+import Profiles from "/snippets/api-v5-profiles.mdx";
+
+## Migration details
+
+<Profiles />
--- a/apps/docs/migration/api-v5-recall.mdx
+++ b/apps/docs/migration/api-v5-recall.mdx
@ -0,0 +1,11 @@
+---
+title: "Migrate search to v5"
+description: "Upgrade search modes, filters, attachments, defaults, and response readers"
+sidebarTitle: "Search"
+---
+
+import Search from "/snippets/api-v5-search.mdx";
+
+## Migration details
+
+<Search />
--- a/apps/docs/migration/api-v5-rollout.mdx
+++ b/apps/docs/migration/api-v5-rollout.mdx
@ -0,0 +1,11 @@
+---
+title: "Verify and roll out a v5 migration"
+description: "Prove behavioral parity, detect intentional differences, and cut over safely"
+sidebarTitle: "Verification and rollout"
+---
+
+import Rollout from "/snippets/api-v5-rollout.mdx";
+
+## Migration details
+
+<Rollout />
--- a/apps/docs/migration/api-v5-settings.mdx
+++ b/apps/docs/migration/api-v5-settings.mdx
@ -0,0 +1,11 @@
+---
+title: "Migrate container tags to namespaces"
+description: "Upgrade namespace discovery, settings, deletion, and moves"
+sidebarTitle: "Namespaces"
+---
+
+import Namespaces from "/snippets/api-v5-namespaces.mdx";
+
+## Migration details
+
+<Namespaces />
--- a/apps/docs/migration/api-v5.mdx
+++ b/apps/docs/migration/api-v5.mdx
@ -0,0 +1,71 @@
+---
+title: "Migrate Supermemory v3/v4 to v5"
+description: "Upgrade legacy API calls to the namespace-scoped v5 API"
+sidebarTitle: "Legacy API to v5"
+icon: "arrow-up-right"
+---
+
+import AgentPrompt from "/snippets/api-v5-agent-prompt.mdx";
+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 Sdks from "/snippets/api-v5-sdks.mdx";
+import Completion from "/snippets/api-v5-completion.mdx";
+
+<AgentPrompt />
+
+<Overview />
+
+## SDKs, tools and the CLI
+
+<Sdks />
+
+## 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 />
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@ -6,7 +6,7 @@
  "portless": { "name": "docs.dev.supermemory", "script": "dev:app", "appPort": 3003 },
  "scripts": {
    "dev": "portless",
-    "dev:app": "bunx mintlify@latest dev --no-open --port 3003"
+    "dev:app": "bash scripts/dev.sh"
  },
  "devDependencies": {
    "@types/bun": "latest",
--- a/apps/docs/scripts/dev.sh
+++ b/apps/docs/scripts/dev.sh
@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+docs_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+docs_port="${PORT:-3003}"
+mintlify_args=(dev --no-open --port "$docs_port")
+
+printf -v docs_dir_escaped "%q" "$docs_dir"
+printf -v mintlify_args_escaped " %q" "${mintlify_args[@]}"
+
+# Run outside the monorepo so npx does not pick up Mintlify's Bun-installed
+# dependency tree, which is incompatible with its Node-based schema compiler.
+cd /tmp
+exec npx --yes \
+  --package node@22 \
+  --package mintlify@latest \
+  --call "cd $docs_dir_escaped && mintlify$mintlify_args_escaped"
--- a/apps/docs/snippets/api-v5-agent-prompt.mdx
+++ b/apps/docs/snippets/api-v5-agent-prompt.mdx
@ -0,0 +1,7 @@
+## Migrate with an agent
+
+Paste this into Claude Code, Cursor, or Codex. It fetches this guide as markdown and rewrites every legacy call.
+
+```text
+Migrate this repository from Supermemory v3/v4 to v5. Fetch https://supermemory.ai/docs/migration/api-v5.md and follow it exactly. First write a checklist of every legacy call site, then migrate them one by one and tick each off. Stop and report any operation that has no v5 replacement instead of inventing one.
+```
--- a/apps/docs/snippets/api-v5-completion.mdx
+++ b/apps/docs/snippets/api-v5-completion.mdx
@ -0,0 +1,9 @@
+## Operations without a direct replacement
+
+- Direct memory creation and version updates: ingest or replace a source document instead.
+- Organization bucket suggestion and organization reset: not part of the v5 public surface.
+- Connector routes that still use `/v3`: unchanged; do not rewrite them.
+- Conversation ingestion (`/v4/conversations`): not part of the v5 public surface. Send the transcript as a document instead.
+- Container-tag merges: not part of the v5 public surface.
+
+Use the [v5 reference](https://api.supermemory.ai/v5/reference) for the stable v5 API. [`/reference`](https://api.supermemory.ai/reference) always points to the latest public version.
--- a/apps/docs/snippets/api-v5-content-management.mdx
+++ b/apps/docs/snippets/api-v5-content-management.mdx
@ -0,0 +1,73 @@
+v5 retrieves, lists, and removes content within one explicit namespace.
+
+### 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>
+
+Repeat `attach` to include chunks, memories, or both. Omitted attachment keys are absent; requested attachments with no results are empty arrays. Lifecycle fields move under `system`:
+
+```json
+{"system":{"status":"done","createdAt":"...","updatedAt":"..."}}
+```
+
+### 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>
+
+Set `type` to `documents`, `chunks`, or `memories`. Pagination and sorting move to the query string; the body contains only optional `filter`.
+
+Every response contains `documents`, `chunks`, `memories`, and `pagination`. Only the selected resource array is populated. Replace legacy `memories` assumptions in document-list callers with `documents`.
+
+### 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 include partial failures.
+
+### 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 return `{ count, matches, errors }`. For drift-free semantic deletion, preview with `dryRun: true`, review the IDs, then submit them to the exact-ID endpoint.
+
+See [memory forgetting](./api-v5-memory-forgetting) for the complete dry-run, approval, response, and audit workflow.
+
+### Verification
+
+- Assert requested empty attachments are `[]`, while omitted attachments are absent.
+- Paginate each resource type until `currentPage >= totalPages`; unselected arrays stay empty.
+- Verify chunk rows contain their parent `documentId`.
+- Exercise partial document-delete failures and semantic dry runs.
+- Verify IDs cannot read, list, or delete content outside their namespace.
--- a/apps/docs/snippets/api-v5-document-ingestion.mdx
+++ b/apps/docs/snippets/api-v5-document-ingestion.mdx
@ -0,0 +1,70 @@
+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 | Query string |
+
+### Add or append one document
+
+<CodeGroup>
+```bash Legacy
+POST /v3/documents
+{"content":"new turn","customId":"conv_1","containerTag":"user_1"}
+```
+
+```bash v5
+POST /ns/user_1/document?dreaming=dynamic
+{"content":"new turn","id":"conv_1"}
+```
+</CodeGroup>
+
+The response remains an acceptance result with `id` and `status`. 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
+{"documents":["first","second"],"containerTag":"user_1"}
+```
+
+```json v5
+{"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. Namespace, `taskType`, and processing mode apply to the request; document content, ID, context, metadata, grouping, and date stay per item.
+
+Batch results preserve input order. Inspect `success`, `failed`, and every item in `results`; 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 |
+| `fileType`, `mimeType` | Query parameters when inference is insufficient |
+
+The API acknowledges the file after durable acceptance. 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.
+
+### 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 result order and per-item errors.
+- Confirm metadata and grouping remain filterable after processing.
--- a/apps/docs/snippets/api-v5-document-updates.mdx
+++ b/apps/docs/snippets/api-v5-document-updates.mdx
@ -0,0 +1,70 @@
+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 supporting fields | 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
+
+<CodeGroup>
+```bash Legacy
+PATCH /v3/documents/doc_1
+{"content":"corrected source","metadata":{"revision":2}}
+```
+
+```bash v5
+PATCH /ns/user_1/document/doc_1?dreaming=dynamic
+{"content":"corrected source","metadata":{"revision":2}}
+```
+</CodeGroup>
+
+The v5 body accepts any non-empty subset of `content`, `supportingContext`, `metadata`, `group`, or `date`. Supplying `content` makes it the new canonical source; facts supported only by the previous source can disappear after reprocessing.
+
+### Replace a file-backed document
+
+```bash
+POST /ns/user_1/document/file/doc_1?dreaming=dynamic
+Content-Type: multipart/form-data
+
+file=@corrected.pdf
+metadata={"revision":2}
+```
+
+POST requires `file` and replaces the canonical source plus user-controlled metadata, grouping, context, and date. Omitted supporting fields are cleared. Use it when the submitted request is the complete new representation of the file-backed document.
+
+### Partially update a file-backed document
+
+```bash
+PATCH /ns/user_1/document/file/doc_1?dreaming=dynamic
+Content-Type: multipart/form-data
+
+metadata={"reviewed":true}
+```
+
+PATCH changes only supplied fields. Include `file` to replace the source while retaining omitted supporting fields, or omit `file` for metadata-, group-, context-, or date-only changes. `metadata` and `group` are JSON-encoded strings; `supportingContext` and `date` are plain strings.
+
+<Warning>
+  There is no public v5 `PUT /ns/{namespace}/document/file/{id}` operation. Use POST for a complete replacement and PATCH for a partial update.
+</Warning>
+
+### 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 document still processing, a namespace conflict, or a conflicting internal file path can return `409`; retry only after the conflicting operation reaches a terminal state.
+
+### 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.
--- a/apps/docs/snippets/api-v5-filters.mdx
+++ b/apps/docs/snippets/api-v5-filters.mdx
@ -0,0 +1,68 @@
+v5 uses one optional singular `filter` field for search, profiles, and list operations.
+
+### Shape
+
+```ts
+type Filter =
+  | { field: string; operator: "eq" | "neq"; value: string; caseSensitive?: boolean }
+  | { field: string; operator: "eq" | "neq"; value: number | boolean }
+  | { field: string; operator: "gt" | "gte" | "lt" | "lte"; value: number }
+  | { field: string; operator: "contains" | "notContains"; value: string; caseSensitive?: boolean }
+  | { field: string; operator: "arrayContains" | "arrayNotContains"; value: string }
+  | { operator: "and" | "or"; operands: Filter[] };
+```
+
+Fields may contain letters, numbers, `_`, `.`, and `-`. Expressions allow up to five nested levels and 200 operands per logical group.
+
+### Operator mapping
+
+| Legacy condition | v5 predicate |
+| --- | --- |
+| `{ key, value }` | `{ field: key, operator: "eq", value }` |
+| `negate: true` equality | `operator: "neq"` |
+| `filterType: "string_contains"` | `operator: "contains"` |
+| contains + `negate: true` | `operator: "notContains"` |
+| `filterType: "array_contains"` | `operator: "arrayContains"` |
+| array contains + `negate: true` | `operator: "arrayNotContains"` |
+| numeric `=` / numeric `=` + `negate: true` | `eq` / `neq` with a JSON number |
+| numeric `>`, `>=`, `<`, `<=` | `gt`, `gte`, `lt`, `lte` |
+| `AND` / `OR` arrays | lowercase `and` / `or` with `operands` |
+| `ignoreCase: true` | `caseSensitive: false` |
+
+### Before and after
+
+<CodeGroup>
+```json Legacy
+{
+  "AND": [
+    { "key": "category", "value": "research" },
+    { "key": "score", "value": 0.8, "filterType": "numeric", "numericOperator": ">=" }
+  ]
+}
+```
+
+```json v5
+{
+  "operator": "and",
+  "operands": [
+    { "field": "category", "operator": "eq", "value": "research" },
+    { "field": "score", "operator": "gte", "value": 0.8 }
+  ]
+}
+```
+</CodeGroup>
+
+### Deterministic conversion
+
+1. Rename outer `filters` to `filter`.
+2. Recursively replace `AND`/`OR` objects with `{ operator, operands }`.
+3. Rename `key` to `field`.
+4. Convert legacy flags into one explicit operator.
+5. Keep numeric values as JSON numbers rather than numeric strings.
+6. Remove legacy `filterType`, `negate`, `numericOperator`, and `ignoreCase` keys.
+
+### Verification
+
+- Compare result IDs for equality, inequality, contains, numeric, array, nested AND, and nested OR fixtures.
+- Add negative tests: legacy shapes, empty operands, incompatible value types, and unknown keys must return `400`.
+- Confirm omitted `filter` preserves unfiltered behavior.
--- a/apps/docs/snippets/api-v5-memory-forgetting.mdx
+++ b/apps/docs/snippets/api-v5-memory-forgetting.mdx
@ -0,0 +1,67 @@
+v5 scopes forgetting to one namespace and returns the same result envelope for exact and semantic requests.
+
+### Choose exact or semantic forgetting
+
+| Intent | v5 operation |
+| --- | --- |
+| Forget reviewed memory IDs | `DELETE /ns/{namespace}/memories` |
+| Find memories by meaning | `DELETE /ns/{namespace}/memories/semantic` |
+
+### Forget exact IDs
+
+```bash
+DELETE /ns/user_1/memories
+Content-Type: application/json
+
+{"ids":["mem_1","mem_2"]}
+```
+
+Send 1–500 IDs. The response reports successful IDs in `matches` and missing or ineligible IDs in `errors`, so HTTP success does not imply every requested ID changed.
+
+### Preview a semantic request
+
+```bash
+DELETE /ns/user_1/memories/semantic
+Content-Type: application/json
+
+{"query":"outdated home address","dryRun":true}
+```
+
+`dryRun: true` performs selection without changing memory state. `dryRun: false` forgets the memories selected when that request executes.
+
+### Avoid selection drift
+
+```text
+semantic request with dryRun: true
+                |
+                v
+review matches[].id
+                |
+                v
+exact DELETE with reviewed IDs
+```
+
+Use this workflow when a human or policy must approve the exact set. Re-running the semantic request with `dryRun: false` can select a different set if memories changed after preview.
+
+### Read the normalized response
+
+```json
+{
+  "count": 1,
+  "matches": [{ "id": "mem_1", "memory": "Old address" }],
+  "errors": [{ "id": "mem_2", "error": "Memory not found" }]
+}
+```
+
+`count` always equals `matches.length`. Both dry-run and applied semantic requests use this shape; the payload alone does not replace your record of which mode was sent.
+
+### Removed memory-write routes
+
+Direct v4 memory creation and version updates have no v5 replacement. Ingest source material through document routes and update the canonical document when facts change.
+
+### Verification
+
+- Exercise all-success, partial-success, duplicate, unknown, and cross-namespace ID sets.
+- Confirm dry runs leave matched memories recallable.
+- Apply reviewed IDs exactly and confirm normal recall excludes them.
+- Persist the request mode alongside audit logs for semantic operations.
--- a/apps/docs/snippets/api-v5-namespaces.mdx
+++ b/apps/docs/snippets/api-v5-namespaces.mdx
@ -0,0 +1,63 @@
+v5 renames the public isolation boundary from container tag to namespace. Existing values remain valid identifiers; no stored data rename is required.
+
+### Endpoint mapping
+
+| Legacy | v5 |
+| --- | --- |
+| `GET /v3/container-tags/list` | `GET /namespaces` |
+| `GET /v3/container-tags/{tag}` | `GET /ns/{namespace}` |
+| `PATCH /v3/container-tags/{tag}` | `PATCH /ns/{namespace}` |
+| `DELETE /v3/container-tags/{tag}` | `DELETE /ns/{namespace}` |
+| Merge container tags | `DELETE /ns/{source}` with `{ "moveTo": "target" }` |
+
+`GET /ns` is an alias for `GET /namespaces`. Prefer `/namespaces` in new integrations.
+
+### List namespaces
+
+Each entry now exposes `id`, `namespace`, `documentCount`, `memoryCount`, nullable `description`, and `system.createdAt/updatedAt`. Update readers that still expect `containerTag`, flat timestamps, or unbounded internal settings.
+
+### Read and update settings
+
+<CodeGroup>
+```bash Legacy
+PATCH /v3/container-tags/project_alpha
+{"entityContext":"Research project for distributed systems"}
+```
+
+```bash v5
+PATCH /ns/project_alpha
+{"supportingContext":"Research project for distributed systems"}
+```
+</CodeGroup>
+
+The public GET and PATCH shapes contain only `namespace`, `supportingContext`, and lifecycle timestamps. Profile buckets have their own `/profile/buckets` resource and are not namespace settings.
+
+Send `supportingContext: null` to remove existing context. Omitting the field entirely is invalid because PATCH requires at least one supported setting.
+
+### Permanently delete a namespace
+
+```bash
+DELETE /ns/project_alpha
+{}
+```
+
+With no `moveTo`, deletion is synchronous and returns `200` with `deletedDocumentsCount` and `deletedMemoriesCount`. This removes the namespace and its content.
+
+### Move then remove a namespace
+
+```bash
+DELETE /ns/project_alpha
+{"moveTo":"project_archive"}
+```
+
+This returns `202` with `status: "queued"` and `operationId`. The destination must differ from the source. Do not treat acceptance as completed migration.
+
+Legacy merge can accept multiple sources; v5 moves one source per request. Run multi-source migrations sequentially and record each operation independently.
+
+### Verification
+
+- Confirm existing container-tag values resolve unchanged as namespace paths.
+- Compare namespace counts with namespace-scoped document and memory lists.
+- Verify a permanent delete returns final counts while a move returns `202`.
+- Verify restricted callers cannot read or mutate namespaces outside their scope.
+- Verify only organization-authorized callers can change settings or lifecycle.
--- a/apps/docs/snippets/api-v5-organization.mdx
+++ b/apps/docs/snippets/api-v5-organization.mdx
@ -0,0 +1,57 @@
+v5 exposes only the organization-wide context needed to guide memory formation. Internal controls and profile bucket mutation are no longer part of this settings resource.
+
+### Endpoint mapping
+
+| Legacy | v5 |
+| --- | --- |
+| `GET /v3/settings` | `GET /organization` |
+| `PATCH /v3/settings` | `PATCH /organization` |
+| `filterPrompt` | `organizationalContext` |
+
+### Read organization settings
+
+```bash
+GET /organization
+```
+
+```json
+{
+  "organizationalContext": "Acme builds security tools for enterprises",
+  "namespaceCount": 42
+}
+```
+
+Remove readers for legacy settings that are not present in this allowlisted response. `namespaceCount` is informational and cannot be changed through PATCH.
+
+### Update organization context
+
+<CodeGroup>
+```bash Legacy
+PATCH /v3/settings
+{"filterPrompt":"Acme builds security tools for enterprises"}
+```
+
+```bash v5
+PATCH /organization
+{"organizationalContext":"Acme builds security tools for enterprises"}
+```
+</CodeGroup>
+
+The field is exhaustive: the supplied value replaces the existing context. Send `null` to remove it. Empty strings are rejected.
+
+Organization updates require an organization administrator. Do not silently fall back to namespace context when the caller receives `403`.
+
+### Removed public operations
+
+- Organization profile-bucket mutation is not exposed through organization settings.
+- Bucket suggestion is not part of v5.
+- Organization data reset is not part of v5.
+- Namespace-owned profile buckets are managed through `/ns/{namespace}/profile/buckets`.
+
+### Verification
+
+- Compare the v5 context with the legacy `filterPrompt` before cutover.
+- Set, replace, and clear organizational context.
+- Confirm `namespaceCount` agrees with `GET /namespaces` for the same credentials.
+- Verify non-admin callers receive `403` on PATCH.
+- Confirm removed fields are not required by downstream configuration code.
--- a/apps/docs/snippets/api-v5-overview.mdx
+++ b/apps/docs/snippets/api-v5-overview.mdx
@ -0,0 +1,47 @@
+## Migrate by hand
+
+<Warning>
+  This is a breaking API migration. Do not change only the URL: fields moved, search defaults changed, response envelopes changed, and some legacy operations have no v5 replacement.
+</Warning>
+
+The API base URL and bearer keys do not change. v5 application routes are unversioned; [`/v5/reference`](https://api.supermemory.ai/v5/reference) is the interactive v5 reference, not an API path prefix.
+
+## Recommended migration process
+
+<Steps>
+  <Step title="Inventory every legacy call">
+    Search for `/v3/`, `/v4/`, `containerTag`, `containerTags`, `customId`, `entityContext`, `filterByMetadata`, `filters`, and legacy SDK methods.
+  </Step>
+  <Step title="Resolve one namespace per request">
+    Move the legacy `containerTag` into `/ns/{namespace}`. Never infer scope from a document or memory ID, and never send multiple namespaces to one v5 request.
+  </Step>
+  <Step title="Translate requests by domain">
+    Apply [ingestion](./api-v5-document-writes), [updates](./api-v5-document-updates), [content management](./api-v5-document-reads), [search](./api-v5-recall), [profiles](./api-v5-profiles), [forgetting](./api-v5-memory-forgetting), [namespaces](./api-v5-settings), [organization](./api-v5-organization), and [filter](./api-v5-filters) changes independently.
+  </Step>
+  <Step title="Update response readers">
+    Migrate envelopes, attachments, pagination, profile buckets, system fields, and partial-error handling before switching traffic.
+  </Step>
+  <Step title="Verify legacy and v5 side by side">
+    Follow the [verification and rollout guide](./api-v5-rollout). Compare identity and behavior—not raw JSON ordering—and set changed defaults explicitly during rollout.
+  </Step>
+  <Step title="Cut over one domain at a time">
+    Switch traffic, monitor failures and semantic drift, then remove legacy compatibility code only after that domain passes verification.
+  </Step>
+</Steps>
+
+## Endpoint map
+
+| Legacy | v5 |
+| --- | --- |
+| `POST /v3/documents` | `POST /ns/{namespace}/document` |
+| `POST /v3/documents/batch` | `POST /ns/{namespace}/document/batch` |
+| `POST /v3/documents/file` | `POST /ns/{namespace}/document/file` |
+| `GET/PATCH /v3/documents/{id}` | `GET/PATCH /ns/{namespace}/document/{id}` |
+| Single or bulk document delete | `DELETE /ns/{namespace}/document` |
+| Legacy document or memory lists | `POST /ns/{namespace}/list/{type}` |
+| `POST /v3/search` or `/v4/search` | `POST /ns/{namespace}/search` |
+| `POST /v4/profile` | `POST /ns/{namespace}/profile` |
+| `POST /v4/profile/buckets` | `GET /ns/{namespace}/profile/buckets` |
+| Legacy memory forget routes | `DELETE /ns/{namespace}/memories...` |
+| Container-tag settings and lifecycle | `/namespaces` and `/ns/{namespace}` |
+| `GET/PATCH /v3/settings` | `GET/PATCH /organization` |
--- a/apps/docs/snippets/api-v5-profiles.mdx
+++ b/apps/docs/snippets/api-v5-profiles.mdx
@ -0,0 +1,75 @@
+v5 returns a maintained profile directly and gives profile bucket definitions their own namespace-scoped resource.
+
+### Remove search behavior from profile calls
+
+<CodeGroup>
+```bash Legacy
+POST /v4/profile
+{"containerTag":"user_1","q":"work preferences","threshold":0.6,"include":{}}
+```
+
+```bash v5
+POST /ns/user_1/profile
+{"filter":{"field":"region","operator":"eq","value":"us-west"},"buckets":["work"]}
+```
+</CodeGroup>
+
+Remove legacy `q`, `threshold`, and `include`. If the caller needs query-ranked results, issue a separate v5 search request. Move `containerTag` to the path and rename `filters` to singular `filter`.
+
+### Read the v5 profile shape
+
+```json
+{
+  "profile": {
+    "static": ["The user works in design"],
+    "dynamic": ["The user is preparing a launch"],
+    "buckets": { "work": ["Prefers concise project updates"] }
+  }
+}
+```
+
+`static` and `dynamic` are always returned and cannot be disabled. Omit `buckets` in the request to return every effective custom bucket; pass up to 50 names to narrow only the bucket section.
+
+### Read bucket definitions
+
+<CodeGroup>
+```bash Legacy
+POST /v4/profile/buckets
+{"containerTag":"user_1"}
+```
+
+```bash v5
+GET /ns/user_1/profile/buckets
+```
+</CodeGroup>
+
+The response changes from key/description objects to a map:
+
+```json
+{"buckets":{"work":"Professional preferences and ongoing work"}}
+```
+
+### Add or edit namespace buckets
+
+```bash
+PUT /ns/user_1/profile/buckets
+{"buckets":{"work":"Professional preferences and ongoing work"}}
+```
+
+Send one to 50 name-to-description entries. Existing namespace names are updated, new names are added, and omitted namespace buckets remain unchanged.
+
+### Delete namespace buckets
+
+```bash
+DELETE /ns/user_1/profile/buckets
+{"buckets":["work"]}
+```
+
+Names must be unique. Organization-owned buckets can appear in the effective GET response but cannot be changed or removed through namespace PUT or DELETE calls.
+
+### Verification
+
+- Confirm every profile response contains `static`, `dynamic`, and `buckets`.
+- Compare omitted buckets with one-name and multi-name narrowing.
+- Add, edit, and delete a namespace bucket without replacing omitted buckets.
+- Attempt to mutate an inherited organization bucket and expect the documented error.
--- a/apps/docs/snippets/api-v5-rollout.mdx
+++ b/apps/docs/snippets/api-v5-rollout.mdx
@ -0,0 +1,59 @@
+Treat migration as a behavioral comparison, not a raw response snapshot update.
+
+### Build deterministic fixtures
+
+Use an isolated namespace with stable IDs and fixed source content. Include plaintext, URL, file, batch, metadata, grouping, profile facts, related memories, forgotten memories, and empty-result cases.
+
+Record each legacy request, v5 request, expected semantic result, and intentional difference. Never compare generated IDs, signed URLs, timing, or JSON object order unless the contract guarantees them.
+
+### Compare writes
+
+- Repeated POST appends or diffs; PATCH replaces canonical content.
+- Batch outcomes preserve input order and surface partial failures.
+- Metadata-only updates leave source content unchanged.
+- Accepted writes are polled until processing reaches a terminal state.
+
+### Compare reads and recall
+
+- Document attachments are absent when omitted and empty arrays when requested without results.
+- Unified list responses populate only the selected resource array.
+- Search parity uses explicit v4-equivalent mode and threshold before testing v5 defaults.
+- Profiles always contain static, dynamic, and bucket sections.
+
+### Exercise boundaries
+
+| Boundary | Cases |
+| --- | --- |
+| Namespace | Correct, missing, unauthorized, cross-namespace ID |
+| Pagination | First, middle, final, empty, maximum limit |
+| Filters | Every operator, nested AND/OR, invalid type, excessive depth |
+| Deletion | All success, partial success, unknown IDs, semantic dry run |
+| Settings | Admin, non-admin, null removal, invalid empty value |
+
+### Classify differences
+
+```text
+same request intent
+       |
+       +-- same semantic result ------> parity
+       +-- documented v5 difference --> update assertion
+       +-- undocumented difference ----> block cutover
+```
+
+Do not normalize away an undocumented difference. Capture the request pair, namespace, IDs, response status, and minimal response fragments needed to reproduce it.
+
+### Cut over by domain
+
+1. Ship v5 request construction behind a per-domain flag.
+2. Dual-read or shadow-call where side effects allow it.
+3. Switch ingestion, content management, search, profiles, then settings independently.
+4. Monitor validation failures, authorization failures, latency, empty-result rate, and processing failures.
+5. Retain the legacy path until the observation window passes.
+
+### Completion checklist
+
+- No application API call accidentally uses a `/v5` prefix.
+- Unchanged connector routes retain their documented `/v3` paths.
+- No legacy field aliases or response readers remain.
+- Every changed default is either accepted intentionally or passed explicitly.
+- Rollback restores the previous caller without requiring data repair.
--- a/apps/docs/snippets/api-v5-sdks.mdx
+++ b/apps/docs/snippets/api-v5-sdks.mdx
@ -0,0 +1,42 @@
+Check which client you call the API through before you translate requests. Not every client supports v5 yet.
+
+| Client | v5 support | What to do |
+| --- | --- | --- |
+| TypeScript SDK (`supermemory` on npm) | `5.0.0-rc.5` and later | Install `supermemory@rc` and follow the SDK changes below. Release candidates before `rc.5` still use the v3/v4 surface. |
+| Python SDK (`supermemory` on PyPI) | Not yet | The 3.x SDK calls v3/v4. Call v5 over HTTP as shown in this guide, or keep the SDK on v3/v4 until a v5 release ships. |
+| `@supermemory/tools` (AI SDK, OpenAI and agent integrations) | Not yet | These call v3/v4 (`/v4/profile`, `/v4/conversations`). No change needed today. |
+| CLI (`npx supermemory`) and `supermemory local` | Unchanged | The CLI calls v3/v4 directly and keeps working. No change needed. |
+
+### TypeScript SDK changes
+
+The v5 SDK scopes every content call to one `namespace` and moves the payload under `body`:
+
+```ts
+import Supermemory from "supermemory";
+
+const client = new Supermemory(); // reads SUPERMEMORY_API_KEY, as before
+
+// v4
+await client.add({ content: "Alex prefers morning meetings.", containerTag: "user_alex" });
+
+// v5
+await client.add({
+  namespace: "user_alex",
+  body: { content: "Alex prefers morning meetings." },
+});
+```
+
+| v4 | v5 |
+| --- | --- |
+| `client.search.memories({ q, containerTag })` | `client.search({ namespace, body: { query } })` |
+| `client.profile({ containerTag, q })` | `client.profile({ namespace })`, plus `client.search` in parallel if you need results |
+| `client.documents.list(...)`, `client.memories.list(...)` | `client.list({ namespace, type })` |
+| `client.containerTags.*` | `client.namespaces.*` |
+| `client.settings.{get, update}` | `client.organization.{get, update}` |
+| Errors per status (`RateLimitError`, …) | One `SupermemoryError`; branch on `statusCode` |
+| Retries on by default | Retries are opt-in through `retryConfig` |
+| `timeout` | `timeoutMs` |
+
+The v5 SDK drops methods that have no v5 endpoint: `connections`, `conversations.add`, `settings.{reset, suggestBuckets}`, `containerTags.{merge, mergeStatus}`, `memories.{add, updateMemory}`, and `documents.{listProcessing, chunks, fileUrl, search}`. Stay on `supermemory@4` for those calls.
+
+The full method map is in the SDK's [migration guide](https://github.com/supermemoryai/sdk-ts/blob/main/MIGRATION.md).
--- a/apps/docs/snippets/api-v5-search.mdx
+++ b/apps/docs/snippets/api-v5-search.mdx
@ -0,0 +1,75 @@
+v5 searches one namespace, defaults to hybrid recall, and moves ranking controls into a typed request body.
+
+### Request mapping
+
+| Legacy | v5 |
+| --- | --- |
+| `containerTag` | `/ns/{namespace}` |
+| body `q` | body `query` |
+| body `limit` | query `limit` |
+| `searchMode: "documents"` | `searchMode=chunks` |
+| omitted search mode | `searchMode=hybrid` |
+| `filters` | singular `filter` |
+| `include.documents` or `.summaries` | `attach.documents` |
+| `include.relatedMemories` | `attach.related` |
+| `include.forgottenMemories` | `attach.forgotten` |
+| `rerank: true` / `aggregate: true` | `rerank: "order"` / `"aggregate"` |
+
+<CodeGroup>
+```bash Legacy
+POST /v4/search
+{"q":"What did the user decide?","containerTag":"user_1","limit":10,"searchMode":"memories"}
+```
+
+```bash v5
+POST /ns/user_1/search?limit=10&searchMode=memories
+{"query":"What did the user decide?","threshold":0.6,"rewriteQuery":false}
+```
+</CodeGroup>
+
+### Changed defaults
+
+| Setting | v4 | v5 |
+| --- | --- | --- |
+| Search mode | `memories` | `hybrid` |
+| Similarity threshold | `0.6` | `0.3` |
+| Reranking | Disabled | `rerank: "none"` |
+| Query rewriting | Disabled | `false` |
+
+Set mode and threshold explicitly while comparing versions. After parity testing, remove them only if you want the broader v5 hybrid defaults.
+
+### Search modes
+
+| Mode | Returns |
+| --- | --- |
+| `memories` | Formed memories only |
+| `chunks` | Source chunks only |
+| `hybrid` | Both result types in one ranked list |
+
+Legacy `include.chunks` has no v5 equivalent. Choose `chunks` or `hybrid` instead.
+
+### Attachments and ranking
+
+- `attach.documents` adds the most relevant source document to each result.
+- `attach.related` adds parent, child, and sibling memories.
+- `attach.forgotten` allows forgotten memories in related context; it does not make them primary results.
+- `rerank` accepts `none`, `order`, or `aggregate`; `rewriteQuery` controls retrieval-oriented query rewriting.
+
+### Response mapping
+
+| Legacy reader | v5 reader |
+| --- | --- |
+| Result array | `results` |
+| Timing | `searchTime` |
+| Source expansion | `result.included.document` |
+| Related context | `result.included.related.{parents,children,siblings}` |
+| Lifecycle fields | `result.system` |
+
+Each primary result contains either `memory`, `chunk`, or both only if the contract allows it. Branch on field presence rather than assuming one result shape.
+
+### Verification
+
+- Compare IDs using explicit v4-equivalent defaults, then test v5 hybrid behavior separately.
+- Cover all three modes, thresholds at `0` and `1`, each rerank option, and query rewriting.
+- Cover every attachment alone and in combination, including empty attachments.
+- Verify filters, namespace isolation, result limits, and invalid body/query placement.
--- a/apps/docs/v5/api-reference/content-management.mdx
+++ b/apps/docs/v5/api-reference/content-management.mdx
@ -2,7 +2,7 @@
 title: "Content management"
 sidebarTitle: "Overview"
 description: "Retrieve, list, and remove documents, chunks, and memories"
-icon: "file-text"
+icon: "book-open"
 ---

 Inspect the context stored in a namespace and remove information that should no longer be used. Retrieve a document with its derived context, page through any resource type, or forget documents and memories precisely.
--- a/apps/docs/v5/api-reference/ingest.mdx
+++ b/apps/docs/v5/api-reference/ingest.mdx
@ -2,7 +2,7 @@
 title: "Ingest"
 sidebarTitle: "Overview"
 description: "Turn source content into searchable memory and keep it current"
-icon: "download"
+icon: "book-open"
 ---

 Ingestion gives Supermemory the source material it uses to build searchable context and memories. Add new content or update an existing source without creating a disconnected copy.
--- a/apps/docs/v5/api-reference/namespaces.mdx
+++ b/apps/docs/v5/api-reference/namespaces.mdx
@ -2,7 +2,7 @@
 title: "Namespaces"
 sidebarTitle: "Overview"
 description: "Keep memory isolated, understandable, and easy to reorganize"
-icon: "layers"
+icon: "book-open"
 ---

 | Operation | Purpose |
--- a/apps/docs/v5/api-reference/organization.mdx
+++ b/apps/docs/v5/api-reference/organization.mdx
@ -2,7 +2,7 @@
 title: "Organization"
 sidebarTitle: "Overview"
 description: "Give every namespace a shared understanding of your organization"
-icon: "building"
+icon: "book-open"
 ---

 | Operation | Purpose |
@ -10,6 +10,6 @@ icon: "building"
 | `GET /organization` | See shared context and your namespace footprint |
 | `PATCH /organization` | Improve the context guiding memory across the organization |

-The public V5 shape intentionally excludes profile buckets, bucket suggestions, reset controls, and internal settings.
+The public v5 shape intentionally excludes profile buckets, bucket suggestions, reset controls, and internal settings.

 See [namespace and settings migration](/migration/api-v5-settings).
--- a/apps/docs/v5/api-reference/overview.mdx
+++ b/apps/docs/v5/api-reference/overview.mdx
@ -2,10 +2,10 @@
 title: "API reference"
 sidebarTitle: "Overview"
 description: "Documents, search, profiles, lists, memories, namespaces, and organization settings in the latest Supermemory API"
-icon: "book-open"
+icon: "unplug"
 ---

-V5 makes namespace scope explicit in the URL and consolidates overlapping legacy operations.
+v5 makes namespace scope explicit in the URL and consolidates overlapping legacy operations.

 ```text
 https://api.supermemory.ai
@ -18,11 +18,11 @@ https://api.supermemory.ai
  /organization
 ```

-Use `/v5/reference` for the stable V5 reference. `/reference` always points to the latest public version.
+Use the [v5 reference](https://api.supermemory.ai/v5/reference) for the stable v5 API. [`/reference`](https://api.supermemory.ai/reference) always points to the latest public version.

 <CardGroup cols={2}>
-  <Card title="Migrate to V5" icon="arrow-up-right" href="/migration/api-v5">
-    Translate every V3/V4 request and response deterministically.
+  <Card title="Migrate to v5" icon="arrow-up-right" href="/migration/api-v5">
+    Translate every v3/v4 request and response deterministically.
  </Card>
  <Card title="Authentication" icon="key" href="/authentication">
    Authenticate with the same bearer API keys used by legacy endpoints.
--- a/apps/docs/v5/api-reference/search.mdx
+++ b/apps/docs/v5/api-reference/search.mdx
@ -2,7 +2,7 @@
 title: "Search"
 sidebarTitle: "Overview"
 description: "Recall the most relevant memories and source context"
-icon: "search"
+icon: "book-open"
 ---

 `POST /ns/{namespace}/search` recalls the most useful memories and source chunks for a query. Hybrid search combines both by default; use `searchMode=memories` or `searchMode=chunks` when your experience needs one result type.