mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-09-30 01:51:28 +00:00
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.
This commit is contained in:
Soham Daga
parent
57b430b5b6
commit
f55fe00e32
8 changed files with 297 additions and 86 deletions
|
|
@ -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"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
|
|
|
|||
18
apps/docs/v5/api-reference/content-management.mdx
Normal file
18
apps/docs/v5/api-reference/content-management.mdx
Normal file
|
|
@ -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).
|
||||
21
apps/docs/v5/api-reference/ingest.mdx
Normal file
21
apps/docs/v5/api-reference/ingest.mdx
Normal file
|
|
@ -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).
|
||||
17
apps/docs/v5/api-reference/namespaces.mdx
Normal file
17
apps/docs/v5/api-reference/namespaces.mdx
Normal file
|
|
@ -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).
|
||||
15
apps/docs/v5/api-reference/organization.mdx
Normal file
15
apps/docs/v5/api-reference/organization.mdx
Normal file
|
|
@ -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).
|
||||
30
apps/docs/v5/api-reference/overview.mdx
Normal file
30
apps/docs/v5/api-reference/overview.mdx
Normal file
|
|
@ -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.
|
||||
|
||||
<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>
|
||||
<Card title="Authentication" icon="key" href="/authentication">
|
||||
Authenticate with the same bearer API keys used by legacy endpoints.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
17
apps/docs/v5/api-reference/profiles.mdx
Normal file
17
apps/docs/v5/api-reference/profiles.mdx
Normal file
|
|
@ -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).
|
||||
12
apps/docs/v5/api-reference/search.mdx
Normal file
12
apps/docs/v5/api-reference/search.mdx
Normal file
|
|
@ -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).
|
||||
Loading…
Add table
Reference in a new issue