> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-soham-v5-docs-attach-to-include.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate Supermemory v3/v4 to v5

> Upgrade legacy API calls to the namespace-scoped v5 API

## Migrate with an agent

Paste this into Claude Code, Cursor, or Codex. It fetches this guide as markdown and rewrites every legacy call.

```text theme={null}
Migrate this repository from Supermemory v3/v4 to v5. Fetch https://supermemory.ai/docs/migration/api-v5.md and follow it exactly. First write a checklist of every legacy call site, then migrate them one by one and tick each off. Stop and report any operation that has no v5 replacement instead of inventing one.
```

## 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` |

## SDKs, tools and the CLI

Check which client you call the API through before you translate requests. Not every client supports v5 yet.

| Client | v5 support | What to do |
| - | - | - |
| TypeScript SDK (`supermemory` on npm) | `5.0.0-rc.5` and later | Install `supermemory@rc` and follow the SDK changes below. Release candidates before `rc.5` still use the v3/v4 surface. |
| Python SDK (`supermemory` on PyPI) | Not yet | The 3.x SDK calls v3/v4. Call v5 over HTTP as shown in this guide, or keep the SDK on v3/v4 until a v5 release ships. |
| `@supermemory/tools` (AI SDK, OpenAI and agent integrations) | Not yet | These call v3/v4 (`/v4/profile`, `/v4/conversations`). No change needed today. |
| CLI (`npx supermemory`) and `supermemory local` | Unchanged | The CLI calls v3/v4 directly and keeps working. No change needed. |

### TypeScript SDK changes

The v5 SDK scopes every content call to one `namespace` and moves the payload under `body`:

```ts theme={null}
import Supermemory from "supermemory";

const client = new Supermemory(); // reads SUPERMEMORY_API_KEY, as before

// v4
await client.add({ content: "Alex prefers morning meetings.", containerTag: "user_alex" });

// v5
await client.add({
  namespace: "user_alex",
  body: { content: "Alex prefers morning meetings." },
});
```

| v4 | v5 |
| - | - |
| `client.search.memories({ q, containerTag })` | `client.search({ namespace, body: { query } })` |
| `client.profile({ containerTag, q })` | `client.profile({ namespace })`, plus `client.search` in parallel if you need results |
| `client.documents.list(...)`, `client.memories.list(...)` | `client.list({ namespace, type })` |
| `client.containerTags.*` | `client.namespaces.*` |
| `client.settings.{get, update}` | `client.organization.{get, update}` |
| Errors per status (`RateLimitError`, …) | One `SupermemoryError`; branch on `statusCode` |
| Retries on by default | Retries are opt-in through `retryConfig` |
| `timeout` | `timeoutMs` |

The v5 SDK drops methods that have no v5 endpoint: `connections`, `conversations.add`, `settings.{reset, suggestBuckets}`, `containerTags.{merge, mergeStatus}`, `memories.{add, updateMemory}`, and `documents.{listProcessing, chunks, fileUrl, search}`. Stay on `supermemory@4` for those calls.

The full method map is in the SDK's [migration guide](https://github.com/supermemoryai/sdk-ts/blob/main/MIGRATION.md).

## Document ingestion

v5 moves document scope into the URL and keeps repeated caller IDs attached to one evolving document.

### Rename common fields

| Legacy | v5 | Location |
| - | - | - |
| `containerTag` | `{namespace}` | Path |
| `customId` | `id` | JSON body |
| `entityContext` | `supportingContext` | JSON/form body |
| `filterByMetadata` | `group` | JSON/form body |
| `documentDate` | `date` | JSON/form body |
| `taskType`, `dreaming` | unchanged | Query string |

### Add or append one document

<CodeGroup>
  ```bash Legacy theme={null}
  POST /v3/documents
  {"content":"new turn","customId":"conv_1","containerTag":"user_1"}
  ```

  ```bash v5 theme={null}
  POST /ns/user_1/document?dreaming=dynamic
  {"content":"new turn","id":"conv_1"}
  ```
