mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-07 02:58:11 +00:00
docs(api): document v5 parameter placement (#1770)
Docs for supermemoryai/mono#3421: ingest `taskType`/`dreaming` move into the JSON body (form fields on file routes, alongside `fileType`/`mimeType`); namespace delete takes `moveTo` as a query param and rejects a body. Adds a "where parameters live" rule to the migration overview.
This commit is contained in:
sohamd22
parent
5c24e67d60
commit
ef5a085a76
5 changed files with 28 additions and 23 deletions
|
|
@ -66,7 +66,7 @@ The v5 array accepts 1–100 Supermemory or caller-defined IDs. Inspect both `co
|
|||
|
||||
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.
|
||||
See [memory forgetting](/migration/api-v5-memory-forgetting) for the complete dry-run, approval, response, and audit workflow.
|
||||
|
||||
### Verification
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ v5 moves document scope into the URL and keeps repeated caller IDs attached to o
|
|||
| `entityContext` | `supportingContext` | JSON/form body |
|
||||
| `filterByMetadata` | `group` | JSON/form body |
|
||||
| `documentDate` | `date` | JSON/form body |
|
||||
| `taskType`, `dreaming` | unchanged | Query string |
|
||||
| `taskType`, `dreaming` | unchanged | JSON/form body |
|
||||
|
||||
### Add or append one document
|
||||
|
||||
|
|
@ -20,8 +20,8 @@ POST /v3/documents
|
|||
```
|
||||
|
||||
```bash v5
|
||||
POST /ns/user_1/document?dreaming=dynamic
|
||||
{"content":"new turn","id":"conv_1"}
|
||||
POST /ns/user_1/document
|
||||
{"content":"new turn","id":"conv_1","dreaming":"dynamic"}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
|
|
@ -39,7 +39,7 @@ The response remains an acceptance result with `id` and `status`. Its `status` i
|
|||
```
|
||||
</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.
|
||||
Send the v5 body to `POST /ns/user_1/document/batch`. The array accepts 1–600 document objects. `taskType` and `dreaming` sit at the top level of the body, next to `documents`, and apply to every item; 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.
|
||||
|
||||
|
|
@ -52,15 +52,18 @@ Replace `POST /v3/documents/file` with `POST /ns/{namespace}/document/file`. Con
|
|||
| `file` | Binary file |
|
||||
| `supportingContext`, `date` | Plain strings |
|
||||
| `metadata`, `group` | JSON-encoded strings |
|
||||
| `fileType`, `mimeType` | Query parameters when inference is insufficient |
|
||||
| `taskType`, `dreaming` | Plain strings |
|
||||
| `fileType`, `mimeType` | Plain strings, only 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.
|
||||
- `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.
|
||||
|
||||
These options go in the JSON body (or as form fields for file routes). Ingest routes take no query parameters; sending one returns `400`.
|
||||
|
||||
### Verification
|
||||
|
||||
|
|
|
|||
|
|
@ -19,21 +19,22 @@ PATCH /v3/documents/doc_1
|
|||
```
|
||||
|
||||
```bash v5
|
||||
PATCH /ns/user_1/document/doc_1?dreaming=dynamic
|
||||
{"content":"corrected source","metadata":{"revision":2}}
|
||||
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`. Supplying `content` makes it the new canonical source; facts supported only by the previous source can disappear after reprocessing.
|
||||
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?dreaming=dynamic
|
||||
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.
|
||||
|
|
@ -41,10 +42,11 @@ POST requires `file` and replaces the canonical source plus user-controlled meta
|
|||
### Partially update a file-backed document
|
||||
|
||||
```bash
|
||||
PATCH /ns/user_1/document/file/doc_1?dreaming=dynamic
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ v5 renames the public isolation boundary from container tag to namespace. Existi
|
|||
| `GET /v3/container-tags/{tag}` | `GET /ns/{namespace}` |
|
||||
| `PATCH /v3/container-tags/{tag}` | `PATCH /ns/{namespace}` |
|
||||
| `DELETE /v3/container-tags/{tag}` | `DELETE /ns/{namespace}` |
|
||||
| Merge container tags | `DELETE /ns/{source}` with `{ "moveTo": "target" }` |
|
||||
| Merge container tags | `DELETE /ns/{source}?moveTo=target` |
|
||||
|
||||
`GET /ns` is an alias for `GET /namespaces`. Prefer `/namespaces` in new integrations.
|
||||
|
||||
|
|
@ -38,19 +38,17 @@ Send `supportingContext: null` to remove existing context. Omitting the field en
|
|||
|
||||
```bash
|
||||
DELETE /ns/project_alpha
|
||||
{}
|
||||
```
|
||||
|
||||
With no `moveTo`, deletion is synchronous and returns `200` with `deletedDocumentsCount` and `deletedMemoriesCount`. This removes the namespace and its content.
|
||||
With no `moveTo`, deletion is synchronous and returns `200` with `status: "deleted"`, `deletedDocumentsCount`, and `deletedMemoriesCount`. Branch on `status` (`deleted` or `queued`) to tell the two outcomes apart. This removes the namespace and its content.
|
||||
|
||||
### Move then remove a namespace
|
||||
|
||||
```bash
|
||||
DELETE /ns/project_alpha
|
||||
{"moveTo":"project_archive"}
|
||||
DELETE /ns/project_alpha?moveTo=project_archive
|
||||
```
|
||||
|
||||
This returns `202` with `status: "queued"` and `operationId`. The destination must differ from the source. Do not treat acceptance as completed migration.
|
||||
`moveTo` is a query parameter. This returns `202` with `status: "queued"` and `operationId`. The destination must differ from the source. Do not treat acceptance as completed migration.
|
||||
|
||||
Legacy merge can accept multiple sources; v5 moves one source per request. Run multi-source migrations sequentially and record each operation independently.
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,9 @@
|
|||
This is a breaking API migration. Do not change only the URL: fields moved, search defaults changed, response envelopes changed, and some legacy operations have no v5 replacement.
|
||||
</Warning>
|
||||
|
||||
The API base URL and bearer keys do not change. v5 application routes are unversioned; [`/v5/reference`](https://api.supermemory.ai/v5/reference) is the interactive v5 reference, not an API path prefix.
|
||||
The API base URL and bearer keys do not change.
|
||||
|
||||
**Where parameters live:** `GET` options go in the query string. `POST`, `PATCH`, and `PUT` options go in the JSON body, or as form fields on file uploads; the one exception is list pagination (`page`, `limit`, `sort`, `order`), which stays in the query string. `DELETE` options such as `moveTo` go in the query string, while bulk deletes send their `ids` in the JSON body. Routes reject options sent in the wrong place with `400`. v5 application routes are unversioned; [`/v5/reference`](https://api.supermemory.ai/v5/reference) is the interactive v5 reference, not an API path prefix.
|
||||
|
||||
## Recommended migration process
|
||||
|
||||
|
|
@ -16,13 +18,13 @@ The API base URL and bearer keys do not change. v5 application routes are unvers
|
|||
Move the legacy `containerTag` into `/ns/{namespace}`. Never infer scope from a document or memory ID, and never send multiple namespaces to one v5 request.
|
||||
</Step>
|
||||
<Step title="Translate requests by domain">
|
||||
Apply [ingestion](./api-v5-document-writes), [updates](./api-v5-document-updates), [content management](./api-v5-document-reads), [search](./api-v5-recall), [profiles](./api-v5-profiles), [forgetting](./api-v5-memory-forgetting), [namespaces](./api-v5-settings), [organization](./api-v5-organization), and [filter](./api-v5-filters) changes independently.
|
||||
Apply [ingestion](/migration/api-v5-document-writes), [updates](/migration/api-v5-document-updates), [content management](/migration/api-v5-document-reads), [search](/migration/api-v5-recall), [profiles](/migration/api-v5-profiles), [forgetting](/migration/api-v5-memory-forgetting), [namespaces](/migration/api-v5-settings), [organization](/migration/api-v5-organization), and [filter](/migration/api-v5-filters) changes independently.
|
||||
</Step>
|
||||
<Step title="Update response readers">
|
||||
Migrate envelopes, includes, pagination, profile buckets, system fields, and partial-error handling before switching traffic.
|
||||
</Step>
|
||||
<Step title="Verify legacy and v5 side by side">
|
||||
Follow the [verification and rollout guide](./api-v5-rollout). Compare identity and behavior—not raw JSON ordering—and set changed defaults explicitly during rollout.
|
||||
Follow the [verification and rollout guide](/migration/api-v5-rollout). Compare identity and behavior—not raw JSON ordering—and set changed defaults explicitly during rollout.
|
||||
</Step>
|
||||
<Step title="Cut over one domain at a time">
|
||||
Switch traffic, monitor failures and semantic drift, then remove legacy compatibility code only after that domain passes verification.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue