> ## 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 profiles and buckets to v5

> Separate profile retrieval from search and manage namespace-owned buckets

## Migration details

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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  POST /v4/profile
  {"containerTag":"user_1","q":"work preferences","threshold":0.6,"include":{}}
  ```

  ```bash v5 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "profile": {
    "static": [{ "id": "mem_1", "memory": "The user works in design" }],
    "dynamic": [{ "id": "mem_2", "memory": "The user is preparing a launch" }],
    "buckets": { "work": [{ "id": "mem_3", "memory": "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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  POST /v4/profile/buckets
  {"containerTag":"user_1"}
  ```

  ```bash v5 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  GET /ns/user_1/profile/buckets
  ```
</CodeGroup>

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

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{"buckets":{"work":"Professional preferences and ongoing work"}}
```

### Add or edit namespace buckets

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

### With the SDK

<CodeGroup>
  ```ts Legacy theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const profile = await client.profile({ containerTag: "user_1", q: "work preferences" })
  const buckets = await client.profile.buckets({ containerTag: "user_1" })
  ```

  ```ts v5 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const { profile } = await supermemory.profile("user_1", {
    buckets: ["work"],
  })

  const buckets = await supermemory.profiles.getBuckets("user_1")

  await supermemory.profiles.setBuckets("user_1", {
    buckets: { work: "Professional preferences and ongoing work" },
  })

  await supermemory.profiles.deleteBuckets("user_1", {
    buckets: ["work"],
  })
  ```
</CodeGroup>

`supermemory.profile` takes no query. `body` is optional and accepts only `filter` and `buckets`. Read `profile.static`, `profile.dynamic`, and `profile.buckets[name]` as arrays of `{ id, memory }`.

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


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