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)
101 lines
4.3 KiB
Text
101 lines
4.3 KiB
Text
v5 makes the difference between adding new information and replacing the canonical source explicit.
|
|
|
|
### Choose the correct write
|
|
|
|
| Intent | Operation | Content behavior |
|
|
| --- | --- | --- |
|
|
| Add information to a stable caller ID | `POST /ns/{namespace}/document` | Append/diff |
|
|
| Replace text or URL content | `PATCH /ns/{namespace}/document/{id}` | Replace and reprocess |
|
|
| Update only metadata, context, or date | Same `PATCH` without `content` | Canonical content unchanged |
|
|
| Replace a source file and its user metadata | `POST /ns/{namespace}/document/file/{id}` | Full replacement and reprocess |
|
|
| Partially update a file or its supporting fields | `PATCH /ns/{namespace}/document/file/{id}` | Omitted fields remain unchanged |
|
|
|
|
### Update text or URL content
|
|
|
|
<CodeGroup>
|
|
```bash Legacy
|
|
PATCH /v3/documents/doc_1
|
|
{"content":"corrected source","metadata":{"revision":2}}
|
|
```
|
|
|
|
```bash v5
|
|
PATCH /ns/user_1/document/doc_1
|
|
{"content":"corrected source","metadata":{"revision":2},"dreaming":"dynamic"}
|
|
```
|
|
</CodeGroup>
|
|
|
|
The v5 body accepts any non-empty subset of `content`, `supportingContext`, `metadata`, or `date`, plus optional `taskType` and `dreaming` (which alone do not count as a change). `group` is an ingestion-side setting: it picks which existing memories serve as context while content is processed, so changing it only takes effect when the document is re-ingested. Send it together with `content`. Supplying `content` makes it the new canonical source; facts supported only by the previous source can disappear after reprocessing.
|
|
|
|
### Replace a file-backed document
|
|
|
|
```bash
|
|
POST /ns/user_1/document/file/doc_1
|
|
Content-Type: multipart/form-data
|
|
|
|
file=@corrected.pdf
|
|
metadata={"revision":2}
|
|
dreaming=dynamic
|
|
```
|
|
|
|
POST requires `file` and replaces the canonical source plus caller metadata, including `date`. Omitted metadata and date are cleared. `supportingContext` is stored on the namespace, so omitting it leaves the namespace's existing context unchanged. Use it when the submitted request is the complete new representation of the file-backed document.
|
|
|
|
### Partially update a file-backed document
|
|
|
|
```bash
|
|
PATCH /ns/user_1/document/file/doc_1
|
|
Content-Type: multipart/form-data
|
|
|
|
metadata={"reviewed":true}
|
|
dreaming=dynamic
|
|
```
|
|
|
|
PATCH changes only supplied fields. Include `file` to replace the source while retaining omitted supporting fields, or omit `file` for metadata-, context-, or date-only changes. Like the JSON update, `group` only takes effect when the file is re-ingested, so send it together with `file`. `metadata` and `group` are JSON-encoded strings; `supportingContext` and `date` are plain strings.
|
|
|
|
<Warning>
|
|
There is no public v5 `PUT /ns/{namespace}/document/file/{id}` operation. Use POST for a complete replacement and PATCH for a partial update.
|
|
</Warning>
|
|
|
|
### With the SDK
|
|
|
|
<CodeGroup>
|
|
```ts Legacy
|
|
await client.documents.update("doc_1", {
|
|
content: "corrected source",
|
|
metadata: { revision: 2 },
|
|
})
|
|
```
|
|
|
|
```ts v5
|
|
await supermemory.documents.update("user_1", "doc_1", {
|
|
content: "corrected source",
|
|
metadata: { revision: 2 },
|
|
})
|
|
|
|
await supermemory.documents.replaceWithFile("user_1", "doc_1", {
|
|
file,
|
|
metadata: JSON.stringify({ revision: 2 }),
|
|
})
|
|
|
|
await supermemory.documents.updateFile("user_1", "doc_1", {
|
|
metadata: JSON.stringify({ reviewed: true }),
|
|
})
|
|
```
|
|
</CodeGroup>
|
|
|
|
`replaceWithFile` is the POST full replacement and requires `file`. `updateFile` is the PATCH partial update; `file` is optional and metadata merges key by key.
|
|
|
|
### IDs and scope
|
|
|
|
The path `id` may be the Supermemory document ID or your caller-defined ID. It is resolved only inside `{namespace}`; an ID from another namespace is not a cross-namespace update mechanism.
|
|
|
|
### Processing and conflicts
|
|
|
|
Content or file replacement is accepted before downstream processing completes. A namespace merge in progress or a conflicting internal file path returns `409`; retry a merge conflict after the merge finishes.
|
|
|
|
### Verification
|
|
|
|
- Patch metadata alone and confirm document content and derived facts remain intact.
|
|
- Patch content and confirm the new source is canonical after processing.
|
|
- Replace a file with POST and confirm omitted user metadata is cleared.
|
|
- Patch a file-backed document and confirm omitted fields remain unchanged.
|
|
- Attempt the same ID in another namespace and confirm the update is rejected or not found.
|