Référence de l’API
Cette page est générée depuis le code, en anglais.
Write, organise, publish and share step-by-step procedures.
Vocabulary
| Word | Meaning |
|---|---|
| flow | A procedure: an ordered list of steps. |
| step | One screen of a flow: a title, a text and an image, each of which the author may hide. |
| button | What leads a reader from a step to another, or ends the flow. |
| binder | A folder: it holds flows and other binders. |
| space | Where binders and flows live: me (your own), org:<id> (an organisation), user:<id> (what someone shares with you), favorites (what you keep at hand). |
| publish | A flow has a draft and a published version. Readers only ever get the published one; publishing replaces it with the draft. |
| online | Whether readers can open a binder or a flow at all. Independent of publishing. |
Authentication
Every request carries a bearer credential:
Authorization: Bearer <token>Three credentials are accepted, and nothing else is: a session cookie never authenticates a request.
- a personal token (
saw_pat_…), created in Settings › App options. It acts as its holder; - an organisation token (
saw_org_…), created by an admin in Settings › Organisation. It acts for the organisation, as a root reader or a root editor, and keeps working when its creator leaves; - an OAuth 2.1 access token, obtained by an application the user authorised (authorization code with PKCE; metadata at
/.well-known/oauth-authorization-server).
A token is shown once, when it is created. GET /me tells who a credential acts as and with which scopes.
Scopes
A credential never has more rights than the account behind it, and only the scopes it was given. Each operation states the one it requires.
| Scope | Opens |
|---|---|
read | Spaces, binders, flows, steps, search, usage. |
write | Create, edit, move and duplicate; delete a step or a button; give up one's own access. |
publish | Publish a flow, put content online or offline. |
delete | Delete binders and flows. |
share | Sharing rules, recipients, invitations, sharing lists. |
org:admin | Members, roles, domains and name of the organisation. Personal token of an admin only. |
What a reader gets
Whoever may not edit a flow gets its published version only, and never what its author hid: a hidden title or text comes back empty, a hidden image has no URL. An id you may not open answers exactly like an id that does not exist.
Errors
Errors are RFC 9457 problem documents (application/problem+json). code is the stable, machine-readable reason; detail is a sentence for a person.
| Status | code | Meaning |
|---|---|---|
| 401 | unauthenticated | No credential, or one that is unknown, expired or revoked. |
| 403 | insufficient_scope | The credential lacks the scope named in scope. |
| 403 | forbidden | The account may see the content but not do this to it. |
| 403 | closed | The content is offline for its readers. |
| 403 | quota_exceeded | The plan of the space is full; metric and plan say which. |
| 403 | feature_closed | The plan of the account does not include the API. |
| 404 | not_found | Nothing with that id, or nothing the account may open. |
| 409 | conflict, refused | The request is valid but the current state forbids it. |
| 409 | confirmation_required | A move that changes who can read the content: send it again with confirmed. |
| 409 | not_published | The flow has no published version. |
| 409 | not_by_domain | The person is not a root reader through a verified domain of the organisation. |
| 422 | invalid | A value is missing or malformed; field or errors say which. |
| 429 | rate_limited | Too many requests; Retry-After gives the seconds to wait. |
Rate limits
Per credential: 600 reads per 60 seconds and 120 writes per 60 seconds.
Idempotency
A write may carry an Idempotency-Key header (up to 255 characters). Sent again within 24 hours with the same key, the request is not run twice: the first answer comes back. The same key on a different request is refused (422 idempotency_key_reused); a key whose first request is still running answers 409 idempotency_in_progress.
Conventions
- Timestamps are UTC, ISO 8601, to the millisecond:
2026-10-05T11:41:08.000Z. - Ids are integers, unique per kind of object.
- A
PATCHonly changes the fields it carries. - Responses are never to be cached (
Cache-Control: no-store).