Skip to main content
One HTTP API, versioned at /v1, JSON in and JSON out.
Examples throughout these guides use $API for that base. The playground on each endpoint page already points at it.

​
Requests

Content-Type: application/json on anything with a body. Bodies are capped at 1 MiB; an oversized one fails at the reader rather than being buffered into memory first. Credentials ride Authorization: Bearer:
Nothing else is accepted. No query parameter — it would land in access logs and browser history. No cookie — this API is not cookie-authenticated, which is also why CORS never needs credentials. The exception is the publishable key, which travels in the body of the endpoints that accept it, alongside the data those endpoints need anyway. See Authentication.

​
The active organization

Session-authenticated routes act on one organization. Which one comes from a header:
It identifies; it does not authorize. The membership JOIN is what authorizes, so a code you are not a member of resolves nothing. Omitted, the session’s default organization answers.

​
Responses

Success is a 2xx with a JSON body, except 204, which has none.
202 is not “queued”. On forgot-password, signup and the magic-link flows it means “accepted, and the answer would be the same either way” — the API does not reveal whether an address has an account.
Errors are always the same envelope:
Branch on code. See Errors.

​
Timestamps

RFC 3339, UTC:
A nullable timestamp is null, never an empty string or a zero date.

​
Identifiers

UUIDs, except for two:
  • organization public code — org_<32 hex>, what goes in URLs and the X-Organization-Id header;
  • credential prefixes — uk_sk_, uk_pk_, uk_st_, uk_ct_, and the one-time token families.
The internal organization UUID never leaves the API on the surfaces the panel uses.

​
Pagination

Collection reads take limit and offset:
The cap is deliberate: enough for a screen, small enough that nobody accidentally downloads their whole audience.
Out-of-range values are not an error — they fall back to the default. Do not rely on a 400 to catch a bad page size.

​
Environments

On the machine surface, the environment is the key’s environment, resolved from the stored row on every request. There is no parameter for it. On the panel surface, reads take ?environment=live|test, defaulting to live. Both are covered in Environments.

​
Rate limits

Public and credential endpoints are throttled per IP; boot is additionally throttled per publishable key. See Rate limits.

​
The surfaces

Staff plane

uk_st_…. Sign-in, account, organizations, members, roles, keys, and the panel view of contacts.

Machine surface

uk_sk_…. /v1/me and /v1/contacts — your backend talking about your own users.

Customer plane

Publishable key in the body. /v1/boot and /v1/contact-auth/*, called from your pages.

Contact surface

uk_ct_…. /v1/contact/me — one of your users reading their own record.