Skip to content

HTTP API ​

Everything the app does, it does through these routes — and so can anything holding an API key:

bash
curl https://notes.example.com/api/pages -H "authorization: Bearer $NOTESFLOW_API_KEY"

A workspace is addressed by prefixing a path with /api/w/<slug>, or by the host where the deployment uses subdomains. /api/… on its own means the default workspace.

Keys says whether an API key may call the route at all. The routes that mint credentials or administer the deployment are a person’s, whatever a key carries.

Retrying safely ​

A write can succeed and still look as though it failed — the connection drops between the server doing it and the answer arriving. Send every write with an Idempotency-Key of your own, new for each request, and send the same key when you retry it:

bash
curl -X POST https://notes.example.com/api/pages/$PAGE/merge \
  -H "authorization: Bearer $NOTESFLOW_API_KEY" \
  -H "idempotency-key: $(uuidgen)" -H "content-type: application/json" -d @merge.json

A repeat is answered with the first response, marked idempotent-replayed: true, and nothing is done twice. The same key on a different request is refused with 422; while the first is still running a repeat gets 409 and should be retried shortly. Keys last 24 hours. Without one, a merge retried after a lost response appends everything it added a second time.

Pages and blocks ​

MethodPathNeedsKeysWhat it does
GET/api/pagesread access to the pageyesThe page tree, annotated with what this caller may do to each page; ?archived=1 or ?trashed=1 for those instead.
POST/api/pagesthe create_root_pages capabilityyesCreate a page, under a parent or at the root; templateId starts it as a copy of that page, under fresh ids. With a parent, write access to the parent is what is needed instead. With templateId, read access to that page as well — the copy is a read of it — and with no parentId the page goes beside the template where the caller may write there, otherwise at the root (parentId: null asks for the root).
GET/api/pageread access to the pageyesOne page by id, as a query parameter.
GET/api/pages/{pageId}read access to the pageyesOne page and its blocks; ?format=markdown for the file instead, with the block ids a merge-back needs.
PATCH/api/pages/{pageId}write access to the pageyesRename, move, place among siblings (before: a sibling, or null for last), archive (archived: true, with everything under it), or set a page’s properties. Send If-Match with the etag from a read to be refused (412) rather than overwrite a change you have not seen.
DELETE/api/pages/{pageId}write access to the pageyesMove a page and everything under it to the trash.
GET/api/pages/{pageId}/writtenread access to the pageyesWhen each block now on the page was written, and by whom: the time of its first create, which nothing moves. Never limited by a package’s page history; a block typed seconds ago is absent until the recorder has written it.
POST/api/pages/{pageId}/restorewrite access to the pageyesBring a page back from the trash.
POST/api/pages/{pageId}/purgewrite access to the pageyesPurge a trashed page and everything trashed under it, with every version of everything on them (ADR 0048). confirm is the page title. Needs purge_content; refused while the workspace is on hold.
POST/api/pages/{pageId}/redactwrite access to the pageyesPreview, or with apply: true carry out, redacting text from every version of a page (ADR 0048). Your own writing needs nothing more; anybody else's needs purge_content.
GET/api/pages/{pageId}/redactionsread access to the pageyesWhich blocks of a page were redacted, and when. Ids and times, never what was removed.
GET/api/pages/{pageId}/historyread access to the pageyesWhat was written here, and by whom.
GET/api/pages/{pageId}/atread access to the pageyesThe page as it read at an instant (?t=).
POST/api/pages/{pageId}/formatwrite access to the pageyesChange how a page is edited: rich, or markdown (ADR 0015). Without apply: true it says what would change; rich to Markdown turns callouts into quotes and database views into tables of their rows.
POST/api/pages/{pageId}/revertwrite access to the pageyesMake the page read as it did, as a new edit.
POST/api/pages/{pageId}/mergewrite access to the pageyesMerge externally edited Markdown back in; ?propose=1 proposes it instead. A paragraph both sides changed is refused by default, with both versions as Markdown (workspace, file). clashes: "propose" writes the rest and files the file’s version of each clash as a proposal on the page; resolutions: [{ blockId, take: "workspace" | "file", seen }] decides one, taking the file’s only over the version seen quotes.
GET/api/pages/{pageId}/backlinksread access to the pageyesWhich blocks link here.
GET/api/pages/{pageId}/mentionsread access to the pageyesPlaces that say this page’s name without linking to it.
POST/api/pages/{pageId}/linkwrite access to the pageyesTurn one of those mentions into a link.
GET/api/pages/{pageId}/commentsread access to the pageyesThe comment threads on this page.
GET/api/pages/{pageId}/accessread access to the pageyesWho this page is shared with.
PUT/api/pages/{pageId}/accesswrite access to the pageyesShare the page with somebody, or withdraw it.
POST/api/pages/{pageId}/offlinewrite access to the pageyesOffer when edits made offline actually happened.
GET/api/pages/{pageId}/proposalsread access to the pageyesChanges proposed for this page.
POST/api/pages/{pageId}/proposalsread access to the pageyesPropose a change to this page. Suggesting needs comment access; deciding needs write.
GET/api/pages/{pageId}/watchread access to the pageyesWhether you are being told about this page.
PUT/api/pages/{pageId}/watchread access to the pageyesStart or stop being told about this page. Read-level on purpose: being told about a page is not editing it.
POST/api/journals/capturethe create_root_pages capabilityyesWriting captured on a phone ({text, at, date}): appended to the journal for date, made if need be, and dated at — the writer’s own clock, believed within the offline window, as /offline is. ADR 0035, step 5. Write access to that journal as well. text is read as Markdown. Retried safely with an Idempotency-Key.
POST/api/journalsthe create_root_pages capabilityyesToday’s journal, created if this is the first writing of the day — or, with { period }, the note for an ISO week (2026-W43) or a month (2026-10), made on first use (ADR 0040).
GET/api/blocks/{blockId}read access to the pageyesOne block’s current text, for a reference.
GET/api/blocks/{blockId}/provenanceread access to the pageyesWho wrote this block, when, and who has touched it since.
PATCH/api/blocks/{blockId}/nameswrite access to the pageyesName a block so it can be referenced (anchor, or generate: true), or make it and the blocks up to through a region (region) — ADR 0015.
PATCH/api/blocks/{blockId}/timelinewrite access to the pageyesPlace a block on a day, pin it, or keep it out of the timeline.
PATCH/api/blocks/{blockId}/taskwrite access to the pageyesTick a task, or set or clear its fields (checked, due, start, horizon, priority, state, repeat, assignee; null clears) — ADR 0040.

Content ​

