mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-10 03:28:14 +00:00
docs(api): lowercase v3/v4/v5 across migration and reference pages
This commit is contained in:
Mahesh Sanikommu
parent
ec8e3aedb4
commit
e8561ff714
20 changed files with 65 additions and 62 deletions
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Migrate content management to V5"
|
||||
title: "Migrate content management to v5"
|
||||
description: "Upgrade document retrieval, resource lists, and document or memory deletion"
|
||||
sidebarTitle: "Content management"
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Migrate document and file updates to V5"
|
||||
title: "Migrate document and file updates to v5"
|
||||
description: "Choose append, replacement, or metadata-only updates deliberately"
|
||||
sidebarTitle: "Document updates"
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Migrate document ingestion to V5"
|
||||
title: "Migrate document ingestion to v5"
|
||||
description: "Upgrade single, batch, and file ingestion without changing append behavior"
|
||||
sidebarTitle: "Document ingestion"
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "Migrate metadata filters to V5"
|
||||
description: "Convert legacy Query filters into strict, type-safe V5 filter expressions"
|
||||
title: "Migrate metadata filters to v5"
|
||||
description: "Convert legacy Query filters into strict, type-safe v5 filter expressions"
|
||||
sidebarTitle: "Typed filters"
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Migrate memory forgetting to V5"
|
||||
title: "Migrate memory forgetting to v5"
|
||||
description: "Replace legacy exact and semantic forgetting with one response contract"
|
||||
sidebarTitle: "Memory forgetting"
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Migrate organization settings to V5"
|
||||
title: "Migrate organization settings to v5"
|
||||
description: "Reduce organization settings to shared context and namespace count"
|
||||
sidebarTitle: "Organization settings"
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Migrate profiles and buckets to V5"
|
||||
title: "Migrate profiles and buckets to v5"
|
||||
description: "Separate profile retrieval from search and manage namespace-owned buckets"
|
||||
sidebarTitle: "Profiles and buckets"
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Migrate search to V5"
|
||||
title: "Migrate search to v5"
|
||||
description: "Upgrade search modes, filters, attachments, defaults, and response readers"
|
||||
sidebarTitle: "Search"
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Verify and roll out a V5 migration"
|
||||
title: "Verify and roll out a v5 migration"
|
||||
description: "Prove behavioral parity, detect intentional differences, and cut over safely"
|
||||
sidebarTitle: "Verification and rollout"
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,10 +1,11 @@
|
|||
---
|
||||
title: "Migrate Supermemory V3/V4 to V5"
|
||||
description: "Upgrade legacy API calls to the namespace-scoped V5 API"
|
||||
sidebarTitle: "Legacy API to V5"
|
||||
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";
|
||||
|
|
@ -18,6 +19,8 @@ import Filters from "/snippets/api-v5-filters.mdx";
|
|||
import Rollout from "/snippets/api-v5-rollout.mdx";
|
||||
import Completion from "/snippets/api-v5-completion.mdx";
|
||||
|
||||
<AgentPrompt />
|
||||
|
||||
<Overview />
|
||||
|
||||
## Document ingestion
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
V5 retrieves, lists, and removes content within one explicit namespace.
|
||||
v5 retrieves, lists, and removes content within one explicit namespace.
|
||||
|
||||
### Retrieve a document and its derived context
|
||||
|
||||
|
|
@ -8,7 +8,7 @@ GET /v3/documents/{id}
|
|||
GET /v3/documents/{id}/chunks
|
||||
```
|
||||
|
||||
```bash V5
|
||||
```bash v5
|
||||
GET /ns/{namespace}/document/{id}?attach=chunks&attach=memories
|
||||
```
|
||||
</CodeGroup>
|
||||
|
|
@ -27,7 +27,7 @@ POST /v3/documents/list
|
|||
POST /v4/memories/list
|
||||
```
|
||||
|
||||
```bash V5
|
||||
```bash v5
|
||||
POST /ns/{namespace}/list/{type}?page=1&limit=100&sort=createdAt&order=desc
|
||||
{}
|
||||
```
|
||||
|
|
@ -45,17 +45,17 @@ DELETE /v3/documents/{id}
|
|||
DELETE /v3/documents/bulk
|
||||
```
|
||||
|
||||
```bash V5
|
||||
```bash v5
|
||||
DELETE /ns/{namespace}/document
|
||||
{"ids":["doc_1","external_id_2"]}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
The V5 array accepts 1–100 Supermemory or caller-defined IDs. Inspect both `deletedCount` and per-ID `errors`; HTTP success can include partial failures.
|
||||
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 |
|
||||
| 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 }` |
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
V5 moves document scope into the URL and keeps repeated caller IDs attached to one evolving document.
|
||||
v5 moves document scope into the URL and keeps repeated caller IDs attached to one evolving document.
|
||||
|
||||
### Rename common fields
|
||||
|
||||
| Legacy | V5 | Location |
|
||||
| Legacy | v5 | Location |
|
||||
| --- | --- | --- |
|
||||
| `containerTag` | `{namespace}` | Path |
|
||||
| `customId` | `id` | JSON body |
|
||||
|
|
@ -19,13 +19,13 @@ POST /v3/documents
|
|||
{"content":"new turn","customId":"conv_1","containerTag":"user_1"}
|
||||
```
|
||||
|
||||
```bash V5
|
||||
```bash v5
|
||||
POST /ns/user_1/document?dreaming=dynamic
|
||||
{"content":"new turn","id":"conv_1"}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
|
|
@ -34,12 +34,12 @@ The response remains an acceptance result with `id` and `status`. Repeating the
|
|||
{"documents":["first","second"],"containerTag":"user_1"}
|
||||
```
|
||||
|
||||
```json V5
|
||||
```json v5
|
||||
{"documents":[{"content":"first","id":"doc_1"},{"content":"second","id":"doc_2"}]}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
V5 makes the difference between adding new information and replacing the canonical source explicit.
|
||||
v5 makes the difference between adding new information and replacing the canonical source explicit.
|
||||
|
||||
### Choose the correct write
|
||||
|
||||
|
|
@ -18,13 +18,13 @@ PATCH /v3/documents/doc_1
|
|||
{"content":"corrected source","metadata":{"revision":2}}
|
||||
```
|
||||
|
||||
```bash V5
|
||||
```bash v5
|
||||
PATCH /ns/user_1/document/doc_1?dreaming=dynamic
|
||||
{"content":"corrected source","metadata":{"revision":2}}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
|
|
@ -50,7 +50,7 @@ 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.
|
||||
|
||||
<Warning>
|
||||
There is no public V5 `PUT /ns/{namespace}/document/file/{id}` operation. Use POST for a complete replacement and PATCH for a partial update.
|
||||
There is no public v5 `PUT /ns/{namespace}/document/file/{id}` operation. Use POST for a complete replacement and PATCH for a partial update.
|
||||
</Warning>
|
||||
|
||||
### IDs and scope
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
V5 uses one optional singular `filter` field for search, profiles, and list operations.
|
||||
v5 uses one optional singular `filter` field for search, profiles, and list operations.
|
||||
|
||||
### Shape
|
||||
|
||||
|
|
@ -16,7 +16,7 @@ Fields may contain letters, numbers, `_`, `.`, and `-`. Expressions allow up to
|
|||
|
||||
### Operator mapping
|
||||
|
||||
| Legacy condition | V5 predicate |
|
||||
| Legacy condition | v5 predicate |
|
||||
| --- | --- |
|
||||
| `{ key, value }` | `{ field: key, operator: "eq", value }` |
|
||||
| `negate: true` equality | `operator: "neq"` |
|
||||
|
|
@ -41,7 +41,7 @@ Fields may contain letters, numbers, `_`, `.`, and `-`. Expressions allow up to
|
|||
}
|
||||
```
|
||||
|
||||
```json V5
|
||||
```json v5
|
||||
{
|
||||
"operator": "and",
|
||||
"operands": [
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
V5 scopes forgetting to one namespace and returns the same result envelope for exact and semantic requests.
|
||||
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 |
|
||||
| Intent | v5 operation |
|
||||
| --- | --- |
|
||||
| Forget reviewed memory IDs | `DELETE /ns/{namespace}/memories` |
|
||||
| Find memories by meaning | `DELETE /ns/{namespace}/memories/semantic` |
|
||||
|
|
@ -57,7 +57,7 @@ Use this workflow when a human or policy must approve the exact set. Re-running
|
|||
|
||||
### 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.
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
V5 renames the public isolation boundary from container tag to namespace. Existing values remain valid identifiers; no stored data rename is required.
|
||||
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 |
|
||||
| Legacy | v5 |
|
||||
| --- | --- |
|
||||
| `GET /v3/container-tags/list` | `GET /namespaces` |
|
||||
| `GET /v3/container-tags/{tag}` | `GET /ns/{namespace}` |
|
||||
|
|
@ -24,7 +24,7 @@ PATCH /v3/container-tags/project_alpha
|
|||
{"entityContext":"Research project for distributed systems"}
|
||||
```
|
||||
|
||||
```bash V5
|
||||
```bash v5
|
||||
PATCH /ns/project_alpha
|
||||
{"supportingContext":"Research project for distributed systems"}
|
||||
```
|
||||
|
|
@ -52,7 +52,7 @@ DELETE /ns/project_alpha
|
|||
|
||||
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.
|
||||
Legacy merge can accept multiple sources; v5 moves one source per request. Run multi-source migrations sequentially and record each operation independently.
|
||||
|
||||
### Verification
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
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.
|
||||
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 |
|
||||
| Legacy | v5 |
|
||||
| --- | --- |
|
||||
| `GET /v3/settings` | `GET /organization` |
|
||||
| `PATCH /v3/settings` | `PATCH /organization` |
|
||||
|
|
@ -31,7 +31,7 @@ PATCH /v3/settings
|
|||
{"filterPrompt":"Acme builds security tools for enterprises"}
|
||||
```
|
||||
|
||||
```bash V5
|
||||
```bash v5
|
||||
PATCH /organization
|
||||
{"organizationalContext":"Acme builds security tools for enterprises"}
|
||||
```
|
||||
|
|
@ -44,13 +44,13 @@ Organization updates require an organization administrator. Do not silently fall
|
|||
### 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.
|
||||
- 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.
|
||||
- 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.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
V5 returns a maintained profile directly and gives profile bucket definitions their own namespace-scoped resource.
|
||||
v5 returns a maintained profile directly and gives profile bucket definitions their own namespace-scoped resource.
|
||||
|
||||
### Remove search behavior from profile calls
|
||||
|
||||
|
|
@ -8,15 +8,15 @@ POST /v4/profile
|
|||
{"containerTag":"user_1","q":"work preferences","threshold":0.6,"include":{}}
|
||||
```
|
||||
|
||||
```bash V5
|
||||
```bash v5
|
||||
POST /ns/user_1/profile
|
||||
{"filter":{"field":"region","operator":"eq","value":"us-west"},"buckets":["work"]}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
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`.
|
||||
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
|
||||
### Read the v5 profile shape
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -38,7 +38,7 @@ POST /v4/profile/buckets
|
|||
{"containerTag":"user_1"}
|
||||
```
|
||||
|
||||
```bash V5
|
||||
```bash v5
|
||||
GET /ns/user_1/profile/buckets
|
||||
```
|
||||
</CodeGroup>
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ Treat migration as a behavioral comparison, not a raw response snapshot update.
|
|||
|
||||
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.
|
||||
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
|
||||
|
||||
|
|
@ -17,7 +17,7 @@ Record each legacy request, V5 request, expected semantic result, and intentiona
|
|||
|
||||
- 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.
|
||||
- Search parity uses explicit v4-equivalent mode and threshold before testing v5 defaults.
|
||||
- Profiles always contain static, dynamic, and bucket sections.
|
||||
|
||||
### Exercise boundaries
|
||||
|
|
@ -36,7 +36,7 @@ Record each legacy request, V5 request, expected semantic result, and intentiona
|
|||
same request intent
|
||||
|
|
||||
+-- same semantic result ------> parity
|
||||
+-- documented V5 difference --> update assertion
|
||||
+-- documented v5 difference --> update assertion
|
||||
+-- undocumented difference ----> block cutover
|
||||
```
|
||||
|
||||
|
|
@ -44,7 +44,7 @@ Do not normalize away an undocumented difference. Capture the request pair, name
|
|||
|
||||
### Cut over by domain
|
||||
|
||||
1. Ship V5 request construction behind a per-domain flag.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
V5 searches one namespace, defaults to hybrid recall, and moves ranking controls into a typed request body.
|
||||
v5 searches one namespace, defaults to hybrid recall, and moves ranking controls into a typed request body.
|
||||
|
||||
### Request mapping
|
||||
|
||||
| Legacy | V5 |
|
||||
| Legacy | v5 |
|
||||
| --- | --- |
|
||||
| `containerTag` | `/ns/{namespace}` |
|
||||
| body `q` | body `query` |
|
||||
|
|
@ -21,7 +21,7 @@ POST /v4/search
|
|||
{"q":"What did the user decide?","containerTag":"user_1","limit":10,"searchMode":"memories"}
|
||||
```
|
||||
|
||||
```bash V5
|
||||
```bash v5
|
||||
POST /ns/user_1/search?limit=10&searchMode=memories
|
||||
{"query":"What did the user decide?","threshold":0.6,"rewriteQuery":false}
|
||||
```
|
||||
|
|
@ -29,14 +29,14 @@ POST /ns/user_1/search?limit=10&searchMode=memories
|
|||
|
||||
### Changed defaults
|
||||
|
||||
| Setting | V4 | V5 |
|
||||
| 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.
|
||||
Set mode and threshold explicitly while comparing versions. After parity testing, remove them only if you want the broader v5 hybrid defaults.
|
||||
|
||||
### Search modes
|
||||
|
||||
|
|
@ -46,7 +46,7 @@ Set mode and threshold explicitly while comparing versions. After parity testing
|
|||
| `chunks` | Source chunks only |
|
||||
| `hybrid` | Both result types in one ranked list |
|
||||
|
||||
Legacy `include.chunks` has no V5 equivalent. Choose `chunks` or `hybrid` instead.
|
||||
Legacy `include.chunks` has no v5 equivalent. Choose `chunks` or `hybrid` instead.
|
||||
|
||||
### Attachments and ranking
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ Legacy `include.chunks` has no V5 equivalent. Choose `chunks` or `hybrid` instea
|
|||
|
||||
### Response mapping
|
||||
|
||||
| Legacy reader | V5 reader |
|
||||
| Legacy reader | v5 reader |
|
||||
| --- | --- |
|
||||
| Result array | `results` |
|
||||
| Timing | `searchTime` |
|
||||
|
|
@ -69,7 +69,7 @@ Each primary result contains either `memory`, `chunk`, or both only if the contr
|
|||
|
||||
### Verification
|
||||
|
||||
- Compare IDs using explicit V4-equivalent defaults, then test V5 hybrid behavior separately.
|
||||
- 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.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue