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

# v1 API Retirement

> The EverOS Cloud v1 API retires soon. What changes, what we handle for you, and how to move your integration to v2.

<Warning>
  **The EverOS Cloud v1 API retires soon.** We will announce the exact date by email and
  on this page. From that date, calls to `/api/v1/*` stop working. Any code that talks to
  EverOS needs to move to the v2 Memory API before then, whether it is running today or not.
</Warning>

Your API key does not change. The same key already works against both versions, so
there is no credential to rotate and no configuration to swap.

## What you get on v2

v2 is a rewrite of the memory layer, not a version bump. Alongside everything v1 did:

<CardGroup cols={2}>
  <Card title="Knowledge bases" icon="books">
    Ingest documents and search them alongside conversational memory, with categories,
    topics and tags.
  </Card>

  <Card title="Profile editing" icon="user-pen">
    Add, update or delete individual profile items directly, instead of waiting for
    extraction to correct itself.
  </Card>

  <Card title="Memory tags" icon="tags">
    Attach your own labels to memories.
  </Card>

  <Card title="Sharper agent memory" icon="robot">
    Agent memory splits into reusable *skills* and distilled *cases*, retrievable
    separately.
  </Card>

  <Card title="Finer retrieval control" icon="sliders">
    Score thresholds, optional LLM reranking, and per-query profile inclusion.
  </Card>

  <Card title="Multi-app scoping" icon="layer-group">
    Partition memory by app and project under a single key.
  </Card>
</CardGroup>

## Do I need to do anything?

<Steps>
  <Step title="Do you call /api/v1/* ?">
    Directly over HTTP, or through any client library. If yes, you need to migrate.
  </Step>

  <Step title="Do you depend on everos-cloud 0.4.x or earlier?">
    Check your `requirements.txt` or `pyproject.toml` for `everos-cloud<1`,
    `everos-cloud>=0.4`, or the older `evermemos` package. If yes, you need to migrate.
  </Step>

  <Step title="Neither?">
    You are already on v2. Nothing to do.
  </Step>
</Steps>

## What happens to your data

We migrate it as part of the retirement. You do not need to export, re-ingest or
backfill anything.

<Note>
  If you are cutting over well before the retirement date and you want your existing
  memories readable in v2 from the moment you switch, contact us. We will schedule your data
  migration around your cutover rather than around the retirement date.
</Note>

## Migrating your code

### Option 1: by hand

Everything that changes is documented below, in the order you will meet it. Python SDK
users should also read [Upgrade Python SDK to 1.x](/api-reference/sdk-migration-1x):
the 1.x SDK speaks only the v2 API, so upgrading it is the migration.

### Option 2: hand it to us

Reply to your migration email, or contact us, and we will make the changes for your
integration.

<Note>
  **A migration tool is on its way.** It will read your codebase, report exactly what would
  change, and apply most of it for you, covering both the Python SDK and raw HTTP calls in
  any language. It runs inside an AI coding assistant. We will link it here and announce it
  by email as soon as it is released.
</Note>

## What changes

### Endpoints

Note the singular `memory` in v2. A search and replace that only swaps `v1` for `v2`
will not work.

| v1                             | v2                            |
| ------------------------------ | ----------------------------- |
| `POST /api/v1/memories`        | `POST /api/v2/memory/add`     |
| `POST /api/v1/memories/agent`  | `POST /api/v2/memory/add`     |
| `POST /api/v1/memories/flush`  | `POST /api/v2/memory/flush`   |
| `POST /api/v1/memories/get`    | `POST /api/v2/memory/get`     |
| `POST /api/v1/memories/search` | `POST /api/v2/memory/search`  |
| `POST /api/v1/memories/delete` | `POST /api/v2/memory/delete`  |
| `POST /api/v1/object/sign`     | `POST /api/v2/object/sign`    |
| `GET /api/v1/tasks/{task_id}`  | `GET /api/v2/tasks/{task_id}` |

### Timestamps must be in milliseconds

<Warning>
  This is the most common migration break. It fails at runtime, on every write.
</Warning>

v2 rejects a seconds-scale timestamp rather than silently rescaling it, because a batch
mixing both scales would mis-order and mis-split sessions.

```python theme={null}
"timestamp": int(time.time())          # rejected with 422
"timestamp": int(time.time() * 1000)   # correct
```

```
422 InvalidParameter: `timestamp` must be a unix millisecond timestamp (>= 1000000000000)
```

Check your test fixtures and seed data too. A 10-digit literal is seconds, a 13-digit
literal is milliseconds.

### The owner moves onto each message

```json theme={null}
// v1
{
  "user_id": "user-alice",
  "session_id": "session-1",
  "messages": [{ "role": "user", "content": "I love hiking", "timestamp": 1757001600000 }]
}

// v2
{
  "session_id": "session-1",
  "messages": [{
    "sender_id": "user-alice",
    "role": "user",
    "content": "I love hiking",
    "timestamp": 1757001600000
  }]
}
```

`session_id` is now required, between 1 and 128 characters. It is the unit that
extraction works on.

### Reads take the owner as a top-level field