MethodPathNeedsKeysWhat it does
GET/api/scim/v2/UsersanybodynoSCIM 2.0 for a company’s directory (ADR 0023): /Users and /Groups with GET (and filter=&lt;attr&gt; eq "…"), POST, PUT, PATCH and DELETE; /ServiceProviderConfig and /ResourceTypes. Provisioning a person invites them; deprovisioning removes them as an admin would. A directory group is a group here. Guarded by a directory sync token from /api/scim-tokens, which also names the workspace — not by a session or a key.
GET/api/trialanybodynoWhether trials are offered here, and the trial this browser holds, if any (ADR 0049).
POST/api/trialanybodynoTry it: a workspace of this browser’s own on the trial package, kept by a cookie. Opens the trial this browser already holds instead of making a second. Limited per network; refused while trials are off, with no trial package, or at the cap.
POST/api/trial/recoveranybodynoA recovery key brings its trial to this browser; every other copy of the trial’s cookie stops working. Body: { key, replace? }. 409 with confirm: true when this browser holds another trial. Limited per network; a wrong key says the same as one never issued.
POST/api/trial/forgetanybodynoForget this browser’s trial: its cookie is expired. The recovery key still finds it.
GET/api/trial/keya signed-in person (not a key)noThe trial’s recovery key, to its own browser only.
POST/api/trial/keya signed-in person (not a key)noMake the trial a new recovery key; the old one stops working.
POST/api/trial/key/saveda signed-in person (not a key)noThe recovery key was copied or downloaded: the workspace stops asking.
PUT/api/trial/namea signed-in person (not a key)noWhat the timeline calls the trial’s writer until they sign up.
POST/api/claima signed-in person (not a key)noKeep this trial in the signed-in account: it becomes an ordinary workspace with the account as its admin (ADR 0049 §6). Needs both this browser’s trial cookie and a session.
GET/app/authorizeanybodynoThe phone app asks for this browser’s session (ADR 0036): ?challenge=&lt;S256 of the app’s verifier&gt;&device=&lt;name&gt;. Not signed in, sends the browser to sign in and back; signed in, asks whether to sign in the app, on a page with no script.
POST/app/authorizeanybodynoThe yes from that page: a one-minute, single-use code, sent to the app as notesflow://signed-in?code=…. Only from the page itself (same origin), and only with a session cookie.
GET/app/editoranybodynoThe editor this deployment runs, for the phone app to keep (ADR 0035, step 3): its fingerprint and every file with its SHA-256. 404 when no bundle built from this server’s editor is present.
GET/app/editor/{path}anybodynoOne file the manifest lists, as inert bytes (application/octet-stream, a sandbox): it is a page for the app’s own origin, never this one.
POST/api/csp-reportsanybodynoWhere the web app’s Content Security Policy sends what it blocked (ADR 0030): a report-uri body or a Reporting API array. Logged at warn as csp violation and passed to the error tracker. Limited per network; always 204.
POST/api/client-errorsanybodynoA browser reports an error (ADR 0029): {kind, name, message, stack, path}. Scrubbed of addresses and tokens, logged at warn and passed to the error tracker. Limited per network; always 204.
POST/api/referencesread access to the pageyesWhat references point at, and what to call blocks in them: resolves targets like Weekly review#^decision, names blocks, and with covers returns what each shows. Only pages the caller can read. Answers only about pages the caller may read; anything else is null.
POST/api/device/importa signed-in person (not a key)noWriting a device saved to a file, brought back (ADR 0034 §6, Level 1). The body is the file’s contents, read in the browser; a preview of what would happen to each block unless ?apply=1, and ?restoreTrashed=1 to put trashed pages back. Written where the page still has what the device last saw, filed as a proposal where it moved on, recovered into a page only the caller can read where the page is gone. Only the account that made the file may import it: writing is credited to whoever imports it.
GET/api/device/policya signed-in person (not a key)noWhether this workspace refuses saving everything on a device to a file (refuseDeviceExport, ADR 0034 §6). The app keeps what it last heard and applies it offline; set with PATCH /api/workspace.
POST/api/device/exportsa signed-in person (not a key)noA device saying it made a file of what it holds, for the workspace’s audit log (device.export). Records; permits nothing, since the file was made with no request at all.
GET/api/updates/factsread access to the pageyesWhat happened in a period for the caller, from the log (ADR 0044): done, moved on, slipped, stalled, waiting, new, written, decided. ?period=week|lastweek|since&today=YYYY-MM-DD&tz=.
POST/api/updates/draftwrite access to the pageyesDraft the caller’s update for a period as a page under their own Updates page, each fact linking to its block (ADR 0044). Nothing is sent. { period, today, tz }.
GET/api/tasks.icsread access to the pageyesThe caller’s open tasks with a day, as an iCalendar feed (ADR 0040 §8): one all-day event each. ?key= from a read-only key, as for the Atom feed. 403 where the workspace refuses task feeds.
GET/api/briefingread access to the pageyesThe morning briefing beyond what is due (ADR 0045 §5): the Taskflow steps that are the caller’s now (steps, each with its task) and the open suggestions waiting on their decision (waiting), from pages they may read.
GET/api/chata signed-in person (not a key)noThe caller’s chat apps (ADR 0047): for Telegram and Signal, whether each is offered here, the bot’s name or the number, whether they have linked it, and how many words this workspace allows.
POST/api/chat/telegrama signed-in person (not a key)noA single-use link, good for ten minutes, that connects the caller’s Telegram when opened there ({url, expiresAt}). A message sent to the bot is saved in this workspace. 409 with no bot on this deployment.
POST/api/chat/signala signed-in person (not a key)noA single-use code, good for ten minutes, for the caller to send as link &lt;code&gt; from their own Signal to the deployment’s number ({code, number, url, expiresAt}). 409 with no Signal number on this deployment.
PATCH/api/chat/{channel}a signed-in person (not a key)noAsk for fewer words than the workspace allows in Telegram, Signal or WhatsApp: {words: "link"|"titles"|"full"|null}.
DELETE/api/chat/{channel}a signed-in person (not a key)noDisconnect the caller’s Telegram, Signal or this workspace’s WhatsApp.
POST/api/chat/whatsappa signed-in person (not a key)noA single-use code, good for ten minutes, for the caller to send as link &lt;code&gt; to this workspace’s own WhatsApp number, and a wa.me link that fills it in ({code, number, url, expiresAt}). 409 when this workspace has no WhatsApp account.
GET/api/chat/whatsapp/accountthe manage_notices capabilitynoThis workspace’s own WhatsApp business account (ADR 0047 step 4): the number, the template a notice goes out with outside the 24 hours, and the webhook’s address and verify token to give Meta. Never the token or the app secret.
PUT/api/chat/whatsapp/accountthe manage_notices capabilityno{phoneNumberId, token?, appSecret?, templateName?, templateLanguage?}: tried (Meta must say whose number it is) and kept, sealed. A token or secret left out keeps the saved one. 422 with Meta’s words otherwise.
DELETE/api/chat/whatsapp/accountthe manage_notices capabilitynoForget this workspace’s WhatsApp account, and everybody’s link to it.
GET/api/chat/whatsapp/webhook/{workspaceId}anybodynoMeta’s handshake for a workspace’s webhook: hub.challenge back when hub.verify_token is the one its console shows; 403 otherwise.
POST/api/chat/whatsapp/webhook/{workspaceId}anybodynoWhere Meta delivers what people send a workspace’s WhatsApp number, signed with its app secret in X-Hub-Signature-256; 401 unless the signature is that workspace’s.
GET/api/chat/wordsa signed-in person (not a key)noHow many words this workspace’s notices carry into each chat app (ADR 0047 §2): link, titles or full.
PUT/api/chat/wordsthe manage_notices capabilityno{channel, words}: set it. Needs manage_notices.
POST/api/chat/telegram/webhookanybodynoWhere Telegram delivers what people send the bot, with the secret it was pointed with in X-Telegram-Bot-Api-Secret-Token; 401 without it.
POST/api/draftsthe use_assistant capabilitynoWrite a page up with the assistant (ADR 0046): {pageId}, a page the caller may write. Planned in the background as the caller, through their own session; written at once or after they look, as their mode says. 202 {draft}.
GET/api/draftsa signed-in person (not a key)noThe caller’s drafts, newest first, with each plan, its questions, and what was written; ?page= for one page’s.
POST/api/drafts/{id}a signed-in person (not a key)noA draft waiting for its person: {answers: [option, …]} plans it again with them; {write: true} writes a plan with no questions; {undone: true} records that what it wrote was undone.
GET/api/assistant/guidesa signed-in person (not a key)noThe assistant’s writing guides (ADR 0046 §4): How we write here and the caller’s How I write, each with whether it is read — not if somebody who may not write it has changed it since it was chosen — and who did.
PUT/api/assistant/guidesa signed-in person (not a key)no{which: "workspace"|"mine", pageId}: choose a page the caller may write as a guide, approving it as it stands. The workspace’s needs manage_assistant.
DELETE/api/assistant/guidesa signed-in person (not a key)no?which=workspace|mine: stop reading that guide. The workspace’s needs manage_assistant.
GET/api/drafts/modea signed-in person (not a key)noHow much the assistant does with the caller’s drafts on its own: ask, unsure (the default) or go, and what the workspace’s ceiling leaves of it.
PUT/api/drafts/modea signed-in person (not a key)no{mode}: set it, or null for the default.
GET/api/assistant/indexa signed-in person (not a key)yesThe assistant’s index (ADR 0045 §3): the reader’s settings and why it stopped, pages read and items noted, what reading the workspace once would cost, and this month’s background credits.
PUT/api/assistant/indexthe manage_assistant capabilityyes{enabled?, endpoint?}: switch the reader on or off, and choose its model — platform, one of the workspace’s own, or null for the default. Never a member’s own model.
POST/api/assistant/index/readthe manage_assistant capabilityyesRead what is due now rather than at the next quarter hour. 202 {queued}.
GET/api/index/pages/{id}read access to the pageyesWhat the assistant noted about one page, current and superseded, and whether the page is kept away from it.
POST/api/index/items/{id}/wrongread access to the pageyesThis is wrong: {reason?}. The note is not used again, and the next reading of its page is told.
GET/api/index/recallread access to the pageyesNotes from pages the caller may read, by ?q= or ?subject=, ?kind=, ?history=1 for superseded ones too: what the assistant’s recall tool asks.
GET/api/findingsread access to the pageyesWhat could be better, found in the background without a model (ADR 0045 §4): findings citing only pages the caller may read, for anybody or addressed to them. ?page=, ?mine=1, ?kind=. With checkedAt (the last run) and checking.
POST/api/findings/checkread access to the pagenoLook for findings again now rather than at the next morning’s run. Asking while a run waits asks for that run (queued: false). 202 {queued}.
POST/api/findings/{id}write access to the pageyesDismiss a finding, or say it was not useful ({state: "dismissed"|"not_useful"}): by whoever it is addressed to, or, addressed to nobody, by somebody who may edit its page. 404 for one the caller cannot see.
GET/api/tasksread access to the pageyesTasks on pages the caller may read, in sections (ADR 0040): ?for=me|all|{accountId}, ?status=open|done|all, ?today=YYYY-MM-DD, ?page=, ?under= (a page and its subtree), ?q=, ?doneDays=, ?period=2026-W43|2026-10 (a week’s or a month’s note).
GET/api/searchread access to the pageyesFull-text search over the workspace (?q=); ?archived=1 includes archived pages.
GET/api/timelineread access to the pageyesWhat was written, by day, ordered by when it happened. ?fold=N folds one person's writing on one page in a day into one row from N entries up: the row is the newest entry, with folded (how many) and authoredCount; ask with ?page= and ?actor= for that day to read them all.
GET/api/timeline/newsread access to the pageyesWhether the timeline has moved on since ?after= (a head from an earlier answer): how many readable pages have new writing in the range. Takes the timeline's own filters (from, to, tz, actor, page, hidden) and answers {head, pages}. Counts by arrival, so an edit made offline and synced late is news too.
GET/api/feed.atomread access to the pageyesThe last thirty days of the timeline as an Atom feed: one entry per page per day, titles and names but never page text (?page= for one page). A feed reader cannot send a header, so ?key= is accepted here and nowhere else — and only from a key whose scopes are exactly ["read"].
GET/api/exportthe export_workspace capabilityyesEvery readable page as Markdown, paged by ?after= — the whole workspace without a request per page.
GET/api/statethe export_workspace capabilityyesThe whole-workspace fingerprint an export mirror runs on.
POST/api/commentsread access to the pageyesComment on a block, optionally quoting part of it.
POST/api/comments/{commentId}/resolveread access to the pageyesResolve a thread, or reopen it.
DELETE/api/comments/{commentId}read access to the pageyesDelete your own comment.
GET/api/starsa signed-in person (not a key)yesThe pages you starred, most recent first, leaving out any you can no longer open.
PUT/api/starsread access to the pageyesStar or unstar a page ({pageId, starred}); needs no more than reading it.
GET/api/autolinksread access to the pageyesThis workspace’s short references: each {prefix, url}, where &lt;num&gt; in the address is the number after the prefix. Empty for a caller who can read no page here.
PUT/api/autolinksthe manage_workspace capabilityyesReplace the whole list ({autolinks: [{prefix, url}]}); at most 50, each address http or https.
GET/api/notificationsa signed-in person (not a key)yesWhat you have been told, newest first; ?unread=1 for only the new. Filtered by what you may read now, not by what you could read when it was written.
POST/api/notifications/reada signed-in person (not a key)yesMark notifications read, by id or all of them.
GET/api/filesread access to the pageyesThe files in this workspace.
POST/api/fileswrite access to the pageyesUpload a file against the page it belongs to (?page=, x-filename).
GET/api/files/{fileId}read access to the pageyesThe bytes, behind the permission of the page they hang on.
GET/api/templatesread access to the pageyesThe template gallery (ADR 0038): this workspace's templates the caller may read, the built-in catalogue, and its shelves.
GET/api/templates/previewread access to the pageyesWhat a template says (?id= a page id or a built-in's id), its placeholders unfilled. A page template needs read access to that page.
POST/api/templates/installthe create_root_pages capabilityyesTake a built-in template into this workspace ({templateId, parentId?}): a template: true copy remembering its version in template_source, under the workspace's Templates page unless placed elsewhere. The Templates page is made at the root the first time; with a parent, write access to it is what is needed instead.
POST/api/templates/usethe create_root_pages capabilityyesMake a page from a template ({templateId, parentId?, title?, props?, values?}): a page id or a built-in's id, with placeholders filled from values.date (YYYY-MM-DD) and values.time (HH:MM) as the reader sees them. A kit's id sets up the kit — its pages, views and templates — and answers with its home page. Placed as POST /api/pages places a page from a template; a built-in's pages go to the root. A date placeholder with no values.date is left as typed.
GET/api/journal-templateread access to the pageyesWhich template an empty journal offers first: {workspace, mine, offered}, each {templateId, title} or null — the caller's own choice wins for them. A choice naming a page the caller cannot read, or one trashed, is answered as null. Only an offer: opening a journal writes nothing.
PUT/api/journal-templateread access to the pageyesSet or clear a journal template ({scope: "workspace" | "mine", templateId: string | null}): a page template's id or a built-in page template's id. scope: "workspace" needs manage_workspace.
POST/api/templates/snippetwrite access to the pageyesA template's blocks to insert into a page ({templateId, pageId, values?, props?, apply?}): filled, under fresh ids that the caller's own edit then creates as the template's, so the timeline shows them as started from a template rather than written. Writes nothing unless apply (the blocks go at the end of the page) or props (the template's properties the page does not have yet). Read access to a page template is needed too.
GET/api/templates/updateread access to the pageyesWhether the built-in a workspace template was taken from has a newer version (?pageId=): {update: {title, from, to, proposal}}, or {update: null}.
POST/api/templates/updatewrite access to the pageyesOffer a workspace template the newer version of its built-in ({pageId}), as a proposal on it: the difference between the two versions, merged against the page when it is applied. Answers with the one already open, if there is one. Writes nothing to the page. Applying the proposal moves its template_source to the new version.
POST/api/recordsthe create_root_pages capabilityyesSet up numbered records ({series?, title?, parentId?}, ADR by default): an index page with a view of the series, and the numbered template beneath it. Under a parent, write on that page instead. A page started from the template gets the next number in its series.
GET/api/viewsread access to the pageyesThe saved views of this workspace.
POST/api/viewsthe manage_views capabilityyesSave a view.
GET/api/views/{viewId}read access to the pageyesA view, evaluated: its rows and columns now.
PATCH/api/views/{viewId}the manage_views capabilityyesChange a view’s query, columns or layout.
DELETE/api/views/{viewId}the manage_views capabilityyesDelete a view. The pages it showed are untouched.
POST/api/views/{viewId}/movewrite access to the pageyesMove a card between board columns, which writes the property on its page.
POST/api/proposals/{proposalId}/applywrite access to the pageyesAccept a proposal, block by block.
POST/api/proposals/{proposalId}/closewrite access to the pageyesClose a proposal without applying it.
POST/api/import/previewthe create_root_pages capabilityyesWhat importing this folder would do. Writes nothing.
POST/api/import/pagesthe create_root_pages capabilityyesCreate the pages an import needs.
POST/api/import/contentwrite access to the pageyesWrite the imported content into those pages.
GET/api/sharedanybodyyesPages shared with you from other workspaces.
GET/api/billingthe manage_billing capabilityyesThis workspace’s billing (ADR 0026): who invoices are made out to, its issued invoices (never drafts), what it owes per currency, and whether its package is on hold for an unpaid one.
PUT/api/billing/profilethe manage_billing capabilityyesWho invoices are made out to: {legalName, email, address, taxId}. The email, when set, is where invoice notices go. The tax rate is the operator’s and is not written here.
GET/api/billing/invoices/{id}the manage_billing capabilityyesOne of this workspace’s invoices, with its lines, payments, credit notes and refunds.
GET/api/billing/invoices/{id}/documentthe manage_billing capabilityyesThe invoice as a printable HTML page (save it as PDF from the browser). Served with a policy that runs no script.
GET/api/billing/credit-notes/{id}/documentthe manage_billing capabilityyesA credit note against one of this workspace’s invoices, as a printable HTML page. Served with a policy that runs no script.
GET/api/plan/choicesthe manage_workspace capabilityyesThe packages this workspace may ask for (those an operator offers), what is in force now, and the request it has open (ADR 0025).
POST/api/plan/requestthe manage_workspace capabilityyesAsk for an offered package for this workspace: {planId, note?}. Replaces any open request. An operator approves or declines it; nothing changes until then.
DELETE/api/plan/requestthe manage_workspace capabilityyesWithdraw this workspace’s open package request.
GET/api/planthe list_members capabilityyesThis workspace’s package (ADR 0024): its name, where it comes from (workspace, owner, default or none), when it ends, every feature with whether it is included, and the limits. A route a package does not include answers 402 with { error, feature, reason: "package" }.
GET/api/scim-tokensthe manage_members capabilityyesThis workspace’s directory sync tokens, and the SCIM endpoint they unlock.
POST/api/scim-tokensthe manage_members capabilityyesMake a directory sync token ({label}), shown once. ADR 0023.
DELETE/api/scim-tokens/{token}the manage_members capabilityyesRevoke a directory sync token.
GET/api/sign-in-policythe manage_sso capabilityyesHow members must sign in here: through SSO, with a second factor, without a password.
PATCH/api/sign-in-policythe manage_sso capabilityyesRequire members to have given a second factor, or refuse password sessions. A member signed in any other way is refused here until they sign in as asked. ADR 0019. Refused when the caller’s own session would not meet it. Visitors, break-glass access and API keys are not affected.
GET/api/accounta signed-in person (not a key)noYour account: name, address, and any move to a new address still waiting.
PATCH/api/accounta signed-in person (not a key)noChange your name (it shows on everything you ever wrote) and what reaches your inbox: notifications.muted lists kinds switched off, notifications.autoWatch whether taking part in a page starts watching it.
POST/api/account/emaila signed-in person (not a key)noAsk to move to a new address. A link goes there; nothing changes until it is followed.
DELETE/api/account/emaila signed-in person (not a key)noWithdraw a move to a new address. The link sent stops working.
GET/api/account/sessionsa signed-in person (not a key)noWhere you are signed in, by handle — never by session id.
DELETE/api/account/sessionsa signed-in person (not a key)noSign out everywhere but here.
DELETE/api/account/sessions/{handle}a signed-in person (not a key)noEnd one session, and close the pages it has open.
GET/api/account/billinga signed-in person (not a key)noYour own account’s billing (ADR 0026): details, invoices, what you owe, and any hold. Also /profile (PUT), /invoices/{id}, /invoices/{id}/document and /credit-notes/{id}/document, as for a workspace.
GET/api/account/plana signed-in person (not a key)noYour own package (ADR 0025): what governs how many workspaces you may start and the workspaces you own without one, the offered packages, and your open request.
POST/api/account/plan/requesta signed-in person (not a key)noAsk for an offered package for your own account: {planId, note?}. An operator decides.
DELETE/api/account/plan/requesta signed-in person (not a key)noWithdraw your open package request.
GET/api/account/identitiesa signed-in person (not a key)noWhich workspaces’ SSO may sign you in, having been confirmed once.
DELETE/api/account/identities/{connection}a signed-in person (not a key)noStop a workspace’s SSO signing you in without asking your email again.
POST/api/account/deletiona signed-in person (not a key)noAsk to erase your account. A link goes to your address; nothing happens until it is followed and confirmed.
DELETE/api/account/deletiona signed-in person (not a key)noWithdraw a request to erase your account. The link sent stops working.
PUT/api/account/passworda signed-in person (not a key)noSet or change your password. Every other session ends and your address is told. Changing needs current; setting a first one needs a sign-in from the last ten minutes.
DELETE/api/account/passworda signed-in person (not a key)noRemove your password; sign in by link from then on. Needs current.
POST/api/account/two-stepa signed-in person (not a key)noStart setting up two-step sign-in: answers the secret and an otpauth:// address for an authenticator app. Needs password, or a sign-in from the last ten minutes when there is no password.
DELETE/api/account/two-stepa signed-in person (not a key)noSwitch two-step sign-in off, with a current code or a recovery code.
POST/api/account/two-step/confirma signed-in person (not a key)noFinish setting up two-step sign-in with the first code from the app. Answers ten recovery codes, shown once.
POST/api/account/recovery-codesa signed-in person (not a key)noReplace your recovery codes, with a current code. The old ones stop working.
DELETE/api/account/membershipa signed-in person (not a key)noLeave this workspace. Your keys here are revoked; your writing stays. The last admin is refused.
GET/api/workspacethe manage_workspace capabilitynoThis workspace’s icon, who may join without an invitation, and what they become.
PATCH/api/workspacethe manage_workspace capabilitynoChange them: icon (one character, or null), joinPolicy (null to follow the deployment, "invitation" or "open"), defaultRole (any role here but admin). "open" admits accounts the deployment already has; it never creates one.
GET/api/export.zipthe export_workspace capabilityyesThe whole workspace as a zip — Markdown pages, sidecars, views and attachments, as pnpm export:git writes them — limited to what you may read.
GET/api/assistantthe use_assistant capabilitynoThe assistant as it is for you here: the models you may use, your choices capped by the workspace’s ceilings, and which model a new conversation would use.
GET/api/assistant/settingsthe manage_assistant capabilitynoThe workspace’s policy and its own models, and whether the deployment has a model of its own.
PUT/api/assistant/policythe manage_assistant capabilitynoChange the workspace’s policy: on or off, members’ own models, the platform’s model, the ceilings on writing and removing, the default model, how long conversations are kept.
PUT/api/assistant/preferencesthe use_assistant capabilitynoYour own default model and what the assistant may do without asking you. Kept as chosen and capped by the ceilings as it is read.
POST/api/assistant/endpointsthe use_assistant capabilitynoAdd a model: scope: "workspace" (manage_assistant) or "mine" (where the policy allows). Tried with a tool call before it is saved; refused with the provider’s own words. The key is sealed and never returned.
PUT/api/assistant/endpoints/{endpointId}the use_assistant capabilitynoChange a model, tried again before it is saved. Omit apiKey to keep the saved one.
DELETE/api/assistant/endpoints/{endpointId}the use_assistant capabilitynoRemove a model, and every default that named it.
POST/api/assistant/endpoints/{endpointId}/trythe use_assistant capabilitynoTry a saved model as it is saved. Answers ok, or the reason it did not answer.
GET/api/assistant/threadsthe use_assistant capabilitynoYour conversations with the assistant here, newest first. Nobody else’s, ever.
GET/api/assistant/threads/{threadId}the use_assistant capabilitynoOne of your conversations: what was asked, what it said, which tools it used and how each run ended.
DELETE/api/assistant/threads/{threadId}the use_assistant capabilitynoForget one of your conversations.
POST/api/assistant/runsthe use_assistant capabilitynoAsk the assistant: message, and optionally threadId, the open pageId, a model and your today. Answers as server-sent events — thread (with the run’s id), thinking, tool, ask, tool_done (with how to undo a write), text, done — and acts as you: reading and suggesting always, writing as your choices and the workspace’s ceilings allow, asking first where they say to.
POST/api/assistant/runs/{runId}/answerthe use_assistant capabilitynoAnswer a write the assistant asked about: callId and answer — apply, always (apply, and stop asking in this conversation; not for removing) or decline. From the person whose run it is, signed in; never from the run.
GET/api/webhooksthe manage_webhooks capabilitynoWhere this workspace sends word of what happens here.
POST/api/webhooksthe manage_webhooks capabilitynoPoint an endpoint at this workspace’s events; format: "mattermost" or "slack" posts each as a chat message for that chat’s incoming webhook. The signing secret is in the answer, and never again.
POST/api/webhooks/{webhookId}/testthe manage_webhooks capabilitynoQueue a test delivery, to see it arrive and verify the signature.
GET/api/webhooks/{webhookId}/deliveriesthe manage_webhooks capabilitynoRecent deliveries, with what the endpoint answered.
DELETE/api/webhooks/{webhookId}the manage_webhooks capabilitynoStop sending to an endpoint. Its history is kept.
GET/api/workspacesanybodyyesThe workspaces this account belongs to.
POST/api/workspacesan operator, or anybody the deployment’s workspace-creation policy admitsyesMake a workspace, or ask for one when the deployment wants an operator to approve it. Answers 201 with the workspace when it was made, 202 with a request when it waits for an operator. A key may call it only for an operator; asking is a person’s act.
GET/api/workspaces/requestsa signed-in person (not a key)noThe workspaces you have asked for, and what became of each.
POST/api/workspaces/requests/seena signed-in person (not a key)noSay the outcome of your decided requests has been shown to you, so it is not shown again.
DELETE/api/workspaces/requests/{requestId}a signed-in person (not a key)noWithdraw a request of yours that is still waiting.