</CodeGroup>

The response remains an acceptance result with `id` and `status`. Repeating the v5 request with `id: "conv_1"` adds or diffs the new content into that document; it does not silently replace the canonical source.

### Batch ingestion

<CodeGroup>
  ```json Legacy theme={null}
  {"documents":["first","second"],"containerTag":"user_1"}
  ```

  ```json v5 theme={null}
  {"documents":[{"content":"first","id":"doc_1"},{"content":"second","id":"doc_2"}]}
  ```
</CodeGroup>

Send the v5 body to `POST /ns/user_1/document/batch`. The array accepts 1–600 document objects. Namespace, `taskType`, and processing mode apply to the request; document content, ID, context, metadata, grouping, and date stay per item.

Batch results preserve input order. Inspect `success`, `failed`, and every item in `results`; a batch can contain successful and failed items together.

### File ingestion

Replace `POST /v3/documents/file` with `POST /ns/{namespace}/document/file`. Continue using `multipart/form-data`:

| Part | Encoding |
| - | - |
| `file` | Binary file |
| `supportingContext`, `date` | Plain strings |
| `metadata`, `group` | JSON-encoded strings |
| `fileType`, `mimeType` | Query parameters when inference is insufficient |

The API acknowledges the file after durable acceptance. Extraction, indexing, and memory formation continue asynchronously; poll the document rather than assuming the first response means processing is complete.

### Processing choices

* `taskType=memory` extracts long-term memories; `taskType=superrag` indexes source context without memory generation.
* `dreaming=dynamic` (default) groups related documents into coherent memory units.
* `dreaming=instant` processes each document independently and bills one extra operation per document.

### Verification

* Ingest text, a public URL, and a file, then wait for each document to finish processing.
* Repeat a caller-defined ID and confirm append/diff behavior instead of replacement.
* Submit a mixed-success batch and verify result order and per-item errors.
* Confirm metadata and grouping remain filterable after processing.

## Document updates

v5 makes the difference between adding new information and replacing the canonical source explicit.

### Choose the correct write

| Intent | Operation | Content behavior |
| - | - | - |
| Add information to a stable caller ID | `POST /ns/{namespace}/document` | Append/diff |
| Replace text or URL content | `PATCH /ns/{namespace}/document/{id}` | Replace and reprocess |
| Update only supporting fields | Same `PATCH` without `content` | Canonical content unchanged |
| Replace a source file and its user metadata | `POST /ns/{namespace}/document/file/{id}` | Full replacement and reprocess |
| Partially update a file or its supporting fields | `PATCH /ns/{namespace}/document/file/{id}` | Omitted fields remain unchanged |

### Update text or URL content

<CodeGroup>
  ```bash Legacy theme={null}
  PATCH /v3/documents/doc_1
  {"content":"corrected source","metadata":{"revision":2}}
  ```

  ```bash v5 theme={null}
  PATCH /ns/user_1/document/doc_1?dreaming=dynamic
  {"content":"corrected source","metadata":{"revision":2}}
  ```
</CodeGroup>

The v5 body accepts any non-empty subset of `content`, `supportingContext`, `metadata`, `group`, or `date`. Supplying `content` makes it the new canonical source; facts supported only by the previous source can disappear after reprocessing.

### Replace a file-backed document

```bash theme={null}
POST /ns/user_1/document/file/doc_1?dreaming=dynamic
Content-Type: multipart/form-data

file=@corrected.pdf
metadata={"revision":2}
```

POST requires `file` and replaces the canonical source plus user-controlled metadata, grouping, context, and date. Omitted supporting fields are cleared. Use it when the submitted request is the complete new representation of the file-backed document.

### Partially update a file-backed document

```bash theme={null}
PATCH /ns/user_1/document/file/doc_1?dreaming=dynamic
Content-Type: multipart/form-data

metadata={"reviewed":true}
```

