---
title: REST API
description: All Memoria REST endpoints, request/response shapes, and conventions. OpenAPI 3 spec available.
order: 4
---

# REST API

Memoria's REST API is the lowest-level interface — the SDK and MCP server both call it under the hood. Use it when you want full control, or when you're integrating from a language that doesn't have an official SDK yet.

**Base URL:** `https://api.memoria.premex.se`

**OpenAPI 3 spec:** [api.memoria.premex.se/openapi.yaml](https://api.memoria.premex.se/openapi.yaml)

## Authentication

Send your API key as a Bearer token:

```bash
curl https://api.memoria.premex.se/v1/recall \
  -H "Authorization: Bearer mem_live_…" \
  -H "Content-Type: application/json" \
  -d '{"query": "Where does Stefan work?"}'
```

API keys are brain-scoped: each key authorizes operations against exactly one brain. To work across brains, create one key per brain.

## Common conventions

- All endpoints return JSON. UTF-8 throughout.
- Timestamps are ISO-8601 with timezone (`2026-05-28T10:00:00Z`).
- Errors return `{"error": "...", "details": ...}` with appropriate 4xx/5xx codes.
- Pagination is cursor-based: pass `?cursor=<opaque>` from the previous response's `next` field.

## Endpoints

### POST /v1/episodes — store a memory

```json
{
  "content": "Stefan joined Premex as a Senior Engineer in 2023.",
  "metadata": { "source": "onboarding-notes" }
}
```

Returns the created episode and kicks off the extraction pipeline. Extraction is async — entities and edges appear in subsequent recalls once the pipeline completes (typically <2s).

### POST /v1/recall — retrieve facts

```json
{
  "query": "Where does Stefan work?",
  "asOf": "2026-01-01",
  "limit": 10
}
```

Returns:

```json
{
  "context": "Stefan is a Senior Engineer at Premex …",
  "edges": [ … bi-temporal edges with scores … ],
  "episodes": [ … source episodes for citation … ]
}
```

`asOf` is optional. Omit it to query "as of right now."

### GET /v1/entities/:id — entity details

Returns the entity plus the most recent valid edges it participates in.

### GET /v1/edges/:id — edge details

Returns the full edge including both time ranges (`tValid`/`tInvalid`, `tIngested`/`tExpired`) and the source episode.

### POST /v1/edges/:id/invalidate — mark a fact superseded

Doesn't delete the edge — sets `tInvalid` to the current time and marks why. The edge stays queryable with `asOf` time-travel.

### GET /v1/playbooks/:slug — fetch a playbook

Playbooks are agent-readable summaries derived from memories. See [Playbooks](/docs/playbooks) (coming soon).

## Rate limits

- **Free tier:** 1,000 successful calls / day per brain
- Soft-fail with `429 Too Many Requests` once exceeded; resets at midnight UTC.

Paid plans are launching soon — check [pricing](/pricing) for current quotas.

## SDK or raw?

Most agents should use the [SDK](/docs/quickstart) or [MCP server](/docs/mcp) — they handle retries, request signing, and pagination for you. Drop to raw REST when you need a language not yet supported or want to debug the wire format.