People and permissions ​

MethodPathNeedsKeysWhat it does
GET/api/membersthe list_members capabilityyesWho is in this workspace.
PATCH/api/members/{accountId}the manage_members capabilityyesChange what somebody may do here.
DELETE/api/members/{accountId}the manage_members capabilityyesRemove somebody from this workspace.
GET/api/invitationsthe manage_invitations capabilityyesInvitations outstanding.
POST/api/invitationsthe manage_invitations capabilityyesInvite an address, naming the role it may join as.
DELETE/api/invitations/{invitationId}the manage_invitations capabilityyesWithdraw an invitation.
GET/api/groupsthe manage_groups capabilityyesThe groups pages can be shared with.
POST/api/groupsthe manage_groups capabilityyesMake a group.
PATCH/api/groups/{groupId}the manage_groups capabilityyesRename a group, or change who is in it.
DELETE/api/groups/{groupId}the manage_groups capabilityyesDelete a group.
GET/api/rolesthe list_members capabilityyesThe roles this workspace has, preset and its own.
POST/api/rolesthe manage_roles capabilityyesWrite a role: a named set of capabilities and a default page level.
PATCH/api/roles/{roleId}the manage_roles capabilityyesChange a role.
DELETE/api/roles/{roleId}the manage_roles capabilityyesDelete a role nobody holds.
GET/api/usagethe list_members capabilityyesWhat this workspace is using against its quotas: pages, bytes, members and sites, and the limits in force (its package with any operator override).
GET/api/auditthe read_audit capabilityyesThis workspace’s audit log.
GET/api/ssothe manage_sso capabilityyesThis workspace’s identity provider connections.
POST/api/ssothe manage_sso capabilityyesConnect an identity provider.
PATCH/api/sso/{connectionId}the manage_sso capabilityyesChange a connection, or the domains it admits.
DELETE/api/sso/{connectionId}the manage_sso capabilityyesDisconnect a provider. Refused for the last enabled connection while SSO is required.
GET/api/sso/requirementthe manage_sso capabilityyesWhether members must sign in through this workspace’s own SSO.
PUT/api/sso/requirementthe manage_sso capabilityyesRequire (or stop requiring) members to sign in through this workspace’s own SSO. A member signed in any other way is refused here until they do. Turning it on needs an enabled connection, and the caller signed in through one. Visitors, break-glass access and API keys are not affected.
GET/api/sso/{connection}/mappingsthe manage_sso capabilityyesWhich of the provider’s groups give which role or keep which group in step here, in order, and the claim they are read from.
PUT/api/sso/{connection}/mappingsthe manage_sso capabilityyesReplace them ({groupClaim?, mappings: [{idpGroup, role?, groupId?}]}). Applied at each sign-in through the connection. ADR 0022. The first mapping with a role that matches decides it; none matching means the connection’s default role. The last admin is never demoted this way.
POST/api/sso/{connection}/verifythe manage_sso capabilityyesProve a domain by its DNS TXT record ({domain}). Takes over another workspace’s unproven claim; refused for a proven one. ADR 0021. 409 with the record to publish while it is not there yet.

