API overview

The Mnueron REST API is the same surface every official client speaks: the Python SDK, the .NET / C# SDK, the Chrome extension, the MCP server, and the dashboard at /dashboard. If something can do it from any of those, you can do it directly over HTTP.

Base URL

https://www.mnueron.com/api

Self-hosted instances live at whatever URL you deploy them to — set MNUERON_API_URL to point your SDK at it. Local mode (the default after mnueron setup) talks to http://127.0.0.1:3122/api against your own SQLite, no auth required.

Authentication

Every authenticated endpoint accepts a token in either:

• Authorization: Bearer mnu_… header — the canonical method, used by every SDK and curl example below
• mnueron_session httpOnly cookie — set by POST /api/auth/login, used by the dashboard

Both paths resolve to the same api_tokens row server-side. Get a token from Account → API tokens. The raw mnu_… value is shown once at creation — store it in your secrets manager, never commit it to git.

export MNUERON_API_TOKEN=mnu_REPLACE_ME

curl https://www.mnueron.com/api/memories \
  -H "Authorization: Bearer $MNUERON_API_TOKEN"

Org and project scope

Every API token is bound to one org. To work across orgs, mint a separate token per org from each org's settings page, or use the org-switcher in the dashboard.

Inside an org, memories belong to a project (Mnueron also calls these namespaces — they're the same row in the DB). Most write endpoints accept an optional namespace field; if omitted you write to "default". See Organizations & projects for the full data model.

Response shape

Successful responses are JSON. Resource endpoints return the resource:

{
  "id": "01HQB9R3MV…",
  "content": "Prefers 2-space indentation in JavaScript.",
  "namespace": "preferences",
  "tags": ["style"],
  "metadata": {},
  "created_at": 1737070000000,
  "updated_at": 1737070000000
}

Timestamps are returned as epoch milliseconds (UTC). All ids are UUIDs.

List endpoints return either a plain array (legacy routes like GET /api/memories) or an object with the resource name as a key ({ memories: [...] }). The newer endpoints use the keyed shape; the older ones are preserved for backwards compatibility.

Errors

Errors are JSON with an error string. Many errors include extra fields a smart client can act on:

{
  "error": "memory_quota_exceeded",
  "message": "You've used your 500 free memories.",
  "quota": { "used": 500, "limit": 500, "plan": "free" },
  "upgrade_url": "/account-settings/plan"
}

Rate limits

Writes are capped at 60 requests/minute per token (POST /api/memories, PATCH /api/memories/:id, DELETE /api/memories/:id, batch endpoints, POST /api/auth/resend-verification). Reads are unlimited.

When the limit is hit you get 429 Too Many Requests with a Retry-After header (seconds).

Quotas

Free orgs are capped at:

• 500 lifetime memories
• 50 MB total storage
• No server-side LLM features (synopsis, entity extraction, consolidation merges, /api/chat) — BYOK keys still work

See Account → Plan for the paid tiers (Personal, Team, Enterprise).

Idempotency

These endpoints are safe to retry:

• All GET requests
• PUT and DELETE on a specific resource (/api/memories/:id, /api/webhooks/:id)
• POST /api/billing/webhook (Stripe events deduped by stripe_event_id)

POST /api/memories is not idempotent — repeated calls create separate memories. Use POST /api/memories with a stable metadata.idempotency_key if you need de-dup semantics today (the server doesn't enforce it yet, but the field travels with the row so you can detect duplicates on your side).

Versioning

The API is v0 until 1.0. Breaking changes are gated behind new endpoints (/api/v2/...) rather than mutating existing shapes. Subscribe to the changelog for the full list of additions and deprecations.