> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate container tags to namespaces

> Upgrade namespace discovery, settings, deletion, and moves

## Migration details

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. 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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  PATCH /v3/container-tags/project_alpha
  {"entityContext":"Research project for distributed systems"}
  ```

  ```bash v5 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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 can accept multiple sources; v5 moves one source 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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  GET /v3/container-tags/list
  PATCH /v3/container-tags/project_alpha
  DELETE /v3/container-tags/project_alpha
  ```

  ```ts v5 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.