Published sites ​

MethodPathNeedsKeysWhat it does
GET/api/sitesthe publish_sites capability, or manager on that siteyesThe sites this caller runs, with how many pages are live and how many are waiting for review. With ?page=<id>, the published sites that page is live on. With ?page=, read access to that page is enough.
POST/api/sitesthe publish_sites capabilityyesStart a site from a page. It begins as a draft, restricted, with only that page chosen. Body: { rootPageId, title?, slug?, audience?: public | signed_in | restricted }.
GET/api/sites/{siteId}the publish_sites capability, or manager on that siteyesOne site: its settings, its list of people, and what is live.
PATCH/api/sites/{siteId}the publish_sites capability, or manager on that siteyesChange a site’s title, address or audience. Making a published site public needs { confirm: <slug> }.
DELETE/api/sites/{siteId}the publish_sites capabilityyesDelete a site: it stops being served, and its address is free.
GET/api/sites/{siteId}/sitemapthe publish_sites capability, or manager on that siteyesThe sitemap to review: every page under the root and every page decided about, with what is live, what the next publish changes, and what nobody has reviewed.
PUT/api/sites/{siteId}/pagesthe publish_sites capability, or manager on that siteyesChoose pages for the site or leave them off. Takes effect at the next publish. Body: { decisions: [{ pageId, publish, path? }] }. Choosing a page needs read access to it.
POST/api/sites/{siteId}/publishthe publish_sites capability, or manager on that siteyesPublish exactly the reviewed pages. 409 with the current sitemap if it changed since it was reviewed. Body: { pages: <the sitemap’s proposed ids> }.
POST/api/sites/{siteId}/unpublishthe publish_sites capability, or manager on that siteyesTake a site down. Its decisions are kept for the next publish.
PUT/api/sites/{siteId}/membersthe publish_sites capability, or manager on that siteyesName somebody on a site’s list as a viewer or a manager, or take them off it. Body: { email | subject: group:<id> | workspace:<id>, role: viewer | manager | null }.
GET/sites/{site}/whoever the site’s audience admits: anybody, anybody signed in, or its listnoA published site’s home page, as HTML. Answered before any workspace is resolved, with no script allowed. Sign-in is by the browser session; keys are not accepted.
GET/sites/{site}/{path}whoever the site’s audience admits: anybody, anybody signed in, or its listnoA published page, as HTML. ?preview shows a manager what the next publish would serve.
GET/sites/{site}/_handoffanybodynoWith a sites domain: hand the signed-in session to the site’s own subdomain, by a signed one-minute token. Sends somebody signed in nowhere to sign in first. ?to=<path on the site>. On the subdomain, /_auth takes the token once and sets a cookie for that host alone.
GET/sites/{site}/searchwhoever the site’s audience admits: anybody, anybody signed in, or its listnoSearch a site’s own pages, as HTML. ?q= is the question; nothing off the site is ever searched.
GET/sites/{site}/sitemap.xmlwhoever the site’s audience admits: anybody, anybody signed in, or its listnoEvery page the site serves, for search engines.
GET/sites/{site}/files/{pageId}/{fileId}whoever the site’s audience admits: anybody, anybody signed in, or its listnoAn attachment of a published page.

