Skip to main content
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

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

​
Base URL

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 and send it in the Authorization header:
Never expose or commit your API key.

​
Response format

Successful v2 responses share a common envelope: a request_id for tracing alongside an endpoint-specific data payload.
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:
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:

API Reference (Cloud v1 · legacy)

The v1 Cloud API, including endpoints not carried into v2 (Groups, Senders, Tasks, Settings).

API Reference (OSS v1 · legacy)

The v1 self-hosted API, including features not yet in v2 (Knowledge Wiki, Reflection).