REST API Server

The Mem0 REST API server exposes every OSS memory operation over HTTP. Run it alongside your stack to add, search, update, and delete memories from any language that speaks REST.

Feature

• CRUD endpoints: Create, retrieve, search, update, delete, and reset memories by user_id, agent_id, or run_id.
• Authentication: On by default. Dashboard sessions use JWTs; programmatic clients use per-user X-API-Key headers. Legacy ADMIN_API_KEY is still supported.
• Status health check: Access base routes to confirm the server is online.
• OpenAPI explorer: Visit /docs for interactive testing and schema reference.

Configure it

Run with Docker Compose (development)

```bash
OPENAI_API_KEY=your-openai-api-key
JWT_SECRET=$(openssl rand -base64 48)
```

2. Bootstrap the stack in one command:

```bash
cd server
make bootstrap    # starts Compose, creates an admin, issues the first API key
```

Or to start the stack only and finish setup via the browser wizard at http://localhost:3000:

```bash
cd server
docker compose up -d
```

3. API is at http://localhost:8888. Code edits auto-reload. </Tab> </Tabs>

<Tabs>
  <Tab title="Pull image">

docker pull mem0/mem0-api-server

  </Tab>
  <Tab title="Build locally">

docker build -t mem0-api-server .

  </Tab>
</Tabs>

1. Create a `.env` file with `OPENAI_API_KEY` and `JWT_SECRET`.
2. Run the container:

```bash
docker run -p 8000:8000 --env-file .env mem0-api-server
```

3. Visit `http://localhost:8000`.

**Run directly (no Docker)**

<Warning>
  This path skips Docker and assumes Postgres is already running and reachable at `POSTGRES_HOST:POSTGRES_PORT`. For a single-command local setup with Postgres included, use Docker Compose above.
</Warning>

```bash
pip install -r requirements.txt
uvicorn main:app --reload
```

Authentication

Auth is on by default. Protected endpoints require either a JWT (from the dashboard login flow) or an X-API-Key header. The / redirect, /docs, and /openapi.json routes stay open so you can reach the OpenAPI explorer.

The /docs OpenAPI explorer supports both auth modes. Click Authorize at the top of the page and paste either Bearer <access_token> (JWT) or your X-API-Key value. Protected endpoints return 401 until you authorize.

Log in and use a JWT

Register the first admin (only works when no user exists yet), then log in:

# First admin only — returns 403 after the first admin is registered
curl -X POST http://localhost:8888/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Admin", "email": "[email protected]", "password": "strong-password"}'

curl -X POST http://localhost:8888/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

Use the returned access_token as a bearer token:

curl -X POST http://localhost:8888/memories \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "messages": [{"role": "user", "content": "I love pizza."}],
    "user_id": "alice"
  }'

When the access token expires, exchange the refresh token at POST /auth/refresh.

Create and use a per-user API key

Create a key from the dashboard API Keys page, or call POST /api-keys with a JWT. The full m0sk_... value is returned once at creation time — store it securely.

curl -X POST http://localhost:8888/memories \
  -H "Content-Type: application/json" \
  -H "X-API-Key: m0sk_your_key_here" \
  -d '{
    "messages": [{"role": "user", "content": "I love pizza."}],
    "user_id": "alice"
  }'

Per-user keys inherit the creating user's scope. List or revoke them via GET /api-keys and DELETE /api-keys/{id}.

Legacy ADMIN_API_KEY

Set the ADMIN_API_KEY environment variable and send it as X-API-Key. The request is treated as admin-level and is not tied to a dashboard user. This mode is kept for back-compat with older self-hosted deployments — prefer JWT or per-user keys for new setups.

ADMIN_API_KEY=your-long-admin-key

See it in action

Create and search memories via HTTP

curl -X POST http://localhost:8888/memories \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "I love fresh vegetable pizza."}
    ],
    "user_id": "alice"
  }'

curl -X POST http://localhost:8888/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "vegetable",
    "user_id": "alice"
  }'

Explore with OpenAPI docs

1. Navigate to http://localhost:8888/docs (Compose) or http://localhost:8000/docs (raw Docker / uvicorn).
2. Pick an endpoint (e.g., POST /search).
3. Fill in parameters and click Execute to try requests in-browser.

Endpoint reference

The OSS REST server exposes the following endpoints. None use the /v1/ prefix.

Memory operations

Authentication

API keys

All /api-keys endpoints require a JWT.

Request logs

Entities

The /auth/*, /api-keys, /requests, and /entities routes are new to the self-hosted server and primarily back the dashboard, but you can call them directly from your own tooling.

Verify the feature is working

• Hit the root route and /docs to confirm the server is reachable.
• Run a full cycle: POST /memories → GET /memories/{id} → DELETE /memories/{id}.
• Watch server logs for import errors or provider misconfigurations during startup.
• Confirm environment variables (API keys, vector store credentials) load correctly when containers restart.

Best practices

1. Keep auth on: Auth is enabled by default. Never set AUTH_DISABLED=true in production. If you rely on ADMIN_API_KEY, use a long value (16+ chars) or prefer per-user API keys.
2. Use HTTPS: Terminate TLS at your load balancer or reverse proxy.
3. Monitor uptime: Track request rates, latency, and error codes per endpoint.
4. Version configs: Keep environment files and Docker Compose definitions in source control.
5. Limit exposure: Bind to private networks unless you explicitly need public access.