scriptoriumadmin/supermemory
1
0
Fork 0
mirror of https://github.com/supermemoryai/supermemory.git synced 2026-10-10 03:28:14 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs(api): deprecation banner, agent prompt first, legacy callout, v5 overview icons

Browse source
This commit is contained in:
Mahesh Sanikommu 2026-09-28 19:29:58 -07:00
parent e8561ff714
commit 4d6fc3a9a2
11 changed files with 36 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
apps/docs/api-reference/overview.mdx
View file

@ -4,6 +4,10 @@ description: "Interactive reference for the Supermemory HTTP API — ingest, sea
icon: "unplug"
---
<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).

8
apps/docs/docs.json
View file

@ -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",

7
apps/docs/snippets/api-v5-agent-prompt.mdx Normal file
View file

@ -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.
```

10
apps/docs/snippets/api-v5-completion.mdx
View file

@ -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.

12
apps/docs/snippets/api-v5-overview.mdx
View file

@ -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
<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.
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` 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.
</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.
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.
@ -21,7 +21,7 @@ The API base URL and bearer keys do not change. V5 application routes are unvers
<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">
<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">
@ -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` |

2
apps/docs/v5/api-reference/content-management.mdx
View file

@ -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.

2
apps/docs/v5/api-reference/ingest.mdx
View file

@ -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.

2
apps/docs/v5/api-reference/namespaces.mdx
View file

@ -2,7 +2,7 @@
title: "Namespaces"
sidebarTitle: "Overview"
description: "Keep memory isolated, understandable, and easy to reorganize"
icon: "layers"
icon: "book-open"
---
| Operation | Purpose |

4
apps/docs/v5/api-reference/organization.mdx
View file

@ -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).

10
apps/docs/v5/api-reference/overview.mdx
View file

@ -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.
<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.

2
apps/docs/v5/api-reference/search.mdx
View file

@ -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.