From f55fe00e32ec72bd3a493303a62270004e991d33 Mon Sep 17 00:00:00 2001 From: Soham Daga Date: Sat, 19 Sep 2026 21:45:55 -0700 Subject: [PATCH] docs(api): add versioned V5 API reference ## Stack context This is the first PR in the V5 documentation stack. The migration guide and local-development wrapper build on it. ## What and why Add Legacy and Latest versions to the API Reference navigation, organize all V5 operations by user workflow, and introduce concise overview pages for each domain. The Latest reference consumes the authoritative `/v5/openapi` document published by the Mono API stack. ```mermaid flowchart LR Legacy[Legacy V3/V4 OpenAPI] --> Selector[Reference version selector] V5[V5 OpenAPI] --> Selector Selector --> Pages[Version-specific endpoint pages] ``` The `GET /ns` compatibility alias remains in the OpenAPI document but is intentionally omitted from navigation in favor of `GET /namespaces`. ## Validation - Parsed `docs.json` successfully with `jq`. - Compared navigation against the generated V5 schema: 22 displayed operations, 23 schema operations, with only `GET /ns` intentionally omitted. - Mintlify build validation passed against the local generated V5 OpenAPI snapshot. ## Deployment dependency The committed source is `https://api.supermemory.ai/v5/openapi`, which returns 404 until Mono PR #3306 and its API stack are deployed. Merge this PR after that endpoint is live. --- apps/docs/docs.json | 253 ++++++++++++------ .../v5/api-reference/content-management.mdx | 18 ++ apps/docs/v5/api-reference/ingest.mdx | 21 ++ apps/docs/v5/api-reference/namespaces.mdx | 17 ++ apps/docs/v5/api-reference/organization.mdx | 15 ++ apps/docs/v5/api-reference/overview.mdx | 30 +++ apps/docs/v5/api-reference/profiles.mdx | 17 ++ apps/docs/v5/api-reference/search.mdx | 12 + 8 files changed, 297 insertions(+), 86 deletions(-) create mode 100644 apps/docs/v5/api-reference/content-management.mdx create mode 100644 apps/docs/v5/api-reference/ingest.mdx create mode 100644 apps/docs/v5/api-reference/namespaces.mdx create mode 100644 apps/docs/v5/api-reference/organization.mdx create mode 100644 apps/docs/v5/api-reference/overview.mdx create mode 100644 apps/docs/v5/api-reference/profiles.mdx create mode 100644 apps/docs/v5/api-reference/search.mdx diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 0d41141c..6ebd1414 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -261,98 +261,179 @@ { "anchor": "API Reference", "icon": "unplug", - "openapi": "https://api.supermemory.ai/v4/openapi", - "pages": [ - "api-reference/overview", - "authentication", + "versions": [ { - "group": "Ingest", - "icon": "download", + "version": "Legacy (V3, V4)", + "openapi": "https://api.supermemory.ai/v4/openapi", "pages": [ - "api-reference/ingest", - "POST /v3/documents", - "POST /v3/documents/file", - "POST /v3/documents/batch", - "POST /v4/conversations", - "GET /v3/documents/{id}" + "api-reference/overview", + "authentication", + { + "group": "Ingest", + "icon": "download", + "pages": [ + "api-reference/ingest", + "POST /v3/documents", + "POST /v3/documents/file", + "POST /v3/documents/batch", + "POST /v4/conversations", + "GET /v3/documents/{id}" + ] + }, + { + "group": "Recall", + "icon": "search", + "pages": [ + "api-reference/search", + "POST /v4/search", + "POST /v3/search", + "api-reference/profiles", + "POST /v4/profile", + "POST /v4/profile/buckets" + ] + }, + { + "group": "Documents", + "icon": "file-text", + "pages": [ + "api-reference/documents", + "POST /v3/documents/list", + "GET /v3/documents/processing", + "PATCH /v3/documents/{id}", + "DELETE /v3/documents/{id}", + "DELETE /v3/documents/bulk", + "GET /v3/documents/{id}/chunks", + "GET /v3/documents/{id}/file-url" + ] + }, + { + "group": "Memories", + "icon": "database", + "pages": [ + "api-reference/memories", + "POST /v4/memories", + "POST /v4/memories/list", + "PATCH /v4/memories", + "DELETE /v4/memories", + "POST /v4/memories/forget-matching" + ] + }, + { + "group": "Container tags", + "icon": "tags", + "pages": [ + "api-reference/container-tags", + "GET /v3/container-tags/{containerTag}", + "PATCH /v3/container-tags/{containerTag}", + "DELETE /v3/container-tags/{containerTag}", + "POST /v3/container-tags/merge", + "GET /v3/container-tags/merge/{mergeId}" + ] + }, + { + "group": "Connections", + "icon": "plug", + "pages": [ + "api-reference/connections", + "POST /v3/connections/{provider}", + "POST /v3/connections/list", + "GET /v3/connections/{connectionId}", + "POST /v3/connections/{connectionId}/configure", + "GET /v3/connections/{connectionId}/resources", + "POST /v3/connections/{provider}/import", + "POST /v3/connections/{provider}/documents", + "POST /v3/connections/{provider}/connection", + "DELETE /v3/connections/{connectionId}", + "DELETE /v3/connections/{provider}" + ] + }, + { + "group": "Settings", + "icon": "settings", + "pages": [ + "api-reference/settings", + "GET /v3/settings", + "PATCH /v3/settings", + "POST /v3/settings/suggest-buckets", + "POST /v3/settings/reset" + ] + } ] }, { - "group": "Recall", - "icon": "search", + "version": "Latest (V5)", + "default": true, + "openapi": { + "source": "https://api.supermemory.ai/v5/openapi", + "directory": "v5/api-reference" + }, "pages": [ - "api-reference/search", - "POST /v4/search", - "POST /v3/search", - "api-reference/profiles", - "POST /v4/profile", - "POST /v4/profile/buckets" - ] - }, - { - "group": "Documents", - "icon": "file-text", - "pages": [ - "api-reference/documents", - "POST /v3/documents/list", - "GET /v3/documents/processing", - "PATCH /v3/documents/{id}", - "DELETE /v3/documents/{id}", - "DELETE /v3/documents/bulk", - "GET /v3/documents/{id}/chunks", - "GET /v3/documents/{id}/file-url" - ] - }, - { - "group": "Memories", - "icon": "database", - "pages": [ - "api-reference/memories", - "POST /v4/memories", - "POST /v4/memories/list", - "PATCH /v4/memories", - "DELETE /v4/memories", - "POST /v4/memories/forget-matching" - ] - }, - { - "group": "Container tags", - "icon": "tags", - "pages": [ - "api-reference/container-tags", - "GET /v3/container-tags/{containerTag}", - "PATCH /v3/container-tags/{containerTag}", - "DELETE /v3/container-tags/{containerTag}", - "POST /v3/container-tags/merge", - "GET /v3/container-tags/merge/{mergeId}" - ] - }, - { - "group": "Connections", - "icon": "plug", - "pages": [ - "api-reference/connections", - "POST /v3/connections/{provider}", - "POST /v3/connections/list", - "GET /v3/connections/{connectionId}", - "POST /v3/connections/{connectionId}/configure", - "GET /v3/connections/{connectionId}/resources", - "POST /v3/connections/{provider}/import", - "POST /v3/connections/{provider}/documents", - "POST /v3/connections/{provider}/connection", - "DELETE /v3/connections/{connectionId}", - "DELETE /v3/connections/{provider}" - ] - }, - { - "group": "Settings", - "icon": "settings", - "pages": [ - "api-reference/settings", - "GET /v3/settings", - "PATCH /v3/settings", - "POST /v3/settings/suggest-buckets", - "POST /v3/settings/reset" + "v5/api-reference/overview", + "authentication", + { + "group": "Ingest", + "icon": "download", + "pages": [ + "v5/api-reference/ingest", + "POST /ns/{namespace}/document", + "POST /ns/{namespace}/document/batch", + "POST /ns/{namespace}/document/file", + "PATCH /ns/{namespace}/document/{id}", + "POST /ns/{namespace}/document/file/{id}", + "PATCH /ns/{namespace}/document/file/{id}" + ] + }, + { + "group": "Content Management", + "icon": "file-text", + "pages": [ + "v5/api-reference/content-management", + "GET /ns/{namespace}/document/{id}", + "POST /ns/{namespace}/list/{type}", + "DELETE /ns/{namespace}/document", + "DELETE /ns/{namespace}/memories", + "DELETE /ns/{namespace}/memories/semantic" + ] + }, + { + "group": "Search", + "icon": "search", + "pages": [ + "v5/api-reference/search", + "POST /ns/{namespace}/search" + ] + }, + { + "group": "Profiles", + "icon": "id-card", + "pages": [ + "v5/api-reference/profiles", + "POST /ns/{namespace}/profile", + "GET /ns/{namespace}/profile/buckets", + "PUT /ns/{namespace}/profile/buckets", + "DELETE /ns/{namespace}/profile/buckets" + ] + }, + { + "group": "Namespaces", + "icon": "layers", + "pages": [ + "v5/api-reference/namespaces", + "GET /namespaces", + "GET /ns/{namespace}", + "PATCH /ns/{namespace}", + "DELETE /ns/{namespace}" + ] + }, + { + "group": "Organization", + "icon": "building", + "pages": [ + "v5/api-reference/organization", + "GET /organization", + "PATCH /organization" + ] + } ] } ] diff --git a/apps/docs/v5/api-reference/content-management.mdx b/apps/docs/v5/api-reference/content-management.mdx new file mode 100644 index 00000000..615bfc8d --- /dev/null +++ b/apps/docs/v5/api-reference/content-management.mdx @@ -0,0 +1,18 @@ +--- +title: "Content management" +sidebarTitle: "Overview" +description: "Retrieve, list, and remove documents, chunks, and memories" +icon: "file-text" +--- + +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. + +| Operation | Purpose | +| --- | --- | +| `GET /ns/{namespace}/document/{id}` | Retrieve source content with its chunks or memories | +| `POST /ns/{namespace}/list/{type}` | Page through documents, chunks, or memories | +| `DELETE /ns/{namespace}/document` | Remove one or many documents | +| `DELETE /ns/{namespace}/memories` | Forget reviewed memories by exact ID | +| `DELETE /ns/{namespace}/memories/semantic` | Find and forget memories by meaning | + +Semantic forgetting supports `dryRun: true`, so you can review matches before deleting them. See [document read migration](/migration/api-v5-document-reads) and [memory migration](/migration/api-v5-recall). diff --git a/apps/docs/v5/api-reference/ingest.mdx b/apps/docs/v5/api-reference/ingest.mdx new file mode 100644 index 00000000..dddbe5b2 --- /dev/null +++ b/apps/docs/v5/api-reference/ingest.mdx @@ -0,0 +1,21 @@ +--- +title: "Ingest" +sidebarTitle: "Overview" +description: "Turn source content into searchable memory and keep it current" +icon: "download" +--- + +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. + +| Operation | Purpose | +| --- | --- | +| `POST /ns/{namespace}/document` | Add text or a URL; reuse an ID to build on an existing document | +| `POST /ns/{namespace}/document/batch` | Bring in up to 600 documents together | +| `POST /ns/{namespace}/document/file` | Turn an uploaded file into searchable memory | +| `PATCH /ns/{namespace}/document/{id}` | Update metadata or replace canonical content | +| `POST /ns/{namespace}/document/file/{id}` | Completely replace a file-backed document | +| `PATCH /ns/{namespace}/document/file/{id}` | Refresh selected file details or its source | + +The `dynamic` processing mode (default) groups related documents together so memories form from coherent, logical units rather than one isolated entry at a time. Use `instant` to process each document on its own right away; it bills one extra operation per document. + +Every request is scoped to a namespace, keeping each user, project, or tenant isolated. See [document write migration](/migration/api-v5-document-writes). diff --git a/apps/docs/v5/api-reference/namespaces.mdx b/apps/docs/v5/api-reference/namespaces.mdx new file mode 100644 index 00000000..3c5324b1 --- /dev/null +++ b/apps/docs/v5/api-reference/namespaces.mdx @@ -0,0 +1,17 @@ +--- +title: "Namespaces" +sidebarTitle: "Overview" +description: "Keep memory isolated, understandable, and easy to reorganize" +icon: "layers" +--- + +| Operation | Purpose | +| --- | --- | +| `GET /namespaces` | Discover namespaces and see their memory footprint | +| `GET /ns/{namespace}` | See the context guiding one namespace | +| `PATCH /ns/{namespace}` | Give Supermemory better context for future memories | +| `DELETE /ns/{namespace}` | Retire a namespace or preserve its content elsewhere | + +`GET /ns` is an alias for `GET /namespaces`. Profile buckets are managed through `/ns/{namespace}/profile/buckets`, not namespace settings. + +See [namespace and settings migration](/migration/api-v5-settings). diff --git a/apps/docs/v5/api-reference/organization.mdx b/apps/docs/v5/api-reference/organization.mdx new file mode 100644 index 00000000..db00a64a --- /dev/null +++ b/apps/docs/v5/api-reference/organization.mdx @@ -0,0 +1,15 @@ +--- +title: "Organization" +sidebarTitle: "Overview" +description: "Give every namespace a shared understanding of your organization" +icon: "building" +--- + +| Operation | Purpose | +| --- | --- | +| `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. + +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 new file mode 100644 index 00000000..f8e54e1c --- /dev/null +++ b/apps/docs/v5/api-reference/overview.mdx @@ -0,0 +1,30 @@ +--- +title: "API reference" +sidebarTitle: "Overview" +description: "Documents, search, profiles, lists, memories, namespaces, and organization settings in the latest Supermemory API" +icon: "book-open" +--- + +V5 makes namespace scope explicit in the URL and consolidates overlapping legacy operations. + +```text +https://api.supermemory.ai + /ns/{namespace}/document + /ns/{namespace}/search + /ns/{namespace}/profile + /ns/{namespace}/list/{type} + /ns/{namespace}/memories + /namespaces + /organization +``` + +Use `/v5/reference` for the stable V5 reference. `/reference` always points to the latest public version. + + + + 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/profiles.mdx b/apps/docs/v5/api-reference/profiles.mdx new file mode 100644 index 00000000..9bb7a259 --- /dev/null +++ b/apps/docs/v5/api-reference/profiles.mdx @@ -0,0 +1,17 @@ +--- +title: "Profiles" +sidebarTitle: "Overview" +description: "Turn accumulated memory into a ready-to-use understanding of a user" +icon: "id-card" +--- + +| Operation | Purpose | +| --- | --- | +| `POST /ns/{namespace}/profile` | Retrieve durable facts, recent context, and custom insights | +| `GET /ns/{namespace}/profile/buckets` | See the profile categories available here | +| `PUT /ns/{namespace}/profile/buckets` | Shape the profile with namespace-specific categories | +| `DELETE /ns/{namespace}/profile/buckets` | Remove namespace-specific categories | + +Profiles always contain static and dynamic sections, giving applications both durable knowledge and fresh context without composing them manually. Organization-owned buckets may be inherited but cannot be changed through namespace bucket endpoints. + +See [profile migration](/migration/api-v5-recall). diff --git a/apps/docs/v5/api-reference/search.mdx b/apps/docs/v5/api-reference/search.mdx new file mode 100644 index 00000000..f7f556a7 --- /dev/null +++ b/apps/docs/v5/api-reference/search.mdx @@ -0,0 +1,12 @@ +--- +title: "Search" +sidebarTitle: "Overview" +description: "Recall the most relevant memories and source context" +icon: "search" +--- + +`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. + +Tune relevance with threshold, reranking, query rewriting, filters, and related context in the request body. Result controls `limit` and `searchMode` belong in the query string. + +See [search migration](/migration/api-v5-recall) and [typed filter migration](/migration/api-v5-filters).