From 4d6fc3a9a26b0170cdf20abc8a9058d0013173c2 Mon Sep 17 00:00:00 2001 From: Mahesh Sanikommu Date: Mon, 28 Sep 2026 19:29:58 -0700 Subject: [PATCH] docs(api): deprecation banner, agent prompt first, legacy callout, v5 overview icons --- apps/docs/api-reference/overview.mdx | 4 ++++ apps/docs/docs.json | 8 ++++++-- apps/docs/snippets/api-v5-agent-prompt.mdx | 7 +++++++ apps/docs/snippets/api-v5-completion.mdx | 10 ++-------- apps/docs/snippets/api-v5-overview.mdx | 12 ++++++------ apps/docs/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 +- 11 files changed, 36 insertions(+), 27 deletions(-) create mode 100644 apps/docs/snippets/api-v5-agent-prompt.mdx diff --git a/apps/docs/api-reference/overview.mdx b/apps/docs/api-reference/overview.mdx index 776eb5fc..720f51e2 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, sea icon: "unplug" --- + +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 d24b1007..3de56bb4 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", @@ -280,7 +284,7 @@ "icon": "unplug", "versions": [ { - "version": "Legacy (V3, V4)", + "version": "Legacy (v3, v4)", "openapi": "https://api.supermemory.ai/v4/openapi", "pages": [ "api-reference/overview", @@ -378,7 +382,7 @@ ] }, { - "version": "Latest (V5)", + "version": "Latest (v5)", "default": true, "openapi": { "source": "https://api.supermemory.ai/v5/openapi", 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 index 1d0f13c2..87a37330 100644 --- a/apps/docs/snippets/api-v5-completion.mdx +++ b/apps/docs/snippets/api-v5-completion.mdx @@ -1,13 +1,7 @@ -## Agent migration prompt - -```text -Migrate this repository from Supermemory V3/V4 to V5. Start with a checklist of every legacy call site. Follow the linked domain guides, use one explicit namespace per request, preserve changed defaults explicitly during rollout, update response readers, and add side-by-side contract tests. Do not add /v5 to application routes or rewrite unchanged connector routes. Report operations with no V5 replacement instead of inventing substitutes. -``` - ## 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. +- Organization bucket suggestion and organization reset: not part of the v5 public surface. - Connector routes that still use `/v3`: unchanged; do not rewrite them. -Use `/v5/reference` for the stable V5 reference. `/reference` always points to the latest public version. +Use `/v5/reference` for the stable v5 reference. `/reference` always points to the latest public version. diff --git a/apps/docs/snippets/api-v5-overview.mdx b/apps/docs/snippets/api-v5-overview.mdx index 7e0efad9..6bc741e6 100644 --- a/apps/docs/snippets/api-v5-overview.mdx +++ b/apps/docs/snippets/api-v5-overview.mdx @@ -1,10 +1,10 @@ -V5 keeps the core ingestion and recall workflows while making scope explicit, consolidating overlapping routes, and tightening request and response types. +## 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. + 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` identifies the documentation version, not an API path prefix. +The API base URL and bearer keys do not change. v5 application routes are unversioned; `/v5/reference` identifies the documentation version, not an API path prefix. ## Recommended migration process @@ -13,7 +13,7 @@ The API base URL and bearer keys do not change. V5 application routes are unvers 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. + 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. @@ -21,7 +21,7 @@ The API base URL and bearer keys do not change. V5 application routes are unvers 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. @@ -31,7 +31,7 @@ The API base URL and bearer keys do not change. V5 application routes are unvers ## Endpoint map -| Legacy | V5 | +| Legacy | v5 | | --- | --- | | `POST /v3/documents` | `POST /ns/{namespace}/document` | | `POST /v3/documents/batch` | `POST /ns/{namespace}/document/batch` | 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..94b79278 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 `/v5/reference` for the stable v5 reference. `/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.