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

# API Overview

> The unified EverOS Memory API (v2), shared across Cloud and self-hosted (OSS) deployments.

EverOS exposes a single **Memory API (v2)** for building AI agents with persistent memory. The same request and response contracts are shared across **EverOS Cloud** (managed SaaS) and **EverOS OSS** (self-hosted), so you write against one API and choose where it runs.

## Endpoints

| Endpoint | Purpose | Availability |
| - | - | - |
| `POST /api/v2/memory/add` | Add conversation messages to a session | OSS + Cloud |
| `POST /api/v2/memory/flush` | Force memory extraction | OSS + Cloud |
| `POST /api/v2/memory/get` | Retrieve memories by type | OSS + Cloud |
| `POST /api/v2/memory/search` | Search memories (keyword, vector, hybrid, agentic) | OSS + Cloud |
| `POST /api/v2/memory/edit` | Bulk-edit profile items | Cloud-only |
| `POST /api/v2/memory/delete` | Delete memories by scope | Cloud-only |
| `POST /api/v2/object/sign` | Generate presigned URLs for multimodal uploads | Cloud (Storage) |

<Note>
  Endpoints marked **Cloud-only** are not yet available on self-hosted deployments. Everything marked **OSS + Cloud** behaves identically on both.
</Note>

## Base URL

<CodeGroup>
  ```text Cloud theme={null}
  https://api.evermind.ai
  ```

  ```text OSS (self-hosted) theme={null}
  http://127.0.0.1:8000
  ```
</CodeGroup>

The OSS base URL depends on where you run the server; `http://127.0.0.1:8000` is the default for a local install.

## Authentication

All endpoints are authenticated with a Bearer token. Obtain your API key from [everos.evermind.ai](https://everos.evermind.ai) and send it in the `Authorization` header:

```bash theme={null}
"Authorization": "Bearer <api-key>"
```

<Warning>
  Never expose or commit your API key.
</Warning>

## Response format

Successful v2 responses share a common envelope: a `request_id` for tracing alongside an endpoint-specific `data` payload.

```json theme={null}
{
  "request_id": "req_abc123",
  "data": { }
}
```

Writes via `add` are asynchronous by default: the request is validated and enqueued, returning **HTTP 202** with `status: "queued"`. Set `async_mode: false` to write synchronously and receive the engine's **HTTP 200** result directly.

## Reading messages before they are extracted

Because extraction is asynchronous, the newest turns in a session may not belong to an episode yet.

`POST /api/v2/memory/search` can return that in-flight buffer as raw messages in `data.unprocessed_messages`, so a live agent still sees what was just said.

It is loaded only when the request pins a single session with a top-level `session_id` equality scalar:

```json theme={null}
{
  "query": "seat preference",
  "user_id": "user_001",
  "filters": {"session_id": "session_001"}
}
```

Anything else leaves the field as `[]`: a `session_id` nested inside `AND` / `OR`, or written as an operator map such as `{"eq": ...}` or `{"in": ...}`. Scoping by `user_id` alone is not enough either.

The reason is that buffered rows have no owner attribution yet, since owner inference runs after boundary detection. The session is therefore the only dimension that can scope them, and pinning one is the deliberate opt-in to read its whole in-flight window.

Each entry is the raw message (`id`, `session_id`, `sender_id`, `sender_name`, `role`, `content`, `timestamp`, plus `tool_calls` / `tool_call_id` for tool turns), ordered oldest first, and carries no relevance `score` because it was never ranked. Once a memcell closes over those rows they leave the buffer and appear as an episode instead.

## Looking for older endpoints?

The previous per-deployment APIs remain available while you migrate:

<CardGroup cols={2}>
  <Card title="API Reference (Cloud v1 · legacy)" icon="clock-rotate-left" href="/api-reference/legacy-cloud-v1">
    The v1 Cloud API, including endpoints not carried into v2 (Groups, Senders, Tasks, Settings).
  </Card>

  <Card title="API Reference (OSS v1 · legacy)" icon="clock-rotate-left" href="/api-reference/legacy-oss-v1">
    The v1 self-hosted API, including features not yet in v2 (Knowledge Wiki, Reflection).
  </Card>
</CardGroup>


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