PATCH changes only supplied fields. Include `file` to replace the source while retaining omitted supporting fields, or omit `file` for metadata-, group-, context-, or date-only changes. `metadata` and `group` are JSON-encoded strings; `supportingContext` and `date` are plain strings.

<Warning>
  There is no public v5 `PUT /ns/{namespace}/document/file/{id}` operation. Use POST for a complete replacement and PATCH for a partial update.
</Warning>

### IDs and scope

The path `id` may be the Supermemory document ID or your caller-defined ID. It is resolved only inside `{namespace}`; an ID from another namespace is not a cross-namespace update mechanism.

### Processing and conflicts

Content or file replacement is accepted before downstream processing completes. A document still processing, a namespace conflict, or a conflicting internal file path can return `409`; retry only after the conflicting operation reaches a terminal state.

### Verification

* Patch metadata alone and confirm document content and derived facts remain intact.
* Patch content and confirm the new source is canonical after processing.
* Replace a file with POST and confirm omitted user metadata is cleared.
* Patch a file-backed document and confirm omitted fields remain unchanged.
* Attempt the same ID in another namespace and confirm the update is rejected or not found.

## Content management

v5 retrieves, lists, and removes content within one explicit namespace.

### Retrieve a document and its derived context

<CodeGroup>
  ```bash Legacy theme={null}
  GET /v3/documents/{id}
  GET /v3/documents/{id}/chunks
  ```

  ```bash v5 theme={null}
  GET /ns/{namespace}/document/{id}?include=chunks,memories
  ```
</CodeGroup>

Pass `include` as a comma-separated list to return chunks, memories, or both. Keys you omit are absent; requested keys with no results are empty arrays. Lifecycle fields move under `system`:

```json theme={null}
{"system":{"status":"done","createdAt":"...","updatedAt":"..."}}
```

### List documents, chunks, or memories

<CodeGroup>
  ```bash Legacy theme={null}
  POST /v3/documents/list
  POST /v4/memories/list
  ```

  ```bash v5 theme={null}
  POST /ns/{namespace}/list/{type}?page=1&limit=100&sort=createdAt&order=desc
  {}
  ```
</CodeGroup>

Set `type` to `documents`, `chunks`, or `memories`. Pagination and sorting move to the query string; the body contains only optional `filter`.

Every response contains `documents`, `chunks`, `memories`, and `pagination`. Only the selected resource array is populated. Replace legacy `memories` assumptions in document-list callers with `documents`.

### Delete documents

<CodeGroup>
  ```bash Legacy theme={null}
  DELETE /v3/documents/{id}
  DELETE /v3/documents/bulk
  ```

  ```bash v5 theme={null}
  DELETE /ns/{namespace}/document
  {"ids":["doc_1","external_id_2"]}
  ```
</CodeGroup>

The v5 array accepts 1–100 Supermemory or caller-defined IDs. Inspect both `deletedCount` and per-ID `errors`; HTTP success can include partial failures.

### Forget memories

| Legacy intent | v5 operation |
| - | - |
| Forget exact IDs | `DELETE /ns/{namespace}/memories` with `{ "ids": [...] }` |
| Find memories by meaning | `DELETE /ns/{namespace}/memories/semantic` with `{ "query": "...", "dryRun": true }` |

Both return `{ count, matches, errors }`. For drift-free semantic deletion, preview with `dryRun: true`, review the IDs, then submit them to the exact-ID endpoint.

See [memory forgetting](./api-v5-memory-forgetting) for the complete dry-run, approval, response, and audit workflow.

### Verification

* Assert requested empty includes are `[]`, while omitted includes are absent.
* Paginate each resource type until `currentPage >= totalPages`; unselected arrays stay empty.
* Verify chunk rows contain their parent `documentId`.
* Exercise partial document-delete failures and semantic dry runs.
* Verify IDs cannot read, list, or delete content outside their namespace.

## Search