Credentials ​

MethodPathNeedsKeysWhat it does
GET/api/keysa signed-in person (not a key)noYour API keys; ?all=1 for everybody’s. all=1 needs manage_api_keys.
POST/api/keysa signed-in person (not a key)noMake a key. The token is in the answer, and never again.
POST/api/keys/{keyId}/rotatea signed-in person (not a key)noNew secret, same key and scopes.
DELETE/api/keys/{keyId}a signed-in person (not a key)noRevoke a key. Revoked stays revoked.
GET/api/servicesthe list_members capabilitynoThe service identities of this workspace.
POST/api/servicesthe manage_members capabilitynoMake a service identity and its first key.
DELETE/api/services/{accountId}the manage_members capabilitynoDisable a service identity and revoke its keys.

The deployment ​

MethodPathNeedsKeysWhat it does
GET/api/platform/assistantan operator of the deploymentnoThe platform’s model for the assistant: the console’s or the environment’s, what a credit is and costs past a package’s, and each workspace’s credits this month.
PUT/api/platform/assistantan operator of the deploymentnoSet the platform’s model — address, model, key, protocol, tokens a credit, a credit’s price past a package — tried with a tool call before it is saved. Owner only; the key is sealed and never returned.
DELETE/api/platform/assistantan operator of the deploymentnoForget the console’s model; the environment’s, if any, is used again.
GET/api/platform/workspacesan operator of the deploymentnoEvery workspace, with counts. No titles.
PATCH/api/platform/workspaces/{slug}an operator of the deploymentnoRename, re-address, suspend or set the quotas of a workspace. An old address stays reserved to it and keeps working.
GET/api/platform/trialsan operator of the deploymentnoEvery trial: its address, its identity and when it was last opened — never its content (ADR 0049).
GET/api/platform/trials/settingsan operator of the deploymentnoThe trial switch, package, clocks and cap, and whether trials can work on this deployment.
PUT/api/platform/trials/settingsan operator of the deploymentnoSet any of: enabled (on, off, or null to follow NOTESFLOW_TRIAL_WORKSPACES), plan, inactiveDays, graceDays, cap. An owner only.
POST/api/platform/trials/{slug}/revokean operator of the deploymentnoRevoke a trial’s identity: its cookie stops working and the trial is scheduled for deletion.
POST/api/platform/workspaces/{slug}/deletionan operator of the deploymentnoSchedule a workspace for deletion: read-only at once, purged after a grace period. An owner only. Body: { confirm: <slug>, days?: 1–365, default 30 }.
DELETE/api/platform/workspaces/{slug}/deletionan operator of the deploymentnoCancel a scheduled deletion. Nothing has been lost until the purge runs.
GET/api/platform/accountsan operator of the deploymentnoAccounts across the deployment, by address or name, with how many workspaces each is in.
PATCH/api/platform/accounts/{accountId}an operator of the deploymentnoDisable an account — sessions, keys, sign-in and live sockets — or enable it again. Memberships are kept.
GET/api/platform/operatorsan operator of the deploymentnoWho operates the deployment: owners and support.
PUT/api/platform/operatorsan operator of the deploymentnoAppoint an owner or support, or step one down. An owner only; never the last owner.
DELETE/api/platform/accounts/{accountId}/credentialsan operator of the deploymentnoStart an account’s sign-in over: its password, two-step sign-in and recovery codes are removed and its sessions end. An owner only.
GET/api/platform/sign-inan operator of the deploymentnoHow people get in: sign-up, what a workspace does with newcomers by default, passwords, the breach check, personal workspaces.
PATCH/api/platform/sign-inan operator of the deploymentnoChange how people get in. An owner only. Opening sign-up is refused while sign-in links are only printed.
GET/api/platform/oauthan operator of the deploymentnoThe deployment’s own sign-in providers (Google, GitHub): where each one’s setting comes from, whether it is offered, and the redirect URI to paste into it.
PUT/api/platform/oauth/{provider}an operator of the deploymentnoAn owner only. Set a provider’s client id and secret, or switch it on or off. Overrides the environment for that provider. The secret is sealed and never returned. ADR 0020.
DELETE/api/platform/oauth/{provider}an operator of the deploymentnoForget the console’s setting for a provider; the environment decides again.
GET/api/platform/purgingan operator of the deploymentnoWhat a purge does on this deployment: erase, or keep out of sight (ADR 0048).
PATCH/api/platform/purgingan operator of the deploymentnoSet what a purge does: erase, retain, or null to follow NOTESFLOW_PURGE_MODE. An owner only.
GET/api/platform/settingsan operator of the deploymentnoWho may create workspaces, how many each person may start, and the quotas those start with.
PATCH/api/platform/settingsan operator of the deploymentnoSet the workspace-creation policy or the per-account limit. An owner only.
GET/api/platform/creation-overridesan operator of the deploymentnoAccounts that are an exception to the workspace-creation policy.
PUT/api/platform/creation-overridesan operator of the deploymentnoMake one account an exception to the policy, or return it to it. An owner only.
GET/api/platform/workspace-requestsan operator of the deploymentnoRequests for new workspaces: those waiting, then recent decisions.
POST/api/platform/workspace-requests/{requestId}an operator of the deploymentnoApprove or decline a request. Approving makes the requester the new workspace’s admin.
GET/api/platform/plansan operator of the deploymentnoEvery package (ADR 0024) with how many workspaces and accounts are on it, the default, the closed list of features with what each does when it lapses, and the limit dimensions.
POST/api/platform/plansan operator of the deploymentnoAn owner only. Make a package: {id, name, description?, price?, features: [...], limits: {pages, members, bytes, sites, workspaces}}. A limit of null is no limit.
PUT/api/platform/plans/{plan}an operator of the deploymentnoAn owner only. Replace a package’s fields, or send only {archived} to archive or restore it. Everybody on it gets the change at once.
DELETE/api/platform/plans/{plan}an operator of the deploymentnoAn owner only. Delete a package nothing is on; 409 otherwise — archive it instead.
GET/api/platform/plan-requestsan operator of the deploymentnoCustomers’ package requests (ADR 0025), newest first. ?status= pending (the default), approved, declined, withdrawn or all.
POST/api/platform/plan-requests/{id}an operator of the deploymentnoAn owner only. Decide a request: {decision: "approve" | "decline", until?, reason?}. Approving assigns the package; whoever asked is told either way.
GET/api/platform/billingan operator of the deploymentnoWhat to bill for a period (ADR 0025): ?from=&to= (UTC days, this month by default), one line per workspace and per account with a priced package of its own — who pays, the package, peak seats, and one interval’s amount in cents — with totals per currency. &format=csv for a spreadsheet.
GET/api/platform/billing/settingsan operator of the deploymentnoWho invoices, and how (ADR 0026): seller name, address and tax ID, footer, default tax label and rate (basis points), payment terms, grace days before a hold, number prefix, and whether drafts are issued automatically.
PUT/api/platform/billing/settingsan operator of the deploymentnoAn owner only. Change any of them.
GET/api/platform/billing/customeran operator of the deploymentnoOne customer’s billing, by ?workspace=&lt;slug&gt; or ?account=&lt;email&gt;: details, tax override, hold, invoices, and account credit (balance and entries).
PUT/api/platform/billing/customeran operator of the deploymentnoAn owner only. Set a customer’s tax override {taxRate (basis points, or null), taxLabel, taxNote}, or release a hold with {held: false}.
GET/api/platform/invoicesan operator of the deploymentnoEvery invoice, newest first. ?status= all, draft, open, paid, void or overdue; ?period=2026-09.
POST/api/platform/invoices/runan operator of the deploymentnoAn owner only. Draft a period that has ended: {period: "2026-09"} or {period: "2026"}. One draft per customer and currency; a customer that has one is skipped.
GET/api/platform/invoices/{id}an operator of the deploymentnoOne invoice with its lines and payments. /document for the printable page.
DELETE/api/platform/invoices/{id}an operator of the deploymentnoAn owner only. Delete a draft; an issued invoice is voided instead.
POST/api/platform/invoices/{id}/issuean operator of the deploymentnoAn owner only. Issue a draft: its number, tax, due date and both parties are fixed from now on, and the customer is told.
POST/api/platform/invoices/{id}/voidan operator of the deploymentnoAn owner only. Void an invoice with no payments and no credit notes: {reason}, which the customer reads. Anything else is credited.
POST/api/platform/invoices/{id}/paymentsan operator of the deploymentnoAn owner only. Record money received: {amount (cents), method?, reference?, receivedAt?}. Paid in full releases any hold it caused.
POST/api/platform/invoices/{id}/credit-notesan operator of the deploymentnoAn owner only. Credit an issued invoice, open or paid: {reason, amount (cents before tax)} or {reason, full: true}. Tax is credited at the invoice’s own rate. The invoice is never edited; what is owed falls, and a fully covered invoice is settled and releases any hold.
POST/api/platform/invoices/{id}/refundsan operator of the deploymentnoAn owner only. Record money paid back: {amount (cents), method?, reference?, refundedAt?}. Never more than was paid beyond what is owed once credits are counted, nor more than was paid in money.
POST/api/platform/invoices/{id}/carryan operator of the deploymentnoAn owner only. Keep what an invoice owes back as the customer’s account credit instead of paying it out: {amount?} (cents; everything owed back when left out). Spent at once on anything else they owe in that currency.
GET/api/platform/errorsan operator of the deploymentnoWhere errors are reported (ADR 0029): whether a tracker is set, its host and environment, and how many errors were sent, held back as repeats, or could not be sent since the server started.
POST/api/platform/errorsan operator of the deploymentnoAn owner only. Send a test error to the tracker and wait for it: 201 when it left, 502 when the tracker could not be reached, 409 with no tracker, 429 within a minute of the last.
GET/api/platform/chat/telegraman operator of the deploymentnoThe deployment’s Telegram bot (ADR 0047 §5): from the console or the environment, its name, and whether Telegram delivers to a webhook or is asked. Never the token.
PUT/api/platform/chat/telegraman operator of the deploymentnoAn owner only. {token}: tried (who is the bot? can it be pointed?) and kept, sealed, only if both answer. 422 with Telegram’s words otherwise.
DELETE/api/platform/chat/telegraman operator of the deploymentnoAn owner only. Forget the console’s bot; the environment’s, if any, is used again.
GET/api/platform/chat/signalan operator of the deploymentnoThe deployment’s Signal bridge (ADR 0047 step 3, experimental): from the console or the environment, its address and number.
PUT/api/platform/chat/signalan operator of the deploymentnoAn owner only. {url, number}: the operator’s signal-cli-rest-api is asked whether it answers and has that number, and kept only if both. 422 with the bridge’s words otherwise.
DELETE/api/platform/chat/signalan operator of the deploymentnoAn owner only. Forget the console’s bridge; the environment’s, if any, is used again.
GET/api/platform/mailan operator of the deploymentnoHow mail leaves this deployment (ADR 0028): smtp, webhook or console (printed, not delivered), described without any secret, and whether that was set here (source: console) or by the environment (ADR 0033); and queue, the notices that failed and are being tried again or were given up on (ADR 0032).
POST/api/platform/mailan operator of the deploymentnoAn owner only. Send a test message to your own address, never anybody else's. 502 with what the mail server said when it cannot be sent.
POST/api/platform/mail/retryan operator of the deploymentnoAn owner only. Try every queued notice again now, given-up ones included, and answer the queue as it stands after (ADR 0032).
PUT/api/platform/mail/settingsan operator of the deploymentnoAn owner only. Set how mail leaves, overriding the environment (ADR 0033): transport: smtp with host, port, security (tls or starttls), username, password, from, replyTo and brand — tried against the relay first, and not saved if it refuses (422) — or transport: webhook with an https url and secret. An omitted password or secret keeps the saved one. Never answers the secret.
DELETE/api/platform/mail/settingsan operator of the deploymentnoAn owner only. Forget the console's mail settings; the environment decides again.
GET/api/platform/backupsan operator of the deploymentnoBackups (ADR 0027): whether this server takes them (pglite, postgres for none taken here, or off), how often and how many are kept, the last attempt and any error, the backups on disk, and the schema version with every migration applied. Never a download.
POST/api/platform/backupsan operator of the deploymentnoAn owner only. Take a backup now. 409 when this server takes none, or one is already being taken.
GET/api/platform/creditsan operator of the deploymentnoEvery customer holding account credit, per currency.
POST/api/platform/creditsan operator of the deploymentnoAn owner only. Add account credit to a customer, or take it away with a negative amount: {workspace | account, currency?, amount (cents), reason}. The reason is shown to the customer. Added credit is spent at once on their open invoices, oldest first, and on every invoice issued to them afterwards.
GET/api/platform/credit-notes/{id}/documentan operator of the deploymentnoA credit note as a printable HTML page.
GET/api/platform/default-planan operator of the deploymentnoThe package for every workspace and account nobody assigned one. Null: everything, unlimited.
PUT/api/platform/default-planan operator of the deploymentnoAn owner only. Set it ({planId}, or null).
GET/api/platform/workspaces/{slug}/planan operator of the deploymentnoA workspace’s own package and end date, whose account it falls back to, the operator’s feature overrides and limit overrides, and what is in force.
PUT/api/platform/workspaces/{slug}/planan operator of the deploymentnoAn owner only. Any of {planId, until, ownerEmail, featureOverrides}; a field left out is left alone. until past is the trial’s end: the workspace falls back to its owner’s package, then the default. ADR 0024. Limit overrides go through PATCH /api/platform/workspaces/{slug} with limits.
GET/api/platform/accounts/{accountId}/planan operator of the deploymentnoAn account’s own package: what the workspaces it owns fall back to, and how many workspaces it may start.
PUT/api/platform/accounts/{accountId}/planan operator of the deploymentnoAn owner only. Any of {planId, until, workspaces}.
GET/api/platform/auditan operator of the deploymentnoThe deployment-wide audit log.
GET/api/platform/break-glassan operator of the deploymentnoBreak-glass grants, current and past.
POST/api/platform/break-glassan operator of the deploymentnoLet yourself into a workspace, with a reason and an expiry.
DELETE/api/platform/break-glass/{grantId}an operator of the deploymentnoEnd a break-glass grant.

