From ecb2db59b5bffe1a3d01d60b6ad941cd5a962b1f Mon Sep 17 00:00:00 2001 From: Soham Daga Date: Mon, 5 Oct 2026 11:45:34 -0700 Subject: [PATCH] docs(api): rename v5 attach to include --- 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 | 18 ++++++++++-------- apps/docs/v5/api-reference/search.mdx | 2 +- 6 files changed, 17 insertions(+), 15 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..1670393a 100644 --- a/apps/docs/snippets/api-v5-search.mdx +++ b/apps/docs/snippets/api-v5-search.mdx @@ -10,9 +10,9 @@ v5 searches one namespace, defaults to hybrid recall, and moves ranking controls | `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` | query `include=documents` | +| `include.relatedMemories` | query `include=related` | +| `include.forgottenMemories` | query `include=forgotten` | | `rerank: true` / `aggregate: true` | `rerank: "order"` / `"aggregate"` | @@ -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 a comma-separated query parameter, e.g. `?include=documents,related`. Repeating the parameter returns a 400. + +- `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..8c9fab04 100644 --- a/apps/docs/v5/api-reference/search.mdx +++ b/apps/docs/v5/api-reference/search.mdx @@ -7,6 +7,6 @@ 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. -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. +Tune relevance with threshold, reranking, query rewriting, and filters in the request body. Result controls `limit`, `searchMode`, and `include` belong in the query string. See [search migration](/migration/api-v5-recall) and [typed filter migration](/migration/api-v5-filters).