The API the CLI and the MCP server are both calling.

POST https://app.mneia.dev/api/v1/rehydrate
authorization: Bearer mneia_...
content-type: application/json

{ "projectId": "...", "task": "migrate the ledger writes to v2", "budgetTokens": 4000 }

• The base URL is your endpoint. https://app.mneia.dev unless you were given another one, and it is what MNEIA_API_URL and .mneia/config.json both set.
• Almost everything is `POST` with a JSON body, including reads. A filter is a structured object rather than a query string, so it does not have to be flattened and re-parsed, and a request body is not logged in a proxy access log the way a URL is.
• A success is `200` with the payload as the body. There is no envelope on success - the resource is the response.
• Every response carries `cache-control: no-store`. These are a workspace’s private rows.
• A token carries its workspace, so no route takes a workspace parameter. There is nothing to pass and nothing to get wrong.

This API is the same surface @mneia/cli and @mneia/mcp-server are built on. If you are reaching for it directly, check first that a command or a tool does not already do what you want - those are covered by tests and by a stable output contract, and this is the layer underneath them.

A bearer token on every request. There are three ways to hold one, and they produce the same kind of credential:

A token resolves to one workspace and one actor. Every query is scoped to that workspace at the store interface and again by Postgres row-level security underneath it, so a token cannot read another workspace’s rows even through a query that forgot to filter - see /docs/security#isolation.

GET /api/me returns the actor and workspace a token resolves to, which is what mneia whoami prints. It is the cheapest way to check a credential.

A 401 carries a WWW-Authenticate: Bearer header naming what went wrong, and on /api/mcp it also names the protected-resource metadata document - so a client can discover how to authenticate rather than guessing.

`human_confirmed` and `asserted_by` are never read from a request body. The actor is resolved from the token and its kind is read from the database, and the confirmation flag is derived from that. A write path that accepted either from its caller would hand the decision about who may overrule whom to the caller.

POST /api/v1/rehydrate

{
  "projectId": "...",
  "task": "add rate limiting to the public API",
  "budgetTokens": 4000
}

Returns the slice: the rendered markdown, the slice id, and the scored items that went into it. The slice id matters - pass it back with a later checkpoint, along with the ids of the items that actually changed what you did, or there is no signal about whether the slice was worth loading and it cannot be recovered afterwards.

Active load-bearing constraints appear regardless of score or budget pressure. That is a guarantee rather than a ranking preference: a dropped constraint is how an agent redoes the approach a human already rejected. Its p95 latency budget is 300ms.

The two are separate because they are different acts: proposing costs money and decides nothing, and writing decides things and costs nothing. Splitting them is what lets a person review the candidates in between.

propose resumes from a server-side watermark keyed on the source and the session reference, so a run that fails part way through does not lose the turns it had already read, and running it twice does not capture the same session twice. An upload that does not reach back to the stored watermark is still extracted - the watermark simply holds, the turns are reported as still pending, and the response says why. A transcript too large for one request is split into chunks rather than trimmed.

A propose call is checked against the workspace’s allowance before the model is called. See /docs/metering for the dials and the refusals.

Writing a checkpoint is atomic. An interrupted write leaves no partial state, every item touched is recorded against the checkpoint with the action taken - created, updated, superseded, or rejected - and every write emits its event.

Both the terminal and the web app go through these two routes, which is why a terminal reviewer and a web reviewer leave the same record: the confirmations, edits, and rejections are written in one place and emit their events there.

A candidate that is load-bearing, or that would supersede a human-confirmed item, is held here rather than written. An agent may read this queue and must not settle it.

The rendered markdown is frozen and the item links stay live, which is deliberate: the artifact says what the sender thought mattered at the time, and the links say what the store thinks now. Those are different questions, and collapsing them would lose one of them.

GET /api/v1/usage returns this workspace’s meter for the current period: the plan, the period boundaries, each dial with its used figure, allowance, and fraction, and the headline percentage. It is the same arithmetic the quota gate enforces, so it cannot report headroom the API is refusing. See /docs/metering.

{ "error": { "code": "invalid_request", "message": "items.0.title: expected a non-empty string" } }

Validation happens before anything is read or written, so an invalid call changes nothing. A message names what was expected and what was received rather than saying the request was invalid, because the first can be acted on and the second cannot.

supersede_refused is not a failure to be retried. It means the arbiter did its job: an agent assertion that would overrule a human-confirmed item is never applied silently, and the item is now waiting in the review queue.

The body cap is deliberate rather than incidental: an unbounded transcript is an unbounded prompt. A session larger than one request is uploaded across successive calls, and the remainder is reported as pending rather than dropped.

Rate limiting is separate from metering. This is about request volume; the meter is about what an extraction costs. A read that never calls a model is subject to the first and not the second.

key_present in the health report is not working. Health never calls the provider, so it cannot see a key that authenticates and is out of credit. Read it as "a key is set", never as "extraction works".

The /api/v1 prefix is a version, and a breaking change to a route’s request or response shape means a new prefix rather than a quiet edit. Adding an optional field to a request, or a field to a response, is not a breaking change - tolerate unknown fields in what you read.

The client packages are the supported surface and they move with the API. If you are calling these routes by hand, pin nothing to the exact prose of an error message: the code is the contract, and the message is written for a person to read.