mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-11 03:37:56 +00:00
f0d4b265e5
Docs for supermemoryai/mono#3415: delete and batch return `count`; ingest `status` is `queued`/`done` (batch adds `error`, files say `queued`); document `system.status` values; search `isInference` and `included.document.system`; `metadata` never null.
70 lines
3.4 KiB
Text
70 lines
3.4 KiB
Text
v5 moves document scope into the URL and keeps repeated caller IDs attached to one evolving document.
|
||
|
||
### Rename common fields
|
||
|
||
| Legacy | v5 | Location |
|
||
| --- | --- | --- |
|
||
| `containerTag` | `{namespace}` | Path |
|
||
| `customId` | `id` | JSON body |
|
||
| `entityContext` | `supportingContext` | JSON/form body |
|
||
| `filterByMetadata` | `group` | JSON/form body |
|
||
| `documentDate` | `date` | JSON/form body |
|
||
| `taskType`, `dreaming` | unchanged | Query string |
|
||
|
||
### Add or append one document
|
||
|
||
<CodeGroup>
|
||
```bash Legacy
|
||
POST /v3/documents
|
||
{"content":"new turn","customId":"conv_1","containerTag":"user_1"}
|
||
```
|
||
|
||
```bash v5
|
||
POST /ns/user_1/document?dreaming=dynamic
|
||
{"content":"new turn","id":"conv_1"}
|
||
```
|
||
</CodeGroup>
|
||
|
||
The response remains an acceptance result with `id` and `status`. Its `status` is the document's processing state after the request: `queued` when new work was queued, otherwise the document's current state (for example `done` for an unchanged duplicate, or `failed` for a metadata-only update to a failed document). Possible values: `unknown`, `queued`, `extracting`, `chunking`, `embedding`, `indexing`, `done`, `failed`. Repeating the v5 request with `id: "conv_1"` adds or diffs the new content into that document; it does not silently replace the canonical source.
|
||
|
||
### Batch ingestion
|
||
|
||
<CodeGroup>
|
||
```json Legacy
|
||
{"documents":["first","second"],"containerTag":"user_1"}
|
||
```
|
||
|
||
```json v5
|
||
{"documents":[{"content":"first","id":"doc_1"},{"content":"second","id":"doc_2"}]}
|
||
```
|
||
</CodeGroup>
|
||
|
||
Send the v5 body to `POST /ns/user_1/document/batch`. The array accepts 1–600 document objects. Namespace, `taskType`, and processing mode apply to the request; document content, ID, context, metadata, grouping, and date stay per item.
|
||
|
||
`results` lists accepted documents first, in request order, then failed ones; match each result by `id`, or by `url` for a failed item with no ID. Inspect `count` (accepted), `failed`, and every item in `results`; each item's `status` is a processing state as above, or `error` when that item failed, and a batch can contain successful and failed items together.
|
||
|
||
### File ingestion
|
||
|
||
Replace `POST /v3/documents/file` with `POST /ns/{namespace}/document/file`. Continue using `multipart/form-data`:
|
||
|
||
| Part | Encoding |
|
||
| --- | --- |
|
||
| `file` | Binary file |
|
||
| `supportingContext`, `date` | Plain strings |
|
||
| `metadata`, `group` | JSON-encoded strings |
|
||
| `fileType`, `mimeType` | Query parameters when inference is insufficient |
|
||
|
||
The API acknowledges the file after durable acceptance, with `status` set as for a JSON add. Extraction, indexing, and memory formation continue asynchronously; poll the document rather than assuming the first response means processing is complete.
|
||
|
||
### Processing choices
|
||
|
||
- `taskType=memory` extracts long-term memories; `taskType=superrag` indexes source context without memory generation.
|
||
- `dreaming=dynamic` (default) groups related documents into coherent memory units.
|
||
- `dreaming=instant` processes each document independently and bills one extra operation per document.
|
||
|
||
### Verification
|
||
|
||
- Ingest text, a public URL, and a file, then wait for each document to finish processing.
|
||
- Repeat a caller-defined ID and confirm append/diff behavior instead of replacement.
|
||
- Submit a mixed-success batch and verify each result matches its document by ID, with per-item errors.
|
||
- Confirm metadata and grouping remain filterable after processing.
|