Développeurs Référence de l’API Version 1 · générée depuis le code openapi.json
Routes

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

WordMeaning
flowA procedure: an ordered list of steps.
stepOne screen of a flow: a title, a text and an image, each of which the author may hide.
buttonWhat leads a reader from a step to another, or ends the flow.
binderA folder: it holds flows and other binders.
spaceWhere binders and flows live: me (your own), org:<id> (an organisation), user:<id> (what someone shares with you), favorites (what you keep at hand).
publishA flow has a draft and a published version. Readers only ever get the published one; publishing replaces it with the draft.
onlineWhether 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.

ScopeOpens
readSpaces, binders, flows, steps, search, usage.
writeCreate, edit, move and duplicate; delete a step or a button; give up one's own access.
publishPublish a flow, put content online or offline.
deleteDelete binders and flows.
shareSharing rules, recipients, invitations, sharing lists.
org:adminMembers, 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.

StatuscodeMeaning
401unauthenticatedNo credential, or one that is unknown, expired or revoked.
403insufficient_scopeThe credential lacks the scope named in scope.
403forbiddenThe account may see the content but not do this to it.
403closedThe content is offline for its readers.
403quota_exceededThe plan of the space is full; metric and plan say which.
403feature_closedThe plan of the account does not include the API.
404not_foundNothing with that id, or nothing the account may open.
409conflict, refusedThe request is valid but the current state forbids it.
409confirmation_requiredA move that changes who can read the content: send it again with confirmed.
409not_publishedThe flow has no published version.
409not_by_domainThe person is not a root reader through a verified domain of the organisation.
422invalidA value is missing or malformed; field or errors say which.
429rate_limitedToo 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 PATCH only changes the fields it carries.
  • Responses are never to be cached (Cache-Control: no-store).
planner_banner_ad_pt