The API contract

A bearer API key

Everything else. The key resolves server-side to an account, a workspace, a role and a set of verbs. Never put it in a query string, in an error report, or in anything that records a URL.

authorization: Bearer mk_live_...

A session cookie

Used by the sign-up and sign-in routes, and by the two account routes — the one that mints an account's first master key, and the one that hands a browser its CSRF token. This is the browser's mechanism, and it is the only way to reach the endpoint that issues the first key, because before that call there is no key to authenticate with.

The CSRF token

A state-changing request authenticated by a cookie must echo this session's token in a header, because a browser attaches a cookie to a cross-site request on its own. A caller using an API key needs none of this: a browser never attaches a key by itself, so a key cannot be used cross-site.

GET  /api/v2/account/csrf-token   → { "csrf_token": "...", "header_name": "x-csrf-token" }
POST /api/v2/account/master-key   → x-csrf-token: <that token>

{
  "request_id": "23ba77f0c6474ccb8dc5d65d1a44d069",
  "data": { }
}

{
  "error": {
    "code": "version_conflict",
    "message": "…",
    "type": "invalid_request_error"
  }
}

The API never returns 200 on an error. If the status is 200 there is a data object, and if there is an error object the status says so too.

Branch on the code, never on the message. Never show a raw code to a person — map it to copy they can act on.

Put the request id somewhere copyable on any error screen. It is the first thing support will ask for, and the service logs the same value.

Nearly everything is POST.

Reads included. A read takes a body of filters, and a key belongs in a header rather than in a URL that proxies and browser history will record. The two task endpoints are the only GETs. Do not treat this as an oversight to correct.

Timestamps are unix milliseconds.

Thirteen digits, at or above 1000000000000, in both directions. A seconds-precision value is rejected rather than read as a date in 1970.

A read names exactly one subject.

The listing and the search each take one subject identifier, and it must match the memory type: a user query names a user, an agent query names an agent. Sending both always fails validation, so build the choice as a toggle rather than two fields.

Bodies are validated strictly.

An unrecognised field is a validation error, not something quietly ignored. A misspelt name fails loudly instead of appearing to work — and no field you could send names a workspace, a filter or an embedding version in the first place.