v5 searches one namespace, defaults to hybrid recall, and takes every option in one typed JSON body. Search has no query-string parameters.

### Request mapping

| Legacy | v5 |
| - | - |
| `containerTag` | `/ns/{namespace}` |
| body `q` | body `query` |
| body `limit` | body `limit` |
| `searchMode: "documents"` | `searchMode: "chunks"` |
| omitted search mode | `searchMode: "hybrid"` |
| `filters` | singular `filter` |
| `include.documents` or `.summaries` | `include.documents` |
| `include.relatedMemories` | `include.related` |
| `include.forgottenMemories` | `include.forgotten` |
| `rerank: true` / `aggregate: true` | `rerank: "order"` / `"aggregate"` |

<CodeGroup>
  ```bash Legacy theme={null}
  POST /v4/search
  {"q":"What did the user decide?","containerTag":"user_1","limit":10,"searchMode":"memories"}
  ```

  ```bash v5 theme={null}
  POST /ns/user_1/search
  {"query":"What did the user decide?","limit":10,"searchMode":"memories","threshold":0.6,"rewriteQuery":false}
  ```
</CodeGroup>

### Changed defaults

| Setting | v4 | v5 |
| - | - | - |
| Search mode | `memories` | `hybrid` |
| Similarity threshold | `0.6` | `0.3` |
| Reranking | Disabled | `rerank: "none"` |
| Query rewriting | Disabled | `false` |

Set mode and threshold explicitly while comparing versions. After parity testing, remove them only if you want the broader v5 hybrid defaults.

### Search modes

| Mode | Returns |
| - | - |
| `memories` | Formed memories only |
| `chunks` | Source chunks only |
| `hybrid` | Both result types in one ranked list |

Legacy `include.chunks` has no v5 equivalent. Choose `chunks` or `hybrid` instead.

### Included context and ranking

`include` is an object of booleans in the body, e.g. `"include": {"documents": true, "related": true}`. Each flag defaults to `false`.

* `include.documents` adds the most relevant source document to each result.
* `include.related` adds parent, child, and sibling memories.
* `include.forgotten` lets forgotten and expired memories appear in results, including as primary results.
* `rerank` accepts `none`, `order`, or `aggregate`; `rewriteQuery` controls retrieval-oriented query rewriting.

### Response mapping

| Legacy reader | v5 reader |
| - | - |
| Result array | `results` |
| Timing | `searchTime` |
| Source expansion | `result.included.document` |
| Related context | `result.included.related.{parents,children,siblings}` |
| Lifecycle fields | `result.system` |

Each primary result contains either `memory`, `chunk`, or both only if the contract allows it. Branch on field presence rather than assuming one result shape.

### Verification

* Compare IDs using explicit v4-equivalent defaults, then test v5 hybrid behavior separately.
* Cover all three modes, thresholds at `0` and `1`, each rerank option, and query rewriting.
* Cover every include alone and in combination, including empty results.
* Verify filters, namespace isolation, result limits, and invalid body/query placement.

## Profiles and buckets

v5 returns a maintained profile directly and gives profile bucket definitions their own namespace-scoped resource.

### Remove search behavior from profile calls

<CodeGroup>
  ```bash Legacy theme={null}
  POST /v4/profile
  {"containerTag":"user_1","q":"work preferences","threshold":0.6,"include":{}}
  ```

  ```bash v5 theme={null}
  POST /ns/user_1/profile
  {"filter":{"field":"region","operator":"eq","value":"us-west"},"buckets":["work"]}
  ```
</CodeGroup>

Remove legacy `q`, `threshold`, and `include`. If the caller needs query-ranked results, issue a separate v5 search request. Move `containerTag` to the path and rename `filters` to singular `filter`.

### Read the v5 profile shape

```json theme={null}
{
  "profile": {
    "static": ["The user works in design"],
    "dynamic": ["The user is preparing a launch"],
    "buckets": { "work": ["Prefers concise project updates"] }
  }
}
```

