mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-11 03:37:56 +00:00
672defc08b
Rewrites 339 TypeScript calls across 50 pages from the rc.5 `method({ namespace, body })` form to the shipped `method(namespace, { ... })` form, and aligns field names with the live v5 spec: `attach` to `include`, `authUrl` to `authorization`, `lastSync` to `latestRun`, `deletedCount` to `count`, and the paginated `namespaces.list()`.
Renames container tags to namespaces across concepts, connectors, integrations and snippets. The namespace pages keep container tag in the description, search keywords and a rename note so old searches still land, and the v3 reference page points at v5.
The migration guide's SDK table now covers both 5.0.0 SDKs, and the SDK integration page uses the real client options (`baseUrl`, `timeoutInSeconds`, `maxRetries`) and error classes.
101 lines
3.9 KiB
Text
101 lines
3.9 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 supporting fields | 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`, `group`, or `date`, plus optional `taskType` and `dreaming` (which alone do not count as a change). 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 user-controlled metadata, grouping, context, and date. Omitted supporting fields are cleared. 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-, group-, context-, or date-only changes. `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 document still processing, a namespace conflict, or a conflicting internal file path can return `409`; retry only after the conflicting operation reaches a terminal state.
|
|
|
|
### 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.
|