Calling the API

Everything the app does, it does through the same HTTP API you can call yourself. Every endpoint is listed in the REST API reference; this page covers the three things you need before any of them will work.

Authenticate

Send an identity token as a bearer credential:

curl -H "Authorization: Bearer <your-token>" \
     https://app.example.com/api/workflows

Tokens come from signing in. There is no separate API key to create: your API identity is your user identity, so anything you can reach in the app you can reach with curl, and nothing else.

Every endpoint requires this. There is no anonymous read: a request with no credential is refused before it reaches the endpoint, whatever the endpoint is. The handful of genuinely public paths — the pricing list, these docs — are public by explicit decision, not because authentication is optional.

Say which workspace you mean

If you belong to more than one workspace, tell us which one a request acts in:

curl -H "Authorization: Bearer <your-token>" \
     -H "X-Account-Id: <workspace-id>" \
     https://app.example.com/api/workflows

Omit it and you get your earliest workspace. Send one you are not a member of and you get your earliest workspace instead — the header selects among workspaces you already belong to, it does not grant access to one you do not.

The header is named X-Account-Id for historical reasons; the value is a workspace id. Everywhere else, the word refers to your own login.

You will only ever see your own workspaces’ data. A collection endpoint returns your rows and nothing else; asking for something in a workspace you are not a member of is refused rather than returned empty.

Which host you call matters

If your organisation runs more than one branded product, the hostname you call selects which one. The same credential on two different hosts sees two different sets of workspaces — the ones you have in each. This is deliberate: a workspace belongs to one brand, and a request has to say which brand it is for.

Reading the errors

Status	Meaning	What to do
`401`	No credential, or it is not valid	Sign in again and retry with a fresh token
`402`	The workspace has no active subscription	Reads still work; writes need a plan. See Usage and billing
`403`	Authenticated, but not yours to touch	You are not a member of that workspace, or the action needs the owner
`404`	Not found — or not yours	For resources addressed by name, we answer 404 rather than 403 so the response does not confirm something exists
`429`	Rate limited, or prepaid credit is exhausted	Slow down; if it says credit, top up

A 402 is worth understanding: an unpaid workspace becomes read-only rather than switched off. You keep access to everything already there and you can still export it — you just cannot create new work until there is a plan again. Billing and membership endpoints keep working, since those are how you fix it.

Webhooks and embeds authenticate differently

Two families of endpoint are not called by a signed-in person, so they do not use your token:

Webhook triggers carry their own token in the URL, so an external system can start a workflow without a user account.
Embed endpoints are authorised by the embed token and the list of sites allowed to use it — see Embed a widget.

Both refuse outright when the owning workspace has no active subscription, rather than degrading to read-only. A stranger on someone else’s website should not be shown a billing problem.