mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-11-05 07:39:44 +00:00
5dd459e9f7
Align API, guide, SDK, plugin, tools and billing pages with the live code in mono, sdk-ts, python-sdk, the plugin repos, smfs and memorybench. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
90 lines
3.8 KiB
Text
90 lines
3.8 KiB
Text
v5 renames the public isolation boundary from container tag to namespace. Existing values remain valid identifiers; no stored data rename is required.
|
|
|
|
### Endpoint mapping
|
|
|
|
| Legacy | v5 |
|
|
| --- | --- |
|
|
| `GET /v3/container-tags/list` | `GET /namespaces` |
|
|
| `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}?moveTo=target` |
|
|
|
|
`GET /ns` is an alias for `GET /namespaces`. Prefer `/namespaces` in new integrations.
|
|
|
|
### List namespaces
|
|
|
|
The list is paginated: `GET /namespaces?page=1&limit=10` returns `{namespaces, pagination}`, newest first, with `limit` up to 100. Add `q` to keep only namespaces whose name contains that text, case-insensitively. Each entry now exposes `id`, `namespace`, `documentCount`, `memoryCount`, nullable `description`, and `system.createdAt/updatedAt`. Update readers that still expect `containerTag`, flat timestamps, or unbounded internal settings.
|
|
|
|
### Read and update settings
|
|
|
|
<CodeGroup>
|
|
```bash Legacy
|
|
PATCH /v3/container-tags/project_alpha
|
|
{"entityContext":"Research project for distributed systems"}
|
|
```
|
|
|
|
```bash v5
|
|
PATCH /ns/project_alpha
|
|
{"supportingContext":"Research project for distributed systems"}
|
|
```
|
|
</CodeGroup>
|
|
|
|
The public GET and PATCH shapes contain only `namespace`, `supportingContext`, and lifecycle timestamps. Profile buckets have their own `/profile/buckets` resource and are not namespace settings.
|
|
|
|
Send `supportingContext: null` to remove existing context. Omitting the field entirely is invalid because PATCH requires at least one supported setting.
|
|
|
|
### Permanently delete a namespace
|
|
|
|
```bash
|
|
DELETE /ns/project_alpha
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
`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 takes exactly two tags and can merge both into a new target; v5 moves one source namespace per request. Run multi-source migrations sequentially and record each operation independently.
|
|
|
|
### With the SDK
|
|
|
|
Replace calls to `/v3/container-tags/*` with `supermemory.namespaces`:
|
|
|
|
<CodeGroup>
|
|
```bash Legacy
|
|
GET /v3/container-tags/list
|
|
PATCH /v3/container-tags/project_alpha
|
|
DELETE /v3/container-tags/project_alpha
|
|
```
|
|
|
|
```ts v5
|
|
const { namespaces } = await supermemory.namespaces.list()
|
|
const one = await supermemory.namespaces.get("project_alpha")
|
|
|
|
await supermemory.namespaces.update("project_alpha", {
|
|
supportingContext: "Research project for distributed systems",
|
|
})
|
|
|
|
await supermemory.namespaces.delete("project_alpha")
|
|
|
|
await supermemory.namespaces.delete("project_alpha", {
|
|
moveTo: "project_archive",
|
|
})
|
|
```
|
|
</CodeGroup>
|
|
|
|
`namespaces.list()` returns `{ namespaces, pagination }`, where each namespace is `{ id, namespace, documentCount, memoryCount, description, system }`. A delete without `moveTo` returns `{ status: "deleted", namespace, deletedDocumentsCount, deletedMemoriesCount }`; with `moveTo` it returns `{ status: "queued", operationId, namespace, moveTo }`.
|
|
|
|
### Verification
|
|
|
|
- Confirm existing container-tag values resolve unchanged as namespace paths.
|
|
- Compare namespace counts with namespace-scoped document and memory lists.
|
|
- Verify a permanent delete returns final counts while a move returns `202`.
|
|
- Verify restricted callers cannot read or mutate namespaces outside their scope.
|
|
- Verify only organization-authorized callers can change settings or lifecycle.
|