mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-11 03:37:56 +00:00
ef5a085a76
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.
49 lines
3.3 KiB
Text
49 lines
3.3 KiB
Text
## Migrate by hand
|
|
|
|
<Warning>
|
|
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.
|
|
|
|
**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
|
|
|
|
<Steps>
|
|
<Step title="Inventory every legacy call">
|
|
Search for `/v3/`, `/v4/`, `containerTag`, `containerTags`, `customId`, `entityContext`, `filterByMetadata`, `filters`, and legacy SDK methods.
|
|
</Step>
|
|
<Step title="Resolve one namespace per request">
|
|
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](/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](/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.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Endpoint map
|
|
|
|
| Legacy | v5 |
|
|
| --- | --- |
|
|
| `POST /v3/documents` | `POST /ns/{namespace}/document` |
|
|
| `POST /v3/documents/batch` | `POST /ns/{namespace}/document/batch` |
|
|
| `POST /v3/documents/file` | `POST /ns/{namespace}/document/file` |
|
|
| `GET/PATCH /v3/documents/{id}` | `GET/PATCH /ns/{namespace}/document/{id}` |
|
|
| Single or bulk document delete | `DELETE /ns/{namespace}/document` |
|
|
| Legacy document or memory lists | `POST /ns/{namespace}/list/{type}` |
|
|
| `POST /v3/search` or `/v4/search` | `POST /ns/{namespace}/search` |
|
|
| `POST /v4/profile` | `POST /ns/{namespace}/profile` |
|
|
| `POST /v4/profile/buckets` | `GET /ns/{namespace}/profile/buckets` |
|
|
| Legacy memory forget routes | `DELETE /ns/{namespace}/memories...` |
|
|
| Container-tag settings and lifecycle | `/namespaces` and `/ns/{namespace}` |
|
|
| `GET/PATCH /v3/settings` | `GET/PATCH /organization` |
|