API

The Setrya API is the backend on your settlement host. It serves the web app and nothing else: every request has to come through the web tier, which proves itself with a shared key. This page covers how the two connect, the request rules, the response format, the error codes and every endpoint.

How requests reach the API

The browser never calls the API directly. It calls /api/v1/... on the web app's own origin, and the web app relays the request.

The relay refuses a request body over 4 MB with HTTP 413. If the API can't be reached, it answers HTTP 502 with code INTERNAL and the message "The settlement server is not reachable. Try again in a moment."

The web tier connects with three settings:

Edge headers

Every request under /api/ must carry the edge key. Without it, the API answers HTTP 403 with code FORBIDDEN and "This endpoint is not public."

GET /healthz answers {"ok":true} without the edge key, for container health checks.

Sessions and access levels

Signing in sets an HttpOnly, SameSite=Strict cookie named setrya_session. A session lasts 12 hours, or 7 days if you chose to stay signed in. The API stores only a SHA-256 hash of the token.

Each endpoint needs one of three access levels:

A missing session gets UNAUTHENTICATED. A locked vault gets VAULT_LOCKED. Actions that move money, approve a period, export data or change security also need a fresh step-up token, which you get from POST /api/v1/auth/step-up with your password. A step-up is tied to one action and to the exact state it covers, such as the snapshot hash and the recipients, and is used up once spent.

Request rules

Every request other than GET and HEAD must pass all three checks, or it gets HTTP 403 with code CSRF_REJECTED:

• The Origin header must be one of the origins in SETRYA_PUBLIC_ORIGIN, which is a comma-separated list.
• The body must be application/json or multipart/form-data.
• The header x-setrya-request: 1 must be present.

JSON bodies may be up to 256 KB. A body that doesn't match the endpoint's schema gets INVALID_INPUT with a message for each field.

Response format

A success returns HTTP 200:

{ "ok": true, "data": { "id": "6f0c…" }, "requestId": "3d2b9a1e-…" }

Amounts are strings of whole zatoshis or exact decimals, never floating-point numbers. bigint values are sent as strings.

An error returns this shape:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Check the highlighted fields.",
    "fieldErrors": { "displayName": "Enter a name" },
    "canRetry": false,
    "recoveryAction": "/sign-in"
  },
  "requestId": "3d2b9a1e-…"
}

fieldErrors and recoveryAction appear only when they apply. An unexpected failure returns INTERNAL with "Something failed on the server. Reference" and the first 8 characters of the request ID, which you can find in the API's logs. File downloads, such as CSV exports and backups, return the file itself instead of this envelope.

Error codes

A few endpoints override the status, for example a refused setup token returns 403.

Views

Server-rendered pages read their data from one endpoint:

GET /api/v1/views/:name?param=value

A view returns the same envelope, encoded so that bigint, Date and Map values survive the trip. It is sent as application/vnd.setrya.wire+json, and those values are tagged:

{ "$setrya": "bigint", "v": "460000000" }
{ "$setrya": "date", "v": "2026-10-28T12:00:00.000Z" }
{ "$setrya": "map", "v": [["partner-id", { "…": "…" }]] }

An unknown view name returns 404. Most views need unlocked access and take a projectId parameter.

Endpoints

All paths start with /api/v1. :projectId and the other path parameters are UUIDs.

Setup and sign-in

Projects and sources

Revenue

Partners and agreements

Periods and rates

Payments

Statements and sharing

Backups

Rate limits

Unauthenticated and sensitive endpoints are limited for each client address or session, for example 8 sign-ins every 5 minutes for each address and each email, 6 unlock attempts every 5 minutes, 5 setup attempts a minute, 10 step-ups every 5 minutes, 10 prepares a minute and 30 share fetches a minute. A limited request gets RATE_LIMITED with canRetry: true.