```json theme={null}
// v1
{ "memory_type": "episodic_memory", "filters": { "user_id": "user-alice" } }

// v2
{ "memory_type": "episode", "user_id": "user-alice" }
```

Exactly one of `user_id` or `agent_id` is required on both `get` and `search`. Owner and
type must agree: a `user_id` owner may ask for `episode` or `profile`, an `agent_id`
owner may ask for `agent_case` or `agent_skill`.

### Memory type values

| v1                | v2                                                                                                 |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `episodic_memory` | `episode`                                                                                          |
| `profile`         | `profile`                                                                                          |
| `agent_memory`    | `agent_case` or `agent_skill`                                                                      |
| `raw_message`     | no longer retrievable. Unextracted turns surface in a `search` response as `unprocessed_messages`. |

### New scoping fields

Every memory call accepts `app_id` and `project_id`, both defaulting to `"default"`.
You can ignore them, but reads must use the same pair as the write. A mismatched pair
returns empty results rather than an error.

This is a partition, not a security boundary. The security boundary is the tenant
resolved from your API key.

### Responses

`request_id` moved to the top level of the envelope, and the human-readable `message`
field is gone.

```json theme={null}
// v1
{ "data": { "request_id": "0217...", "message_count": 4, "status": "accumulated", "message": "Messages accepted" } }

// v2
{ "request_id": "0217...", "data": { "message_count": 4, "status": "extracted" } }
```

In `search` responses, `raw_messages` becomes `unprocessed_messages`, and the single
`agent_memory` object becomes two arrays, `agent_cases` and `agent_skills`.

`delete` returned `204 No Content` on v1. On v2 it returns `200` with a body reporting
what matched.

### Errors

```json theme={null}
// v1
{ "code": "HTTP_ERROR", "message": "...", "request_id": "...", "path": "..." }

// v2
{ "code": "InvalidParameter", "message": "...", "param": "messages[0].timestamp",
  "type": "UnprocessableEntity", "status_code": 422 }
```

Branch on `status_code` rather than matching on `message`. Code that matched the
literal string `"HTTP_ERROR"` will never match again.

## Capabilities that changed shape

<AccordionGroup>
  <Accordion title="Group memory" icon="users">
    v1 had a group as an addressable object: `/api/v1/memories/group`, a `/groups`
    registry, and `group_id` as a read filter.

    v2 scopes memory by sender. Multi-party conversations still work and still produce
    episodes attributed to every participant, but you write all participants into one
    `session_id` and read per participant rather than by group.

    If your integration uses group memory, contact us before you start. We will go
    through your usage and agree a mapping with you.
  </Accordion>

  <Accordion title="Sender registry" icon="address-card">
    `/api/v1/senders` has no v2 equivalent. If you used it only to attach display names,
    pass `sender_name` on each message instead. Note that this changes "register once"
    into "send every time", so the name has to be available at write time.
  </Accordion>

  <Accordion title="Memory space settings" icon="gear">
    `/api/v1/settings`, covering `timezone` and `llm_custom_setting`, has no v2
    equivalent. If you configured either, contact us before migrating.
  </Accordion>

  <Accordion title="Single-memory delete" icon="trash">
    v1 accepted `{"memory_id": "..."}` to delete one memory. v2 deletes by scope only:
    `user_id`, `agent_id` or `session_id`.

    Note the scope semantics: deleting by `user_id` alone removes that user's episodes
    and their profile. Adding `session_id` removes what that session produced and leaves
    the profile in place.
  </Accordion>

  <Accordion title="Async Python client" icon="bolt">
    `everos-cloud` 1.x ships no async client. `AsyncEverOS` was removed. You can run the
    synchronous client in a thread, or call `/api/v2/memory/*` with your own async HTTP
    client.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Does my API key change?">
    No. The same key authenticates both versions, so you can migrate service by service
    without touching credentials.
  </Accordion>

  <Accordion title="Can I migrate one service at a time?">
    Yes. v1 and v2 both accept your key until the retirement date, so you can move incrementally.
    Keep in mind that the two versions hold separate stores until your data is migrated,
    so a service reading on v2 will not see what another service wrote on v1. If that
    matters during your transition, contact us about migrating your data sooner.
  </Accordion>

  <Accordion title="What happens on the retirement date?">
    Requests to `/api/v1/*` stop being served. Your existing memories are not affected.
    We migrate them into v2 as part of the retirement.
  </Accordion>

  <Accordion title="Can you migrate my data earlier?">
    Yes. Tell us when you plan to cut over and we will schedule your migration to line
    up with it, so your history is there from the moment you switch.
  </Accordion>

  <Accordion title="Is there a tool that does this for me?">
    One is coming. Until it is released, follow the manual guide above, or contact us and
    we will make the changes for you.
  </Accordion>

  <Accordion title="What if I need longer?">
    Tell us. We would much rather adjust the plan with you in advance than have you
    discover a problem on the last day.
  </Accordion>
</AccordionGroup>

## Get help

You do not have to do this alone. Reply to your migration email with any questions, and
we will walk through it with you. If you would rather hand it over, we will make the
changes for your integration.