`static` and `dynamic` are always returned and cannot be disabled. Omit `buckets` in the request to return every effective custom bucket; pass up to 50 names to narrow only the bucket section.

### Read bucket definitions

<CodeGroup>
  ```bash Legacy theme={null}
  POST /v4/profile/buckets
  {"containerTag":"user_1"}
  ```

  ```bash v5 theme={null}
  GET /ns/user_1/profile/buckets
  ```
</CodeGroup>

The response changes from key/description objects to a map:

```json theme={null}
{"buckets":{"work":"Professional preferences and ongoing work"}}
```

### Add or edit namespace buckets

```bash theme={null}
PUT /ns/user_1/profile/buckets
{"buckets":{"work":"Professional preferences and ongoing work"}}
```

Send one to 50 name-to-description entries. Existing namespace names are updated, new names are added, and omitted namespace buckets remain unchanged.

### Delete namespace buckets

```bash theme={null}
DELETE /ns/user_1/profile/buckets
{"buckets":["work"]}
```

Names must be unique. Organization-owned buckets can appear in the effective GET response but cannot be changed or removed through namespace PUT or DELETE calls.

### Verification

* Confirm every profile response contains `static`, `dynamic`, and `buckets`.
* Compare omitted buckets with one-name and multi-name narrowing.
* Add, edit, and delete a namespace bucket without replacing omitted buckets.
* Attempt to mutate an inherited organization bucket and expect the documented error.

## Memory forgetting

v5 scopes forgetting to one namespace and returns the same result envelope for exact and semantic requests.

### Choose exact or semantic forgetting

| Intent | v5 operation |
| - | - |
| Forget reviewed memory IDs | `DELETE /ns/{namespace}/memories` |
| Find memories by meaning | `DELETE /ns/{namespace}/memories/semantic` |

### Forget exact IDs

```bash theme={null}
DELETE /ns/user_1/memories
Content-Type: application/json

{"ids":["mem_1","mem_2"]}
```

Send 1–500 IDs. The response reports successful IDs in `matches` and missing or ineligible IDs in `errors`, so HTTP success does not imply every requested ID changed.

### Preview a semantic request

```bash theme={null}
DELETE /ns/user_1/memories/semantic
Content-Type: application/json

{"query":"outdated home address","dryRun":true}
```

`dryRun: true` performs selection without changing memory state. `dryRun: false` forgets the memories selected when that request executes.

### Avoid selection drift

```text theme={null}
semantic request with dryRun: true
                |
                v
review matches[].id
                |
                v
exact DELETE with reviewed IDs
```

Use this workflow when a human or policy must approve the exact set. Re-running the semantic request with `dryRun: false` can select a different set if memories changed after preview.

### Read the normalized response

```json theme={null}
{
  "count": 1,
  "matches": [{ "id": "mem_1", "memory": "Old address" }],
  "errors": [{ "id": "mem_2", "error": "Memory not found" }]
}
```

`count` always equals `matches.length`. Both dry-run and applied semantic requests use this shape; the payload alone does not replace your record of which mode was sent.

### Removed memory-write routes

Direct v4 memory creation and version updates have no v5 replacement. Ingest source material through document routes and update the canonical document when facts change.

### Verification

* Exercise all-success, partial-success, duplicate, unknown, and cross-namespace ID sets.
* Confirm dry runs leave matched memories recallable.
* Apply reviewed IDs exactly and confirm normal recall excludes them.
* Persist the request mode alongside audit logs for semantic operations.

## Namespaces

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}` with `{ "moveTo": "target" }` |

`GET /ns` is an alias for `GET /namespaces`. Prefer `/namespaces` in new integrations.

### List namespaces

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={null}
  PATCH /v3/container-tags/project_alpha
  {"entityContext":"Research project for distributed systems"}
  ```

  ```bash v5 theme={null}
  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={null}
DELETE /ns/project_alpha
{}
```

