Web API

Authentication & API keys#

Every operation in this document is authenticated with an organisation API key, sent as the Apikey request header:

Apikey: <your key>

Getting a key#

A key is created by a signed-in user in the Locantra web app, under Settings → API keys. It acts as that user: it is bound to their organisation and carries at most the scopes and permissions they hold themselves. A key can be limited to a subset of them, and expires — 90 days from creation unless another expiry is set.

The secret is shown once, in the dialog that creates or rotates the key, and can never be read back. Store it before closing that dialog; if it is lost, rotate the key. Rotating issues a new secret and stops the old one working, so every integration using it must be updated.

Organisation scoping#

A key never sees outside its own organisation: every list is filtered to it, and an ID belonging to another organisation is refused. Most operations answer 404; a few answer 403, and each says so in its own description. Either way the answer is the same one an ID that does not exist gets, so it never confirms that an ID is in use elsewhere.

Permissions and tiers#

Each operation publishes the permission it requires as x-locantra-permission. A key missing it is answered 403. Operations marked x-locantra-tier: plus additionally need the Plus tier and answer 402 with the error code UpgradeRequired otherwise.

Rate limit#

Each key may issue 600 requests per minute by default: one fixed window per key, shared across api.locantra.de and auth.locantra.de — calling both with the same key draws down the same quota, not one each. A key-authenticated answer reports the current state in these headers; treat them as authoritative rather than hard-coding the number, and tolerate their absence:

Header	Meaning
RateLimit-Limit	Requests the key may issue in one window.
RateLimit-Remaining	Requests left in the current window.
RateLimit-Reset	Seconds until the window ends and the quota resets.

Header names are case-insensitive; on the wire they arrive as Ratelimit-Limit etc.

Exceeding it answers 429 with the error code RateLimitExceeded and a Retry-After header in seconds. Pace off RateLimit-Remaining rather than waiting for the 429.

Idempotent writes#

Operations marked x-locantra-idempotent accept an Idempotency-Key header: a free-form string of 1–128 characters, unique per logical operation (a UUID is the usual choice). Retrying with the same key replays the stored response instead of executing the write again, for 24 hours; a replay carries Idempotent-Replayed: true and is otherwise identical to the original answer. The key is scoped to your organisation and to the operation, so the same key sent to a different operation is a different key.

Status	Error code	When
400	IdempotencyKeyInvalid	The header is empty or longer than 128 characters.
409	IdempotencyInProgress	The first request with this key is still running — retry shortly.
422	IdempotencyKeyReused	This key was already used with a different body. Use a new key.

Server errors are never stored, so a retry after a 5xx really does re-run the operation. A request without the header is never idempotent.

Pagination#

Entity lists page by offset: Limit (each operation documents its default and maximum) and Offset. The response envelope's Page carries the applied Limit and the Total number of matches. Where an operation documents a Cursor parameter it pages by keyset instead: pass the Cursor from the previous response's Page.NextCursor; an empty NextCursor means the last page. A cursor is opaque — pass it back unchanged. On operations with neither, Limit only caps the rows returned.

Response envelope and errors#

Every response is the same envelope: Message (human-readable), Data (the payload), Page on a paged list, and Error on a failure. Error is a stable machine-readable code — branch on it, not on Message. On a validation failure Message names the fields that failed.

Streaming operations#

Operations marked x-locantra-stream: sse answer a server-sent event stream instead of a single body: one data: frame per event as JSON, with a : keepalive comment every 15 seconds to hold the connection open. Frames carry no event name and no id, so a dropped connection resumes at the present rather than where it left off. Streams are capped per organisation — an operation's description states its cap, and exceeding it answers 429.

Versioning and deprecation#

This document is the contract: only the operations it lists are covered. The public surface is additive-only — new endpoints, new optional fields and new values of an open enum can appear at any time, and anything else is a breaking change that goes through deprecation first. A deprecated operation is marked deprecated: true here, its responses carry Deprecation (RFC 9745), Sunset (RFC 8594) once a date is set, and Link: <replacement>; rel="successor-version" when there is one, and it stays available for at least six months. info.version tracks the release that produced this document. The full policy is published alongside these docs.