diff --git a/apps/docs/snippets/api-v5-content-management.mdx b/apps/docs/snippets/api-v5-content-management.mdx index 362385d1..8aa0e8db 100644 --- a/apps/docs/snippets/api-v5-content-management.mdx +++ b/apps/docs/snippets/api-v5-content-management.mdx @@ -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 diff --git a/apps/docs/snippets/api-v5-document-ingestion.mdx b/apps/docs/snippets/api-v5-document-ingestion.mdx index 87b0a983..661dfd74 100644 --- a/apps/docs/snippets/api-v5-document-ingestion.mdx +++ b/apps/docs/snippets/api-v5-document-ingestion.mdx @@ -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"} ``` @@ -39,7 +39,7 @@ The response remains an acceptance result with `id` and `status`. Its `status` i ``` -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 diff --git a/apps/docs/snippets/api-v5-document-updates.mdx b/apps/docs/snippets/api-v5-document-updates.mdx index 5f9a3192..843ed72b 100644 --- a/apps/docs/snippets/api-v5-document-updates.mdx +++ b/apps/docs/snippets/api-v5-document-updates.mdx @@ -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"} ``` -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. diff --git a/apps/docs/snippets/api-v5-namespaces.mdx b/apps/docs/snippets/api-v5-namespaces.mdx index 0fdde3a7..97894226 100644 --- a/apps/docs/snippets/api-v5-namespaces.mdx +++ b/apps/docs/snippets/api-v5-namespaces.mdx @@ -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. diff --git a/apps/docs/snippets/api-v5-overview.mdx b/apps/docs/snippets/api-v5-overview.mdx index 2239a314..931b9aeb 100644 --- a/apps/docs/snippets/api-v5-overview.mdx +++ b/apps/docs/snippets/api-v5-overview.mdx @@ -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. -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. - 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. Migrate envelopes, includes, pagination, profile buckets, system fields, and partial-error handling before switching traffic. - 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. Switch traffic, monitor failures and semantic drift, then remove legacy compatibility code only after that domain passes verification.