mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-11 03:37:56 +00:00
3688ffc996
Docs for supermemoryai/mono#3417: list pagination defaults (`page=1`, `limit=10`, max 100, `sort=createdAt`, `order=desc`) and `include.forgotten` for memory lists. Absorbs #1768.
77 lines
2.9 KiB
Text
77 lines
2.9 KiB
Text
v5 retrieves, lists, and removes content within one explicit namespace.
|
||
|
||
### Retrieve a document and its derived context
|
||
|
||
<CodeGroup>
|
||
```bash Legacy
|
||
GET /v3/documents/{id}
|
||
GET /v3/documents/{id}/chunks
|
||
```
|
||
|
||
```bash v5
|
||
GET /ns/{namespace}/document/{id}?include=chunks,memories
|
||
```
|
||
</CodeGroup>
|
||
|
||
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":"..."}}
|
||
```
|
||
|
||
`system.status` is one of `unknown`, `queued`, `extracting`, `chunking`, `embedding`, `indexing`, `done`, or `failed`.
|
||
|
||
### List documents, chunks, or memories
|
||
|
||
<CodeGroup>
|
||
```bash Legacy
|
||
POST /v3/documents/list
|
||
POST /v4/memories/list
|
||
```
|
||
|
||
```bash v5
|
||
POST /ns/{namespace}/list/{type}?page=1&limit=100&sort=createdAt&order=desc
|
||
{}
|
||
```
|
||
</CodeGroup>
|
||
|
||
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`.
|
||
|
||
Memory lists hide forgotten memories and memories past their `forget_after`. Send `"include": {"forgotten": true}` to list them too; they come back with `isForgotten: true`. Document memories (`include=memories` on `GET /ns/{namespace}/document/{id}`) report the same flag.
|
||
|
||
Every response contains `documents`, `chunks`, `memories`, and `pagination`. Only the selected resource array is populated. Replace legacy `memories` assumptions in document-list callers with `documents`.
|
||
|
||
### Delete documents
|
||
|
||
<CodeGroup>
|
||
```bash Legacy
|
||
DELETE /v3/documents/{id}
|
||
DELETE /v3/documents/bulk
|
||
```
|
||
|
||
```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 `count` and per-ID `errors`; HTTP success can include partial failures.
|
||
|
||
### Forget memories
|
||
|
||
| 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 }` |
|
||
|
||
Both return `{ count, matches, errors }`. For drift-free semantic deletion, preview with `dryRun: true`, review the IDs, then submit them to the exact-ID endpoint.
|
||
|
||
See [memory forgetting](./api-v5-memory-forgetting) for the complete dry-run, approval, response, and audit workflow.
|
||
|
||
### Verification
|
||
|
||
- 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.
|
||
- Verify IDs cannot read, list, or delete content outside their namespace.
|