From f3001517d1a435e79bac597c38019977678af83c Mon Sep 17 00:00:00 2001 From: sreedharsreeram <141047751+sreedharsreeram@users.noreply.github.com> Date: Wed, 21 Oct 2026 18:19:21 +0000 Subject: [PATCH] docs: explain optional content in v5 document lists (#1830) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Why The document operations guide did not describe how to retrieve extracted text from a v5 document list, and the migration guide incorrectly said the list `include` object was for memories only. ## What changed - Document `include.content`, its `false` default, and a cURL request for uploaded files in the same section pattern as the surrounding guide. - Explain that list content is the last published extracted text, including the behavior before first publication and during failed replacement. - Correct the v5 migration and reference overview copy. ```mermaid flowchart LR A[Document operations guide] --> B[include.content request] B --> C[Published extracted text in list response] ``` ## Validation - Compared the guide and migration snippet with adjacent v5 docs for format and terminology. - `git diff --check` — passed. - `python3 -m json.tool apps/docs/docs.json` — passed. Related API PR: https://github.com/supermemoryai/mono/pull/3606 The written docs should publish with or after the API change. The generated v5 reference reads the deployed OpenAPI source, so it updates when that source is available and the docs site refreshes. --- apps/docs/ingestion/document-operations.mdx | 14 ++++++++++++++ apps/docs/snippets/api-v5-content-management.mdx | 4 +++- apps/docs/v5/api-reference/content-management.mdx | 2 ++ 3 files changed, 19 insertions(+), 1 deletion(-) diff --git a/apps/docs/ingestion/document-operations.mdx b/apps/docs/ingestion/document-operations.mdx index 428e7c2f..457893c4 100644 --- a/apps/docs/ingestion/document-operations.mdx +++ b/apps/docs/ingestion/document-operations.mdx @@ -85,8 +85,22 @@ Every response contains `documents`, `chunks`, `memories`, and `pagination`. Onl | `sort` | string | `createdAt` | `createdAt` or `updatedAt` for documents and memories; `createdAt` or `position` for chunks | | `order` | string | `desc` | `desc` (newest) or `asc` (oldest) | | `body.filter` | object | — | Metadata filter. See [Organizing & Filtering](/concepts/filtering) | +| `body.include.content` | boolean | `false` | Documents only: include last published extracted text as `content` | | `body.include.forgotten` | boolean | `false` | Memories only: include forgotten or expired rows that remain latest, returned with `isForgotten: true`. Normal forgetting makes a memory non-latest, so it still will not appear in this list | +### Include extracted content + +Document lists omit `content` by default. To include the last published extracted text, including text from uploaded files, set `include.content` in the JSON body: + +```bash +curl -X POST "https://api.supermemory.ai/ns/user_123/list/documents?limit=10" \ + -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"include":{"content":true}}' +``` + +`content` is `null` until the first extraction publishes. When you replace a file, the previous text remains until the new extraction publishes. It also remains if the replacement fails. Including content can make pages large. + ```typescript async function getAllDocuments(namespace: string) { diff --git a/apps/docs/snippets/api-v5-content-management.mdx b/apps/docs/snippets/api-v5-content-management.mdx index e926f97b..e2b843c4 100644 --- a/apps/docs/snippets/api-v5-content-management.mdx +++ b/apps/docs/snippets/api-v5-content-management.mdx @@ -48,7 +48,9 @@ POST /ns/{namespace}/list/{type}?page=1&limit=100&sort=createdAt&order=desc ``` -Set `type` to `documents`, `chunks`, or `memories`. Pagination and sorting move to the query string as plain integers and values; the body takes an optional `filter` and, for memories, `include`. Defaults are `page=1`, `limit=10` (maximum 100), `sort=createdAt`, and `order=desc`. `sort` accepts `createdAt` or `updatedAt` for documents and memories, and `createdAt` or `position` for chunks; any other combination returns `400`. +Set `type` to `documents`, `chunks`, or `memories`. Pagination and sorting move to the query string as plain integers and values; the body takes an optional `filter` and `include` object. Defaults are `page=1`, `limit=10` (maximum 100), `sort=createdAt`, and `order=desc`. `sort` accepts `createdAt` or `updatedAt` for documents and memories, and `createdAt` or `position` for chunks; any other combination returns `400`. + +Document lists omit `content` by default. Send `{"include":{"content":true}}` to return the last published extracted text, including text from uploaded files. `content` is `null` before the first extraction publishes. During a replacement, previous text remains until new text publishes and also remains if extraction fails. Including content can make responses large. Memory lists return only the latest version of each memory and hide forgotten memories and memories past their `forget_after`. Sending `"include": {"forgotten": true}` admits forgotten or expired rows only if they remain latest; they come back with `isForgotten: true`. Normal forgetting makes a memory non-latest, so this list does not recover it even with that flag. To search such memories, use search with `include.forgotten`. Document memories (`include=memories` on `GET /ns/{namespace}/document/{id}`) report the same forgotten flag. diff --git a/apps/docs/v5/api-reference/content-management.mdx b/apps/docs/v5/api-reference/content-management.mdx index 37d05a94..7e2fde72 100644 --- a/apps/docs/v5/api-reference/content-management.mdx +++ b/apps/docs/v5/api-reference/content-management.mdx @@ -41,4 +41,6 @@ curl -X POST "https://api.supermemory.ai/ns/user_1/list/documents?page=1&limit=5 ``` +Document lists omit `content` by default. Send `{"include":{"content":true}}` to return published extracted text, including text from uploaded files. See [Document operations](/ingestion/document-operations) for response and processing details. + Semantic forgetting supports `dryRun: true`, so you can review matches before deleting them. See [document read migration](/migration/api-v5-document-reads) and [memory forgetting migration](/migration/api-v5-memory-forgetting).