Appearance
API reference
The document itself is generated from the server's own request and response schemas and is published with these docs at openapi.json. It covers every mounted public route — a generator-side check enumerates the router and fails if a mounted route is missing from the document, or if the document describes a path that is not mounted.
The document describes 47 operations:
| Group | Operations | Scopes |
|---|---|---|
/analytics | 7 | analytics:read |
/cards | 9 | cards:read, cards:write |
/events | 1 | none required |
/locations | 5 | locations:read, locations:write |
/me | 1 | none required |
/programs | 22 | cards:write, programs:read, programs:write, webhooks:read, webhooks:write |
/transactions | 2 | transactions:read |
23 of them are writes, and every one accepts Idempotency-Key. None of them writes a transaction — there is no such route and no such scope.
What is still missing
One thing, and it does not change the contract: the rendered, browsable reference. There is no Redoc/Scalar-style explorer on this site yet. The document itself is published here as a static asset — fetch openapi.json and read it, or import it into your HTTP client, which is what most integrators do anyway.
Every operation is now described field by field, request bodies included: issuing and updating a card are IssueCardRequest and UpdateCardRequest in components.schemas, with their properties enumerated, and both carry a worked example.
A hand-written reference drifts from the API within one release, and a drifted reference is worse than none because it is believed. Generating it means CI can do two things a reviewer cannot: regenerate and diff on every change, and assert that every mounted route appears in the document and every documented path is mounted.
Everything the reference contains is also specified on the pages around it, and none of it changes when the rendered version appears:
- the base URL and what the API does not do;
- authentication, scopes and location restriction;
- the error envelope and the full error catalogue;
- pagination and idempotency, which apply uniformly to every list and every write;
- rate limits and quotas.
What it is
- OpenAPI 3.1, checked into the repository and verified by CI on every change.
- Security scheme: HTTP bearer with a
tsk_key. Scopes per operation, so the scope a call needs is on the call, not in a paragraph. - The error envelope as a shared component, referenced by every operation.
- Cursor pagination parameters on every list.
Idempotency-Keydocumented as a header on every write.
Using it
You will not need a client library from us — see why we do not ship SDKs. Generate one from the document:
- Generate a typed client for TypeScript, PHP or Python.
- Import the same document into Postman, Bruno or Insomnia.
Start from working code instead
The quickstart walks the whole path end to end with curl, and the integration kit carries the two pieces of code you actually have to get right — signature verification and idempotent retries.