From 3b847130971eaf47499b83cb44862d9a2aff3e9c Mon Sep 17 00:00:00 2001 From: sohamd22 <85427822+sohamd22@users.noreply.github.com> Date: Tue, 6 Oct 2026 16:48:36 +0000 Subject: [PATCH] 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. --- apps/docs/api-reference/overview.mdx | 4 + apps/docs/docs.json | 25 ++++++- apps/docs/migration/api-v5-document-reads.mdx | 11 +++ .../migration/api-v5-document-updates.mdx | 11 +++ .../docs/migration/api-v5-document-writes.mdx | 11 +++ apps/docs/migration/api-v5-filters.mdx | 11 +++ .../migration/api-v5-memory-forgetting.mdx | 11 +++ apps/docs/migration/api-v5-organization.mdx | 11 +++ apps/docs/migration/api-v5-profiles.mdx | 11 +++ apps/docs/migration/api-v5-recall.mdx | 11 +++ apps/docs/migration/api-v5-rollout.mdx | 11 +++ apps/docs/migration/api-v5-settings.mdx | 11 +++ apps/docs/migration/api-v5.mdx | 71 ++++++++++++++++++ apps/docs/package.json | 2 +- apps/docs/scripts/dev.sh | 17 +++++ apps/docs/snippets/api-v5-agent-prompt.mdx | 7 ++ apps/docs/snippets/api-v5-completion.mdx | 9 +++ .../snippets/api-v5-content-management.mdx | 73 ++++++++++++++++++ .../snippets/api-v5-document-ingestion.mdx | 70 +++++++++++++++++ .../docs/snippets/api-v5-document-updates.mdx | 70 +++++++++++++++++ apps/docs/snippets/api-v5-filters.mdx | 68 +++++++++++++++++ .../snippets/api-v5-memory-forgetting.mdx | 67 +++++++++++++++++ apps/docs/snippets/api-v5-namespaces.mdx | 63 ++++++++++++++++ apps/docs/snippets/api-v5-organization.mdx | 57 ++++++++++++++ apps/docs/snippets/api-v5-overview.mdx | 47 ++++++++++++ apps/docs/snippets/api-v5-profiles.mdx | 75 +++++++++++++++++++ apps/docs/snippets/api-v5-rollout.mdx | 59 +++++++++++++++ apps/docs/snippets/api-v5-sdks.mdx | 42 +++++++++++ apps/docs/snippets/api-v5-search.mdx | 75 +++++++++++++++++++ .../v5/api-reference/content-management.mdx | 2 +- apps/docs/v5/api-reference/ingest.mdx | 2 +- apps/docs/v5/api-reference/namespaces.mdx | 2 +- apps/docs/v5/api-reference/organization.mdx | 4 +- apps/docs/v5/api-reference/overview.mdx | 10 +-- apps/docs/v5/api-reference/search.mdx | 2 +- 35 files changed, 1019 insertions(+), 14 deletions(-) create mode 100644 apps/docs/migration/api-v5-document-reads.mdx create mode 100644 apps/docs/migration/api-v5-document-updates.mdx create mode 100644 apps/docs/migration/api-v5-document-writes.mdx create mode 100644 apps/docs/migration/api-v5-filters.mdx create mode 100644 apps/docs/migration/api-v5-memory-forgetting.mdx create mode 100644 apps/docs/migration/api-v5-organization.mdx create mode 100644 apps/docs/migration/api-v5-profiles.mdx create mode 100644 apps/docs/migration/api-v5-recall.mdx create mode 100644 apps/docs/migration/api-v5-rollout.mdx create mode 100644 apps/docs/migration/api-v5-settings.mdx create mode 100644 apps/docs/migration/api-v5.mdx create mode 100644 apps/docs/scripts/dev.sh create mode 100644 apps/docs/snippets/api-v5-agent-prompt.mdx create mode 100644 apps/docs/snippets/api-v5-completion.mdx create mode 100644 apps/docs/snippets/api-v5-content-management.mdx create mode 100644 apps/docs/snippets/api-v5-document-ingestion.mdx create mode 100644 apps/docs/snippets/api-v5-document-updates.mdx create mode 100644 apps/docs/snippets/api-v5-filters.mdx create mode 100644 apps/docs/snippets/api-v5-memory-forgetting.mdx create mode 100644 apps/docs/snippets/api-v5-namespaces.mdx create mode 100644 apps/docs/snippets/api-v5-organization.mdx create mode 100644 apps/docs/snippets/api-v5-overview.mdx create mode 100644 apps/docs/snippets/api-v5-profiles.mdx create mode 100644 apps/docs/snippets/api-v5-rollout.mdx create mode 100644 apps/docs/snippets/api-v5-sdks.mdx create mode 100644 apps/docs/snippets/api-v5-search.mdx diff --git a/apps/docs/api-reference/overview.mdx b/apps/docs/api-reference/overview.mdx index 651ec806..f8fdfcf3 100644 --- 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" --- + +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. + + 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). diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 27dd7724..98756bad 100644 --- 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", diff --git a/apps/docs/migration/api-v5-document-reads.mdx b/apps/docs/migration/api-v5-document-reads.mdx new file mode 100644 index 00000000..57fc77b2 --- /dev/null +++ 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 + + diff --git a/apps/docs/migration/api-v5-document-updates.mdx b/apps/docs/migration/api-v5-document-updates.mdx new file mode 100644 index 00000000..148f2779 --- /dev/null +++ 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 + + diff --git a/apps/docs/migration/api-v5-document-writes.mdx b/apps/docs/migration/api-v5-document-writes.mdx new file mode 100644 index 00000000..6a8b5520 --- /dev/null +++ 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 + + diff --git a/apps/docs/migration/api-v5-filters.mdx b/apps/docs/migration/api-v5-filters.mdx new file mode 100644 index 00000000..288847f5 --- /dev/null +++ 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 + + diff --git a/apps/docs/migration/api-v5-memory-forgetting.mdx b/apps/docs/migration/api-v5-memory-forgetting.mdx new file mode 100644 index 00000000..3ddde55a --- /dev/null +++ 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 + + diff --git a/apps/docs/migration/api-v5-organization.mdx b/apps/docs/migration/api-v5-organization.mdx new file mode 100644 index 00000000..54a1f91d --- /dev/null +++ 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 + + diff --git a/apps/docs/migration/api-v5-profiles.mdx b/apps/docs/migration/api-v5-profiles.mdx new file mode 100644 index 00000000..5ec5e16b --- /dev/null +++ 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 + + diff --git a/apps/docs/migration/api-v5-recall.mdx b/apps/docs/migration/api-v5-recall.mdx new file mode 100644 index 00000000..f3c024ba --- /dev/null +++ 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 + + diff --git a/apps/docs/migration/api-v5-rollout.mdx b/apps/docs/migration/api-v5-rollout.mdx new file mode 100644 index 00000000..a90d005b --- /dev/null +++ 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 + + diff --git a/apps/docs/migration/api-v5-settings.mdx b/apps/docs/migration/api-v5-settings.mdx new file mode 100644 index 00000000..a90305a1 --- /dev/null +++ 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 + + diff --git a/apps/docs/migration/api-v5.mdx b/apps/docs/migration/api-v5.mdx new file mode 100644 index 00000000..4c19cdd5 --- /dev/null +++ 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"; + + + + + +## SDKs, tools and the CLI + + + +## Document ingestion + + + +## Document updates + + + +## Content management + + + +## Search + + + +## Profiles and buckets + + + +## Memory forgetting + + + +## Namespaces + + + +## Organization settings + + + +## Typed filters + + + +## Verification and rollout + + + + diff --git a/apps/docs/package.json b/apps/docs/package.json index 957c64bc..eaf23a97 100644 --- 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", diff --git a/apps/docs/scripts/dev.sh b/apps/docs/scripts/dev.sh new file mode 100644 index 00000000..9e56ed22 --- /dev/null +++ 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" diff --git a/apps/docs/snippets/api-v5-agent-prompt.mdx b/apps/docs/snippets/api-v5-agent-prompt.mdx new file mode 100644 index 00000000..8f431542 --- /dev/null +++ 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. +``` diff --git a/apps/docs/snippets/api-v5-completion.mdx b/apps/docs/snippets/api-v5-completion.mdx new file mode 100644 index 00000000..1e8895e8 --- /dev/null +++ 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. diff --git a/apps/docs/snippets/api-v5-content-management.mdx b/apps/docs/snippets/api-v5-content-management.mdx new file mode 100644 index 00000000..04e8ae4b --- /dev/null +++ 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 + + +```bash Legacy +GET /v3/documents/{id} +GET /v3/documents/{id}/chunks +``` + +```bash v5 +GET /ns/{namespace}/document/{id}?attach=chunks&attach=memories +``` + + +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 + + +```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 +{} +``` + + +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 + + +```bash Legacy +DELETE /v3/documents/{id} +DELETE /v3/documents/bulk +``` + +```bash v5 +DELETE /ns/{namespace}/document +{"ids":["doc_1","external_id_2"]} +``` + + +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. diff --git a/apps/docs/snippets/api-v5-document-ingestion.mdx b/apps/docs/snippets/api-v5-document-ingestion.mdx new file mode 100644 index 00000000..79a9e731 --- /dev/null +++ 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 + + +```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"} +``` + + +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 + + +```json Legacy +{"documents":["first","second"],"containerTag":"user_1"} +``` + +```json v5 +{"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. 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. diff --git a/apps/docs/snippets/api-v5-document-updates.mdx b/apps/docs/snippets/api-v5-document-updates.mdx new file mode 100644 index 00000000..5f9a3192 --- /dev/null +++ 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 + + +```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}} +``` + + +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. + + + There is no public v5 `PUT /ns/{namespace}/document/file/{id}` operation. Use POST for a complete replacement and PATCH for a partial update. + + +### 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. diff --git a/apps/docs/snippets/api-v5-filters.mdx b/apps/docs/snippets/api-v5-filters.mdx new file mode 100644 index 00000000..016aee94 --- /dev/null +++ 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 + + +```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 } + ] +} +``` + + +### 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. diff --git a/apps/docs/snippets/api-v5-memory-forgetting.mdx b/apps/docs/snippets/api-v5-memory-forgetting.mdx new file mode 100644 index 00000000..30b266a0 --- /dev/null +++ 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. diff --git a/apps/docs/snippets/api-v5-namespaces.mdx b/apps/docs/snippets/api-v5-namespaces.mdx new file mode 100644 index 00000000..0fdde3a7 --- /dev/null +++ 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 + + +```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"} +``` + + +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. diff --git a/apps/docs/snippets/api-v5-organization.mdx b/apps/docs/snippets/api-v5-organization.mdx new file mode 100644 index 00000000..db220fc8 --- /dev/null +++ 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 + + +```bash Legacy +PATCH /v3/settings +{"filterPrompt":"Acme builds security tools for enterprises"} +``` + +```bash v5 +PATCH /organization +{"organizationalContext":"Acme builds security tools for enterprises"} +``` + + +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. diff --git a/apps/docs/snippets/api-v5-overview.mdx b/apps/docs/snippets/api-v5-overview.mdx new file mode 100644 index 00000000..7d8b6743 --- /dev/null +++ b/apps/docs/snippets/api-v5-overview.mdx @@ -0,0 +1,47 @@ +## Migrate by hand + + + 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. + + +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 + + + + Search for `/v3/`, `/v4/`, `containerTag`, `containerTags`, `customId`, `entityContext`, `filterByMetadata`, `filters`, and legacy SDK methods. + + + 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. + + + 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. + + + Migrate envelopes, attachments, pagination, profile buckets, system fields, and partial-error handling before switching traffic. + + + Follow the [verification and rollout guide](./api-v5-rollout). Compare identity and behavior—not raw JSON ordering—and set changed defaults explicitly during rollout. + + + Switch traffic, monitor failures and semantic drift, then remove legacy compatibility code only after that domain passes verification. + + + +## 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` | diff --git a/apps/docs/snippets/api-v5-profiles.mdx b/apps/docs/snippets/api-v5-profiles.mdx new file mode 100644 index 00000000..225889f7 --- /dev/null +++ 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 + + +```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"]} +``` + + +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 + + +```bash Legacy +POST /v4/profile/buckets +{"containerTag":"user_1"} +``` + +```bash v5 +GET /ns/user_1/profile/buckets +``` + + +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. diff --git a/apps/docs/snippets/api-v5-rollout.mdx b/apps/docs/snippets/api-v5-rollout.mdx new file mode 100644 index 00000000..35e05f64 --- /dev/null +++ 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. diff --git a/apps/docs/snippets/api-v5-sdks.mdx b/apps/docs/snippets/api-v5-sdks.mdx new file mode 100644 index 00000000..c8dc8a85 --- /dev/null +++ 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). diff --git a/apps/docs/snippets/api-v5-search.mdx b/apps/docs/snippets/api-v5-search.mdx new file mode 100644 index 00000000..2ba00d86 --- /dev/null +++ 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"` | + + +```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} +``` + + +### 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. diff --git a/apps/docs/v5/api-reference/content-management.mdx b/apps/docs/v5/api-reference/content-management.mdx index 615bfc8d..9b225ee8 100644 --- 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. diff --git a/apps/docs/v5/api-reference/ingest.mdx b/apps/docs/v5/api-reference/ingest.mdx index dddbe5b2..6c8ca8c4 100644 --- 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. diff --git a/apps/docs/v5/api-reference/namespaces.mdx b/apps/docs/v5/api-reference/namespaces.mdx index 3c5324b1..6aa7f2aa 100644 --- 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 | diff --git a/apps/docs/v5/api-reference/organization.mdx b/apps/docs/v5/api-reference/organization.mdx index db00a64a..64f28220 100644 --- 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). diff --git a/apps/docs/v5/api-reference/overview.mdx b/apps/docs/v5/api-reference/overview.mdx index f8e54e1c..7d3dfa1f 100644 --- 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. - - Translate every V3/V4 request and response deterministically. + + Translate every v3/v4 request and response deterministically. Authenticate with the same bearer API keys used by legacy endpoints. diff --git a/apps/docs/v5/api-reference/search.mdx b/apps/docs/v5/api-reference/search.mdx index f7f556a7..9532fc1a 100644 --- 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.