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.
107 lines
6.2 KiB
Text
107 lines
6.2 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 such as `client.search.execute`, `client.profile`, and `client.connections.*`.
|
|
</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>
|
|
|
|
## Upgrade the SDK
|
|
|
|
The v5 TypeScript SDK ships as the same `supermemory` package. Install it, then replace the legacy client:
|
|
|
|
```bash
|
|
npm i supermemory
|
|
```
|
|
|
|
<CodeGroup>
|
|
```ts Legacy
|
|
import Supermemory from "supermemory"
|
|
|
|
const client = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY })
|
|
await client.add({ content: "new turn", containerTag: "user_1" })
|
|
```
|
|
|
|
```ts v5
|
|
import { Supermemory } from "supermemory"
|
|
|
|
const supermemory = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY })
|
|
await supermemory.add("user_1", { content: "new turn" })
|
|
```
|
|
</CodeGroup>
|
|
|
|
Every v5 call takes one object. `namespace`, path IDs, and query parameters are top-level keys; the JSON body goes under `body`. Legacy `containerTag` never appears in a body again. There is no v5 Python SDK yet.
|
|
|
|
## Endpoint map
|
|
|
|
| Legacy | v5 | SDK method |
|
|
| --- | --- | --- |
|
|
| `POST /v3/documents` | `POST /ns/{namespace}/document` | `supermemory.add` |
|
|
| `POST /v3/documents/batch` | `POST /ns/{namespace}/document/batch` | `supermemory.documents.batchAdd` |
|
|
| `POST /v3/documents/file` | `POST /ns/{namespace}/document/file` | `supermemory.documents.uploadFile` |
|
|
| `GET/PATCH /v3/documents/{id}` | `GET/PATCH /ns/{namespace}/document/{id}` | `supermemory.documents.get` / `supermemory.documents.update` |
|
|
| File replace or partial file update | `POST/PATCH /ns/{namespace}/document/file/{id}` | `supermemory.documents.replaceWithFile` / `supermemory.documents.updateFile` |
|
|
| Single or bulk document delete | `DELETE /ns/{namespace}/document` | `supermemory.documents.delete` |
|
|
| Legacy document or memory lists | `POST /ns/{namespace}/list/{type}` | `supermemory.list` |
|
|
| `POST /v3/search` or `/v4/search` | `POST /ns/{namespace}/search` | `supermemory.search` |
|
|
| `POST /v4/profile` | `POST /ns/{namespace}/profile` | `supermemory.profile` |
|
|
| `POST /v4/profile/buckets` | `GET/PUT/DELETE /ns/{namespace}/profile/buckets` | `supermemory.profiles.getBuckets` / `setBuckets` / `deleteBuckets` |
|
|
| Legacy memory forget routes | `DELETE /ns/{namespace}/memories...` | `supermemory.memories.forget` / `supermemory.memories.forgetMatching` |
|
|
| Container-tag settings and lifecycle | `/namespaces` and `/ns/{namespace}` | `supermemory.namespaces.list` / `get` / `update` / `delete` |
|
|
| `GET/PATCH /v3/settings` | `GET/PATCH /organization` | `supermemory.organization.get` / `update` |
|
|
|
|
### Connectors
|
|
|
|
Connector routes also move under the namespace. Legacy `containerTags` arrays become one namespace per connector.
|
|
|
|
| Legacy | v5 | SDK method |
|
|
| --- | --- | --- |
|
|
| `POST /v3/connections/list` | `GET /ns/{namespace}/connectors` or `GET /connectors` | `supermemory.connectors.list` / `supermemory.connectors.listAll` |
|
|
| `POST /v3/connections/{provider}` | `POST /ns/{namespace}/connectors` | `supermemory.connectors.create` |
|
|
| `GET /v3/connections/{connectionId}` | `GET /ns/{namespace}/connectors/{id}` | `supermemory.connectors.get` |
|
|
| `POST /v3/connections/{connectionId}/configure` | `PATCH /ns/{namespace}/connectors/{id}` | `supermemory.connectors.update` |
|
|
| `DELETE /v3/connections/{connectionId}` | `DELETE /ns/{namespace}/connectors/{id}` | `supermemory.connectors.delete` |
|
|
| `POST /v3/connections/{provider}/import` | `POST /ns/{namespace}/connectors/{id}/sync` | `supermemory.connectors.sync` |
|
|
|
|
<CodeGroup>
|
|
```ts Legacy
|
|
const connection = await client.connections.create("notion", {
|
|
containerTags: ["user_1"],
|
|
redirectUrl: "https://app.example.com/connected",
|
|
})
|
|
```
|
|
|
|
```ts v5
|
|
const { id, authorization } = await supermemory.connectors.create("user_1", {
|
|
provider: "notion",
|
|
redirectUrl: "https://app.example.com/connected"
|
|
})
|
|
```
|
|
</CodeGroup>
|
|
|
|
`authorization` is `null` for config providers (`web-crawler`, `s3`, `granola`), which start syncing immediately. `connectors.sync` returns `{ id, status: "queued" }` and `409` when a sync is already running.
|