REST API

The Memax REST API lives at https://api.memax.app. All endpoints are under the /v1/ prefix.

Base URL

https://api.memax.app/v1

Authentication

Every request needs a Bearer token — either an API key you generated via memax auth create-key, or a short-lived access token from the OAuth flow.

curl -H "Authorization: Bearer mxk_your_api_key" \
  https://api.memax.app/v1/memories

See Authentication for how to obtain and manage keys.

Response envelope

Every REST endpoint returns the same JSON shape. Success:

{ "data": { ... } }

Error:

{
  "error": {
    "code": "not_found",
    "message": "Memory not found",
    "details": {}
  }
}

details is optional and endpoint-specific.

Endpoint categories

See Memories, Recall, and Hubs for the common endpoints. For the full list, the authoritative source is packages/server/internal/serverapp/routes.go.

Pagination

List endpoints use cursor-based pagination:

GET /v1/memories?limit=20&cursor=<opaque>

Responses include:

{
  "data": {
    "memories": [ ... ],
    "next_cursor": "<opaque string or empty>",
    "has_more": true
  }
}

Treat cursors as opaque — don't parse them. An empty next_cursor with has_more: false indicates the last page.

Rate limits

Every response from a rate-limited endpoint includes:

X-RateLimit-Limit:     <per-minute cap for this endpoint class>
X-RateLimit-Remaining: <remaining in the current window>
X-RateLimit-Reset:     <unix timestamp when the window resets>

When the window is exhausted, the API returns 429 Too Many Requests with a Retry-After header (in seconds).

The actual per-minute caps are plan-defined and split into three buckets:

• Regular endpoints (reads, metadata).
• Heavy endpoints (/v1/recall, /v1/ask, /v1/dreams/trigger — anything that calls the LLM or embedding models).
• Light endpoints (health, whoami, etc.).

See Usage or GET /v1/usage for your current plan's limits.