Signing in ​

MethodPathNeedsKeysWhat it does
GET/api/auth/meanybodyyesWho this caller is here, and what they may do.
POST/api/auth/logoutanybodynoEnd this session.
POST/api/auth/request-linkanybodynoSend a sign-in link to an address.
POST/api/auth/redeemanybodynoTurn a sign-in link into a session.
POST/api/auth/app/tokenanybodynoThe phone app swaps the code and its verifier for a device token: a session of its own, made the way the browser’s was. Sent as Authorization: Bearer nfa_…. ADR 0036. A code is spent by any attempt, right or wrong.
POST/api/auth/app/ticketanybodynoA ten-minute ticket for the editor in the app’s WebView, minted from the device token. Good as Authorization: Bearer nft_… and as ?ticket= on a page’s socket; refused for anything under /api/auth (but me), /api/account, /api/keys and /api/platform. ADR 0036. 401 without a device token; a cookie or a ticket cannot mint one.
PUT/api/auth/app/pushanybodynoThis phone’s address for notices ({platform: android|ios, token, base}), held by the app’s session; answers whether the deployment has a push relay to send through. ADR 0037. The device token only: 401 for a cookie or nothing, 403 for a ticket. A notice carries ids, never words. The address moves to whichever session registers it last.
DELETE/api/auth/app/pushanybodynoStop sending this phone notices. ADR 0037. The device token only. Signing the phone out does this too.
POST/api/auth/confirm-emailanybodynoFollow the link sent to a new address: the account moves there, and its other sessions end. The token is the proof; it works without a session so it can be opened on another device.
POST/api/auth/confirm-deletionanybodynoFollow the link sent to erase an account: name and address are erased, everything it belongs to is left, the id stays so history still resolves. Irreversible. Refused while the account is the last admin of a workspace or the last owner of the deployment.
GET/api/auth/optionsanybodynoWhat the sign-in page may offer: OAuth providers, whether passwords are on, and whether a new address may sign up.
POST/api/auth/signupanybodynoSign up with an address, a name and a password. Sends a link to confirm the address; the account is made when it is followed and the password typed again. Answers { sent: true } whatever the address, so it cannot be used to learn which addresses have accounts.
POST/api/auth/passwordanybodynoSign in with an address and a password. Answers a session, or { twoStep: { challenge } } when the account has two-step sign-in. One answer for every failure. Repeated wrong passwords make the next try wait, per account.
POST/api/auth/two-stepanybodynoFinish a sign-in with a code from an authenticator app, or a recovery code. A challenge allows five tries and lasts five minutes.
POST/api/auth/resetanybodynoForgot the password: sends a link to choose a new one. Answers { sent: true } whatever the address.
POST/api/auth/reset/confirmanybodynoFollow the reset link with a new password. Every session of the account ends; it does not sign in.
POST/api/auth/sso/confirmanybodynoConfirm a first sign-in through a workspace’s SSO from the mailed link, in the browser that signed in. Links the provider’s subject to the account. ADR 0018. 409 from any other browser; may answer a two-step challenge.
GET/api/auth/ssoanybodynoWhether an address’s domain has an identity provider connected.
GET/api/auth/sso/{connectionId}/startanybodynoBegin single sign-on against a workspace’s provider.
GET/api/auth/sso/{connectionId}/callbackanybodynoThe provider’s answer.
GET/api/auth/{provider}/startanybodynoBegin OAuth sign-in.
GET/api/auth/{provider}/callbackanybodynoThe provider’s answer.

The process ​

MethodPathNeedsKeysWhat it does
GET/api/healthanybodyyesLiveness: the process is running.
GET/api/readyanybodyyesReadiness: the database answers and the server is not draining.
GET/api/metricsanybodyyesPrometheus metrics. Absent unless NOTESFLOW_METRICS_TOKEN is set. Guarded by its own bearer token, not by a session or a key.

Blocks and the op log are canonical. Markdown is a projection. Git is a target.