API overview

#Base URL

https://api.zanora.dev

The API is HTTPS and JSON only. A request that reaches the gateway over plain HTTP is refused with 403 INSECURE_TRANSPORT before authentication, so a key sent over HTTP isn't accepted.

#Authentication

Send your API key in the x-api-key header on every request:

curl -s https://api.zanora.dev/v1/whoami -H "x-api-key: zk.akey_….…"

These routes need no key: GET /health, the four signup routes, and the three account-recovery routes (login, password/forgot, password/reset).

Each route below lists the scope it needs. See Accounts and API keys for the full scope table.

#Tenancy comes from the key

Routes work out your providerId or workspaceId from your key. Don't send them in request bodies. They're ignored for tenant keys, and a query that names another tenant changes nothing. List routes return your records only.

#Amounts

Every amount is a string of integer minor units (cents): "priceMinor": "100" is $1.00. A JSON number is rejected with 400 VALIDATION_FAILED, never rounded. Responses use the same format. See Money and amounts.

#Request bodies

• Send content-type: application/json only when there's a body. An empty body with that header is rejected.
• Routes whose body is optional accept no body at all.
• Unknown enum values are rejected, not ignored.

#Errors

{ "error": { "code": "VALIDATION_FAILED", "message": "priceMinor must be a string of integer minor units", "details": {} } }

Handle errors by code. An unexpected error returns 500 with "internal error" and an errorId. Quote the errorId when you contact support@zanora.dev. Every code is listed in Errors and refusals.

#Rate limits

Requests are limited per key (or per IP without one), 50 per second by default. Over the limit, you get 429 RATE_LIMITED with a retry-after header. Signup and password-recovery routes have a separate, stricter per-IP limit. If you have many workers, give each its own key rather than sharing one.

#Pagination

Lists that grow over time use a cursor, not an offset:

curl -s "https://api.zanora.dev/v1/receipts?limit=50" -H "x-api-key: $KEY"
# → { "receipts": [ … ], "nextCursor": "rcp_…" }
curl -s "https://api.zanora.dev/v1/receipts?limit=50&after=rcp_…" -H "x-api-key: $KEY"

nextCursor is present only when the page came back full. An unknown cursor is refused rather than starting again from the top.

#Route index