With no `moveTo`, deletion is synchronous and returns `200` with `deletedDocumentsCount` and `deletedMemoriesCount`. This removes the namespace and its content.

### Move then remove a namespace

```bash theme={null}
DELETE /ns/project_alpha
{"moveTo":"project_archive"}
```

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.

### 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.

## Organization settings

v5 exposes only the organization-wide context needed to guide memory formation. Internal controls and profile bucket mutation are no longer part of this settings resource.

### Endpoint mapping

| Legacy | v5 |
| - | - |
| `GET /v3/settings` | `GET /organization` |
| `PATCH /v3/settings` | `PATCH /organization` |
| `filterPrompt` | `organizationalContext` |

### Read organization settings

```bash theme={null}
GET /organization
```

```json theme={null}
{
  "organizationalContext": "Acme builds security tools for enterprises",
  "namespaceCount": 42
}
```

Remove readers for legacy settings that are not present in this allowlisted response. `namespaceCount` is informational and cannot be changed through PATCH.

### Update organization context

<CodeGroup>
  ```bash Legacy theme={null}
  PATCH /v3/settings
  {"filterPrompt":"Acme builds security tools for enterprises"}
  ```

  ```bash v5 theme={null}
  PATCH /organization
  {"organizationalContext":"Acme builds security tools for enterprises"}
  ```
</CodeGroup>

The field is exhaustive: the supplied value replaces the existing context. Send `null` to remove it. Empty strings are rejected.

Organization updates require an organization administrator. Do not silently fall back to namespace context when the caller receives `403`.

### Removed public operations

* Organization profile-bucket mutation is not exposed through organization settings.
* Bucket suggestion is not part of v5.
* Organization data reset is not part of v5.
* Namespace-owned profile buckets are managed through `/ns/{namespace}/profile/buckets`.

### Verification

* Compare the v5 context with the legacy `filterPrompt` before cutover.
* Set, replace, and clear organizational context.
* Confirm `namespaceCount` agrees with `GET /namespaces` for the same credentials.
* Verify non-admin callers receive `403` on PATCH.
* Confirm removed fields are not required by downstream configuration code.

## Typed filters

v5 uses one optional singular `filter` field for search, profiles, and list operations.

### Shape

```ts theme={null}
type Filter =
  | { field: string; operator: "eq" | "neq"; value: string; caseSensitive?: boolean }
  | { field: string; operator: "eq" | "neq"; value: number | boolean }
  | { field: string; operator: "gt" | "gte" | "lt" | "lte"; value: number }
  | { field: string; operator: "contains" | "notContains"; value: string; caseSensitive?: boolean }
  | { field: string; operator: "arrayContains" | "arrayNotContains"; value: string }
  | { operator: "and" | "or"; operands: Filter[] };
```

Fields may contain letters, numbers, `_`, `.`, and `-`. Expressions allow up to five nested levels and 200 operands per logical group.

### Operator mapping

| Legacy condition | v5 predicate |
| - | - |
| `{ key, value }` | `{ field: key, operator: "eq", value }` |
| `negate: true` equality | `operator: "neq"` |
| `filterType: "string_contains"` | `operator: "contains"` |
| contains + `negate: true` | `operator: "notContains"` |
| `filterType: "array_contains"` | `operator: "arrayContains"` |
| array contains + `negate: true` | `operator: "arrayNotContains"` |
| numeric `=` / numeric `=` + `negate: true` | `eq` / `neq` with a JSON number |
| numeric `>`, `>=`, `<`, `<=` | `gt`, `gte`, `lt`, `lte` |
| `AND` / `OR` arrays | lowercase `and` / `or` with `operands` |
| `ignoreCase: true` | `caseSensitive: false` |

### Before and after

