> ## 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: run the migration tool

The tool runs inside your AI coding assistant. It reads your code and tells you exactly
what would change before it changes anything, for the Python SDK and for raw HTTP calls in
any language.

Start with a report. This edits nothing.

**In Claude Code**

```bash theme={null}
/plugin marketplace add EverMind-AI/everos-tools
/plugin install everos-sdk-upgrade@everos-tools
/everos-sdk-upgrade --scan
```

**In Codex, Cursor, or any other assistant that follows the Agent Skills standard**

Install from your project directory:

```bash theme={null}
npx skills add https://github.com/EverMind-AI/everos-tools
```

Then ask the assistant, in its own chat:

```text theme={null}
Run the everos-sdk-upgrade skill in --scan mode on this repository.
```

The report opens with three lines: whether your code can move to v2, how many changes the
tool makes for you, and how many decisions are yours. Every place that needs a human is
listed by file and line. It contains no source code and no credentials, so you can send it
to us as it is. That is the fastest way for us to help you.

When you are ready, run it without `--scan` (or ask without the words `--scan`). It snapshots your working tree, works on its
own branch, and rewrites the mechanical parts: the user id moves onto each message,
timestamps become milliseconds, `filters` becomes `user_id`, and a handful of fields and
types are renamed. Anything with no v2 equivalent is marked in place rather than guessed
at. If it finds such places it stops and asks before editing; pass `--yes` to proceed with
them marked. The report ends with the exact command that undoes the run.

Two things the tool does not do: it does not run your test suite, and it does not install
the new package. Do both yourself, against a non-production key, before you switch traffic.

### Option 2: 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 3: hand it to us

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

## 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?">
    Yes. See [Option 1: run the migration tool](#option-1-run-the-migration-tool). Start
    with `--scan`: it reports what would change without editing anything, and the report is
    safe to send to us.
  </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.


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