mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-27 06:15:15 +00:00
4347970d16
Fixes v5 ingestion and document-operation docs. - **Query params return `400`.** `dreaming`, `fileType` and `mimeType` were documented as query params; they are JSON body or multipart form fields. - **Errors.** Out-of-balance quota is `402`, not `429`; `429` is only rate limiting. Added the `409` returned during a namespace merge. - **Statuses.** There is no `processing` status. The real ones are queued, extracting, chunking, embedding, done and failed; treat anything else as in progress. - **`group` on updates.** `group` is ingestion-side: it picks which existing memories serve as context while content is processed. Changing it only takes effect on re-ingestion, so it's sent with `content`/`file`. The "group-only PATCH" claims are removed from the migration doc. - **Lists, deletes and forget:** - Valid `sort` values per type, a `limit` max of 100, and `include.forgotten`. - Deletes skip documents that are still processing. - Forget-matching has a 100-match cap and a 2000-character `query` limit. - **Failed documents stay `failed`.** The docs said they're deleted after 2 minutes. They actually stay `failed`, and resending the same `id` reprocesses them. - **Smaller fixes:** - Metadata allows `string[]`. - The batch response field is `count`. - `audio` is a valid `fileType`. - Chunk overlap is 200 characters. - URL extraction no longer claims Markdowner. - Search examples no longer index the response object as an array. Checked against the current API and the published SDKs (TS 5.0.1, Python 5.0.0). Legacy v3/v4 docs are unchanged apart from factual fixes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
123 lines
6.1 KiB
Text
123 lines
6.1 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","dreamingStatus":"dreaming","createdAt":"...","updatedAt":"..."}}
|
||
```
|
||
|
||
`system.status` is one of `unknown`, `queued`, `extracting`, `chunking`, `embedding`, `indexing`, `done`, or `failed`.
|
||
|
||
`system.dreamingStatus` tracks memory generation separately. It is `dreaming` while memories for the latest content are queued, being generated, or waiting for a retry, and `done` once they are generated or when the document needed none. Under the default `dreaming: "dynamic"`, `status` can reach `done` minutes before `dreamingStatus` does, so wait on `dreamingStatus` when the next step reads memories or profiles. Legacy `GET /v3/documents/{id}` returned it as a top-level `dreamingStatus`; v5 nests it under `system` on document reads and on document list items.
|
||
|
||
### Retrieve a memory and its history
|
||
|
||
```bash v5
|
||
GET /ns/{namespace}/memories/{id}?include=related,documents&relatedLimit=10
|
||
```
|
||
|
||
Returns one memory with `id`, `memory`, `metadata`, `isStatic`, `isInference`, `isLatest`, `isForgotten`, `version`, and `system.createdAt/updatedAt`. A memory from another namespace returns `404`; a forgotten memory, or one past its `forget_after`, is still returned with `isForgotten: true`.
|
||
|
||
- `include=related` adds `included.related.parents` (earlier versions), `children` (newer versions), and `siblings` (memories directly connected by `extends` or `derives`). Parents and children reach up to three versions away, nearest first. Each list holds at most `relatedLimit` items (default `10`, maximum `100`). Forgotten memories and memories in other namespaces are left out.
|
||
- `include=documents` adds `included.document`, the most recently updated source document. With both values, every related memory also carries its own `document`.
|
||
|
||
### 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`. `sort` accepts `createdAt` or `updatedAt` for documents and memories, and `createdAt` or `position` for chunks; any other combination returns `400`.
|
||
|
||
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.
|
||
|
||
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. Only documents whose `system.status` is `done` or `failed` are deleted; one that is still processing comes back in `errors` as `Document is still processing`.
|
||
|
||
### With the SDK
|
||
|
||
<CodeGroup>
|
||
```ts Legacy
|
||
const doc = await client.documents.get("doc_1")
|
||
const page = await client.documents.list({ containerTags: ["user_1"] })
|
||
const processing = await client.documents.listProcessing()
|
||
await client.documents.delete("doc_1")
|
||
```
|
||
|
||
```ts v5
|
||
const doc = await supermemory.documents.get("user_1", "doc_1", {
|
||
include: ["chunks", "memories"],
|
||
})
|
||
|
||
const { documents, pagination } = await supermemory.list("user_1", "documents", {
|
||
page: 1,
|
||
limit: 100,
|
||
sort: "createdAt",
|
||
order: "desc",
|
||
})
|
||
|
||
const { memories } = await supermemory.list("user_1", "memories")
|
||
|
||
const { count, errors } = await supermemory.documents.delete("user_1", {
|
||
ids: ["doc_1", "external_id_2"],
|
||
})
|
||
```
|
||
</CodeGroup>
|
||
|
||
There is no separate processing list. Read `system.status` and `system.dreamingStatus` on each item returned by `supermemory.list(namespace, "documents")`. Chunks come from `supermemory.list(namespace, "chunks")` or `documents.get` with `include: ["chunks"]`.
|
||
|
||
### 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](/migration/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.
|
||
- Move readers of the legacy top-level `dreamingStatus` to `system.dreamingStatus`, and gate memory or profile reads on it rather than on `system.status`.
|
||
- 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.
|