Skip to content

API Reference ​

This page renders docs/generated/openapi.json through an interactive reference: every route below can be sent for real. It targets the API of this exact page's own environment — the staging docs call the staging API, the production docs call the production API, and neither can reach the other, by CORS policy as well as by the server this page is built with. That file is generated by npm run openapi:generate from the running application and its Zod schemas, verified byte for byte by npm run openapi:check, and never edited by hand — so this page always reflects what the service actually exposes, not a snapshot of it. The same file is served as /openapi.json.

What it exposes today is 292 operations on 238 paths (counted from that file): identity (accounts, sessions, sign-in methods, second factors, password, step-up, invitations, memberships, roles, approvals by PIN, ownership grants), the organization and its structure (guided onboarding, sites, brands, legal entities, business units, outlets, outlet groups, schedules, sales channels), the platform plans and subscription, assets, the catalog (138 operations), settings, the audit trail, stock locations, the price list, and sales at an outlet. Business routes are served under /api/v1/.... What is not built (payments, till, credit, promotions, quotas and availability, supply-route administration and receiving have no route) and the conventions every client needs (errors, Idempotency-Key, If-Match, pagination, the permission each route needs) are in the client integration guide; each flow has a diagram in System flows.

Get a token, then try a route ​

  1. POST /sign-ups with a password and either an email (identifierType: "email") or a phone number plus its ISO country (identifierType: "phone", country: "EC") — never a phone number under "email".
  2. Confirm it with the code that route sends: POST /sign-ups/confirmations.
  3. POST /sign-ins with the same credentials. The response body's data.accessToken is your session.
  4. Open Authentication in the panel below, select the session scheme, and paste that token there once. Every request this page sends afterward carries it as Authorization: Bearer <token>, until you replace or clear it.

A padlock on a route means it needs that token. Adding, confirming or removing a way in needs one more thing (so do staff commands that move money or change what is sold: assigning or changing a plan, recording a payment, archiving an organization, publishing or retiring a plan version, publishing or withdrawing an offering, and opening a market): a live elevation from POST /step-ups/confirmations, sent as the X-Elevation-Token header shown on that specific route. Mint it right before the call — it is bound to the session asking and is not meant to be reused across requests.

The two health probes below stay unversioned and unprefixed on purpose — Railway's healthcheck depends on that exact path, and they are deliberately outside the data envelope.

Staging data is disposable. Anything created against the staging API can be reset or deleted without notice. Never sign up with a real email/phone number or an account anyone depends on. Production docs never target staging, and staging docs never target production: each site is wired, at build time, to the one API origin that matches it, and the API's own CORS allowlist only accepts requests from that matching docs origin.

Last updated:

Application Foundation in progress. Tracked in issue #13.