# lema docs — API reference

Everything the hosted MCP tools can do, your own code can do directly: query your team's decision graph — the cited answers, the raw claims, the never-reopen check — over plain HTTPS with a lema_live_ key.

## Base URL

All endpoints live under https://api.lema.sh — no version prefix. Requests and responses are JSON; request bodies are capped at 1 MiB, and an unknown JSON field is a 400, not silently ignored. A good first call is GET /me.

## Authentication

One header on every call: `Authorization: Bearer lema_live_…`. Keys are minted after you connect your repo (/docs/connect), then at /account/api-keys — sign in once to mint; the key does the rest. No session cookies on this surface. The scoping rule is the identity rule: a key answers over the workspaces its owner can see, and nothing else. Most read endpoints take an optional `workspace_ids` narrower; omitted, they answer org-wide. A workspace that exists but isn't yours returns 403.

## Scopes

- `decisions:read` — the default: ask, retrieve, check, and the meters.
- `decisions:write` — capture. Mintable only up to your own role in the org.

Key management is deliberately NOT a key scope: mint/list/revoke require a signed-in browser session, and an API key calling them gets 403 — a leaked key must never mint its own successors.

## Errors — three shapes, honestly three

1. Handler errors (4xx/5xx): `{ "error": "<what went wrong>" }`
2. Over a plan limit (429), structured so your agent can act on it:

```
{
  "error": "daily_limit_reached",
  "message": "<what happened, in plain words>",
  "limit": 150,
  "used": 150,
  "resets_at": "<RFC3339 — next UTC midnight>",
  "upgrade_url": "https://lema.sh/account/plan"
}
```

3. The auth layer: a missing/invalid bearer is a 401 and a missing scope a 403 as PLAIN TEXT, not JSON — they fire before any handler runs. Code against the status, not the body.

## Rate limits and the daily wallet

/ask, /retrieve, /check-approach, and /closed-atoms share ONE daily MCP-query wallet (150/day Free, 2,500/day Pro), resetting at UTC midnight. The wallet is debited only after a request is admitted — a failed validation never charges you — and the limit is never a silent failure. GET /usage is the live meter and never charges it.

## Pages

- Ask & retrieve — POST /ask, POST /retrieve (/docs/api/ask)
- Check — POST /check-approach, GET /closed-atoms (/docs/api/check)
- Keys, usage & identity — /api-keys, GET /usage, GET /me (/docs/api/keys)

Not documented yet, deliberately: POST /verify (the GitHub Action is the supported path — /docs/verify) and the capture bridge lema-mcp uses.