From 2feccc99fafbf3052f7c995b822dfd12313c4580 Mon Sep 17 00:00:00 2001 From: sohamd22 <85427822+sohamd22@users.noreply.github.com> Date: Tue, 6 Oct 2026 16:48:36 +0000 Subject: [PATCH] docs(api): rename v5 attach to include (#1763) Renames v5 `attach` to `include`. GET routes take one comma-separated `include` query param (`?include=chunks,memories`); search takes every option in the JSON body, with `include` as an object of booleans. Also fixes the `forgotten` description: it does let forgotten memories come back as primary results. Pairs with supermemoryai/mono#3410. --- apps/docs/migration/api-v5-recall.mdx | 2 +- .../snippets/api-v5-content-management.mdx | 6 ++-- apps/docs/snippets/api-v5-overview.mdx | 2 +- apps/docs/snippets/api-v5-rollout.mdx | 2 +- apps/docs/snippets/api-v5-search.mdx | 30 ++++++++++--------- apps/docs/v5/api-reference/search.mdx | 4 +-- 6 files changed, 24 insertions(+), 22 deletions(-) diff --git a/apps/docs/migration/api-v5-recall.mdx b/apps/docs/migration/api-v5-recall.mdx index f3c024ba..355a72f6 100644 --- a/apps/docs/migration/api-v5-recall.mdx +++ b/apps/docs/migration/api-v5-recall.mdx @@ -1,6 +1,6 @@ --- title: "Migrate search to v5" -description: "Upgrade search modes, filters, attachments, defaults, and response readers" +description: "Upgrade search modes, filters, included context, defaults, and response readers" sidebarTitle: "Search" --- diff --git a/apps/docs/snippets/api-v5-content-management.mdx b/apps/docs/snippets/api-v5-content-management.mdx index 04e8ae4b..0f197501 100644 --- a/apps/docs/snippets/api-v5-content-management.mdx +++ b/apps/docs/snippets/api-v5-content-management.mdx @@ -9,11 +9,11 @@ GET /v3/documents/{id}/chunks ``` ```bash v5 -GET /ns/{namespace}/document/{id}?attach=chunks&attach=memories +GET /ns/{namespace}/document/{id}?include=chunks,memories ``` -Repeat `attach` to include chunks, memories, or both. Omitted attachment keys are absent; requested attachments with no results are empty arrays. Lifecycle fields move under `system`: +Pass `include` as a comma-separated list to return chunks, memories, or both. Keys you omit are absent; requested keys with no results are empty arrays. Lifecycle fields move under `system`: ```json {"system":{"status":"done","createdAt":"...","updatedAt":"..."}} @@ -66,7 +66,7 @@ See [memory forgetting](./api-v5-memory-forgetting) for the complete dry-run, ap ### Verification -- Assert requested empty attachments are `[]`, while omitted attachments are absent. +- Assert requested empty includes are `[]`, while omitted includes are absent. - Paginate each resource type until `currentPage >= totalPages`; unselected arrays stay empty. - Verify chunk rows contain their parent `documentId`. - Exercise partial document-delete failures and semantic dry runs. diff --git a/apps/docs/snippets/api-v5-overview.mdx b/apps/docs/snippets/api-v5-overview.mdx index 7d8b6743..2239a314 100644 --- a/apps/docs/snippets/api-v5-overview.mdx +++ b/apps/docs/snippets/api-v5-overview.mdx @@ -19,7 +19,7 @@ The API base URL and bearer keys do not change. v5 application routes are unvers 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. - Migrate envelopes, attachments, pagination, profile buckets, system fields, and partial-error handling before switching traffic. + Migrate envelopes, includes, 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. diff --git a/apps/docs/snippets/api-v5-rollout.mdx b/apps/docs/snippets/api-v5-rollout.mdx index 35e05f64..bf468250 100644 --- a/apps/docs/snippets/api-v5-rollout.mdx +++ b/apps/docs/snippets/api-v5-rollout.mdx @@ -15,7 +15,7 @@ Record each legacy request, v5 request, expected semantic result, and intentiona ### Compare reads and recall -- Document attachments are absent when omitted and empty arrays when requested without results. +- Document includes 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. - Profiles always contain static, dynamic, and bucket sections. diff --git a/apps/docs/snippets/api-v5-search.mdx b/apps/docs/snippets/api-v5-search.mdx index 2ba00d86..023189e7 100644 --- a/apps/docs/snippets/api-v5-search.mdx +++ b/apps/docs/snippets/api-v5-search.mdx @@ -1,4 +1,4 @@ -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 takes every option in one typed JSON body. Search has no query-string parameters. ### Request mapping @@ -6,13 +6,13 @@ v5 searches one namespace, defaults to hybrid recall, and moves ranking controls | --- | --- | | `containerTag` | `/ns/{namespace}` | | body `q` | body `query` | -| body `limit` | query `limit` | -| `searchMode: "documents"` | `searchMode=chunks` | -| omitted search mode | `searchMode=hybrid` | +| body `limit` | body `limit` | +| `searchMode: "documents"` | `searchMode: "chunks"` | +| omitted search mode | `searchMode: "hybrid"` | | `filters` | singular `filter` | -| `include.documents` or `.summaries` | `attach.documents` | -| `include.relatedMemories` | `attach.related` | -| `include.forgottenMemories` | `attach.forgotten` | +| `include.documents` or `.summaries` | `include.documents` | +| `include.relatedMemories` | `include.related` | +| `include.forgottenMemories` | `include.forgotten` | | `rerank: true` / `aggregate: true` | `rerank: "order"` / `"aggregate"` | @@ -22,8 +22,8 @@ POST /v4/search ``` ```bash v5 -POST /ns/user_1/search?limit=10&searchMode=memories -{"query":"What did the user decide?","threshold":0.6,"rewriteQuery":false} +POST /ns/user_1/search +{"query":"What did the user decide?","limit":10,"searchMode":"memories","threshold":0.6,"rewriteQuery":false} ``` @@ -48,11 +48,13 @@ Set mode and threshold explicitly while comparing versions. After parity testing Legacy `include.chunks` has no v5 equivalent. Choose `chunks` or `hybrid` instead. -### Attachments and ranking +### Included context and ranking -- `attach.documents` adds the most relevant source document to each result. -- `attach.related` adds parent, child, and sibling memories. -- `attach.forgotten` allows forgotten memories in related context; it does not make them primary results. +`include` is an object of booleans in the body, e.g. `"include": {"documents": true, "related": true}`. Each flag defaults to `false`. + +- `include.documents` adds the most relevant source document to each result. +- `include.related` adds parent, child, and sibling memories. +- `include.forgotten` lets forgotten and expired memories appear in results, including as primary results. - `rerank` accepts `none`, `order`, or `aggregate`; `rewriteQuery` controls retrieval-oriented query rewriting. ### Response mapping @@ -71,5 +73,5 @@ Each primary result contains either `memory`, `chunk`, or both only if the contr - 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. +- Cover every include alone and in combination, including empty results. - Verify filters, namespace isolation, result limits, and invalid body/query placement. diff --git a/apps/docs/v5/api-reference/search.mdx b/apps/docs/v5/api-reference/search.mdx index 9532fc1a..92cb0121 100644 --- a/apps/docs/v5/api-reference/search.mdx +++ b/apps/docs/v5/api-reference/search.mdx @@ -5,8 +5,8 @@ description: "Recall the most relevant memories and source context" 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. +`POST /ns/{namespace}/search` recalls the most useful memories and source chunks for a query. Hybrid search combines both by default; set `searchMode` to `memories` or `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. +Every option goes in the JSON request body: `query`, `searchMode`, `limit`, `threshold`, `filter`, `include`, `rerank`, and `rewriteQuery`. See [search migration](/migration/api-v5-recall) and [typed filter migration](/migration/api-v5-filters).