mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-11 03:37:56 +00:00
47 lines
2.7 KiB
Text
47 lines
2.7 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. 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](./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.
|
|
</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.
|
|
</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` |
|