<CodeGroup>
  ```json Legacy theme={null}
  {
    "AND": [
      { "key": "category", "value": "research" },
      { "key": "score", "value": 0.8, "filterType": "numeric", "numericOperator": ">=" }
    ]
  }
  ```

  ```json v5 theme={null}
  {
    "operator": "and",
    "operands": [
      { "field": "category", "operator": "eq", "value": "research" },
      { "field": "score", "operator": "gte", "value": 0.8 }
    ]
  }
  ```
</CodeGroup>

### Deterministic conversion

1. Rename outer `filters` to `filter`.
2. Recursively replace `AND`/`OR` objects with `{ operator, operands }`.
3. Rename `key` to `field`.
4. Convert legacy flags into one explicit operator.
5. Keep numeric values as JSON numbers rather than numeric strings.
6. Remove legacy `filterType`, `negate`, `numericOperator`, and `ignoreCase` keys.

### Verification

* Compare result IDs for equality, inequality, contains, numeric, array, nested AND, and nested OR fixtures.
* Add negative tests: legacy shapes, empty operands, incompatible value types, and unknown keys must return `400`.
* Confirm omitted `filter` preserves unfiltered behavior.

## Verification and rollout

Treat migration as a behavioral comparison, not a raw response snapshot update.

### Build deterministic fixtures

Use an isolated namespace with stable IDs and fixed source content. Include plaintext, URL, file, batch, metadata, grouping, profile facts, related memories, forgotten memories, and empty-result cases.

Record each legacy request, v5 request, expected semantic result, and intentional difference. Never compare generated IDs, signed URLs, timing, or JSON object order unless the contract guarantees them.

### Compare writes

* Repeated POST appends or diffs; PATCH replaces canonical content.
* Batch outcomes preserve input order and surface partial failures.
* Metadata-only updates leave source content unchanged.
* Accepted writes are polled until processing reaches a terminal state.

### Compare reads and recall

* Document includes are absent when omitted and empty arrays when requested without results.
* Unified list responses populate only the selected resource array.
* Search parity uses explicit v4-equivalent mode and threshold before testing v5 defaults.
* Profiles always contain static, dynamic, and bucket sections.

### Exercise boundaries

| Boundary | Cases |
| - | - |
| Namespace | Correct, missing, unauthorized, cross-namespace ID |
| Pagination | First, middle, final, empty, maximum limit |
| Filters | Every operator, nested AND/OR, invalid type, excessive depth |
| Deletion | All success, partial success, unknown IDs, semantic dry run |
| Settings | Admin, non-admin, null removal, invalid empty value |

### Classify differences

```text theme={null}
same request intent
       |
       +-- same semantic result ------> parity
       +-- documented v5 difference --> update assertion
       +-- undocumented difference ----> block cutover
```

Do not normalize away an undocumented difference. Capture the request pair, namespace, IDs, response status, and minimal response fragments needed to reproduce it.

### Cut over by domain

1. Ship v5 request construction behind a per-domain flag.
2. Dual-read or shadow-call where side effects allow it.
3. Switch ingestion, content management, search, profiles, then settings independently.
4. Monitor validation failures, authorization failures, latency, empty-result rate, and processing failures.
5. Retain the legacy path until the observation window passes.

### Completion checklist

* No application API call accidentally uses a `/v5` prefix.
* Unchanged connector routes retain their documented `/v3` paths.
* No legacy field aliases or response readers remain.
* Every changed default is either accepted intentionally or passed explicitly.
* Rollback restores the previous caller without requiring data repair.

## Operations without a direct replacement

* Direct memory creation and version updates: ingest or replace a source document instead.
* Organization bucket suggestion and organization reset: not part of the v5 public surface.
* Connector routes that still use `/v3`: unchanged; do not rewrite them.
* Conversation ingestion (`/v4/conversations`): not part of the v5 public surface. Send the transcript as a document instead.
* Container-tag merges: not part of the v5 public surface.

Use the [v5 reference](https://api.supermemory.ai/v5/reference) for the stable v5 API. [`/reference`](https://api.supermemory.ai/reference) always points to the latest public version.


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