Appearance
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.jsonA 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
| Method | Path | Needs | Keys | What it does |
|---|---|---|---|---|
GET | /api/pages | read access to the page | yes | The page tree, annotated with what this caller may do to each page; ?archived=1 or ?trashed=1 for those instead. |
POST | /api/pages | the create_root_pages capability | yes | Create 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/page | read access to the page | yes | One page by id, as a query parameter. |
GET | /api/pages/{pageId} | read access to the page | yes | One 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 page | yes | Rename, 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 page | yes | Move a page and everything under it to the trash. |
GET | /api/pages/{pageId}/written | read access to the page | yes | When 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}/restore | write access to the page | yes | Bring a page back from the trash. |
POST | /api/pages/{pageId}/purge | write access to the page | yes | Purge 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}/redact | write access to the page | yes | Preview, 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}/redactions | read access to the page | yes | Which blocks of a page were redacted, and when. Ids and times, never what was removed. |
GET | /api/pages/{pageId}/history | read access to the page | yes | What was written here, and by whom. |
GET | /api/pages/{pageId}/at | read access to the page | yes | The page as it read at an instant (?t=). |
POST | /api/pages/{pageId}/format | write access to the page | yes | Change 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}/revert | write access to the page | yes | Make the page read as it did, as a new edit. |
POST | /api/pages/{pageId}/merge | write access to the page | yes | Merge 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}/backlinks | read access to the page | yes | Which blocks link here. |
GET | /api/pages/{pageId}/mentions | read access to the page | yes | Places that say this page’s name without linking to it. |
POST | /api/pages/{pageId}/link | write access to the page | yes | Turn one of those mentions into a link. |
GET | /api/pages/{pageId}/comments | read access to the page | yes | The comment threads on this page. |
GET | /api/pages/{pageId}/access | read access to the page | yes | Who this page is shared with. |
PUT | /api/pages/{pageId}/access | write access to the page | yes | Share the page with somebody, or withdraw it. |
POST | /api/pages/{pageId}/offline | write access to the page | yes | Offer when edits made offline actually happened. |
GET | /api/pages/{pageId}/proposals | read access to the page | yes | Changes proposed for this page. |
POST | /api/pages/{pageId}/proposals | read access to the page | yes | Propose a change to this page. Suggesting needs comment access; deciding needs write. |
GET | /api/pages/{pageId}/watch | read access to the page | yes | Whether you are being told about this page. |
PUT | /api/pages/{pageId}/watch | read access to the page | yes | Start or stop being told about this page. Read-level on purpose: being told about a page is not editing it. |
POST | /api/journals/capture | the create_root_pages capability | yes | Writing 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/journals | the create_root_pages capability | yes | Today’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 page | yes | One block’s current text, for a reference. |
GET | /api/blocks/{blockId}/provenance | read access to the page | yes | Who wrote this block, when, and who has touched it since. |
PATCH | /api/blocks/{blockId}/names | write access to the page | yes | Name 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}/timeline | write access to the page | yes | Place a block on a day, pin it, or keep it out of the timeline. |
PATCH | /api/blocks/{blockId}/task | write access to the page | yes | Tick a task, or set or clear its fields (checked, due, start, horizon, priority, state, repeat, assignee; null clears) — ADR 0040. |
Content
| Method | Path | Needs | Keys | What it does |
|---|---|---|---|---|
GET | /api/scim/v2/Users | anybody | no | SCIM 2.0 for a company’s directory (ADR 0023): /Users and /Groups with GET (and filter=<attr> 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/trial | anybody | no | Whether trials are offered here, and the trial this browser holds, if any (ADR 0049). |
POST | /api/trial | anybody | no | Try 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/recover | anybody | no | A 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/forget | anybody | no | Forget this browser’s trial: its cookie is expired. The recovery key still finds it. |
GET | /api/trial/key | a signed-in person (not a key) | no | The trial’s recovery key, to its own browser only. |
POST | /api/trial/key | a signed-in person (not a key) | no | Make the trial a new recovery key; the old one stops working. |
POST | /api/trial/key/saved | a signed-in person (not a key) | no | The recovery key was copied or downloaded: the workspace stops asking. |
PUT | /api/trial/name | a signed-in person (not a key) | no | What the timeline calls the trial’s writer until they sign up. |
POST | /api/claim | a signed-in person (not a key) | no | Keep 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/authorize | anybody | no | The phone app asks for this browser’s session (ADR 0036): ?challenge=<S256 of the app’s verifier>&device=<name>. 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/authorize | anybody | no | The 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/editor | anybody | no | The 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} | anybody | no | One 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-reports | anybody | no | Where 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-errors | anybody | no | A 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/references | read access to the page | yes | What 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/import | a signed-in person (not a key) | no | Writing 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/policy | a signed-in person (not a key) | no | Whether 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/exports | a signed-in person (not a key) | no | A 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/facts | read access to the page | yes | What 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/draft | write access to the page | yes | Draft 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.ics | read access to the page | yes | The 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/briefing | read access to the page | yes | The 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/chat | a signed-in person (not a key) | no | The 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/telegram | a signed-in person (not a key) | no | A 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/signal | a signed-in person (not a key) | no | A single-use code, good for ten minutes, for the caller to send as link <code> 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) | no | Ask 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) | no | Disconnect the caller’s Telegram, Signal or this workspace’s WhatsApp. |
POST | /api/chat/whatsapp | a signed-in person (not a key) | no | A single-use code, good for ten minutes, for the caller to send as link <code> 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/account | the manage_notices capability | no | This 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/account | the manage_notices capability | no | {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/account | the manage_notices capability | no | Forget this workspace’s WhatsApp account, and everybody’s link to it. |
GET | /api/chat/whatsapp/webhook/{workspaceId} | anybody | no | Meta’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} | anybody | no | Where 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/words | a signed-in person (not a key) | no | How many words this workspace’s notices carry into each chat app (ADR 0047 §2): link, titles or full. |
PUT | /api/chat/words | the manage_notices capability | no | {channel, words}: set it. Needs manage_notices. |
POST | /api/chat/telegram/webhook | anybody | no | Where 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/drafts | the use_assistant capability | no | Write 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/drafts | a signed-in person (not a key) | no | The 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) | no | A 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/guides | a signed-in person (not a key) | no | The 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/guides | a 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/guides | a signed-in person (not a key) | no | ?which=workspace|mine: stop reading that guide. The workspace’s needs manage_assistant. |
GET | /api/drafts/mode | a signed-in person (not a key) | no | How 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/mode | a signed-in person (not a key) | no | {mode}: set it, or null for the default. |
GET | /api/assistant/index | a signed-in person (not a key) | yes | The 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/index | the manage_assistant capability | yes | {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/read | the manage_assistant capability | yes | Read what is due now rather than at the next quarter hour. 202 {queued}. |
GET | /api/index/pages/{id} | read access to the page | yes | What the assistant noted about one page, current and superseded, and whether the page is kept away from it. |
POST | /api/index/items/{id}/wrong | read access to the page | yes | This is wrong: {reason?}. The note is not used again, and the next reading of its page is told. |
GET | /api/index/recall | read access to the page | yes | Notes 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/findings | read access to the page | yes | What 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/check | read access to the page | no | Look 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 page | yes | Dismiss 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/tasks | read access to the page | yes | Tasks 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/search | read access to the page | yes | Full-text search over the workspace (?q=); ?archived=1 includes archived pages. |
GET | /api/timeline | read access to the page | yes | What 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/news | read access to the page | yes | Whether 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.atom | read access to the page | yes | The 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/export | the export_workspace capability | yes | Every readable page as Markdown, paged by ?after= — the whole workspace without a request per page. |
GET | /api/state | the export_workspace capability | yes | The whole-workspace fingerprint an export mirror runs on. |
POST | /api/comments | read access to the page | yes | Comment on a block, optionally quoting part of it. |
POST | /api/comments/{commentId}/resolve | read access to the page | yes | Resolve a thread, or reopen it. |
DELETE | /api/comments/{commentId} | read access to the page | yes | Delete your own comment. |
GET | /api/stars | a signed-in person (not a key) | yes | The pages you starred, most recent first, leaving out any you can no longer open. |
PUT | /api/stars | read access to the page | yes | Star or unstar a page ({pageId, starred}); needs no more than reading it. |
GET | /api/autolinks | read access to the page | yes | This workspace’s short references: each {prefix, url}, where <num> in the address is the number after the prefix. Empty for a caller who can read no page here. |
PUT | /api/autolinks | the manage_workspace capability | yes | Replace the whole list ({autolinks: [{prefix, url}]}); at most 50, each address http or https. |
GET | /api/notifications | a signed-in person (not a key) | yes | What 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/read | a signed-in person (not a key) | yes | Mark notifications read, by id or all of them. |
GET | /api/files | read access to the page | yes | The files in this workspace. |
POST | /api/files | write access to the page | yes | Upload a file against the page it belongs to (?page=, x-filename). |
GET | /api/files/{fileId} | read access to the page | yes | The bytes, behind the permission of the page they hang on. |
GET | /api/templates | read access to the page | yes | The template gallery (ADR 0038): this workspace's templates the caller may read, the built-in catalogue, and its shelves. |
GET | /api/templates/preview | read access to the page | yes | What 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/install | the create_root_pages capability | yes | Take 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/use | the create_root_pages capability | yes | Make 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-template | read access to the page | yes | Which 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-template | read access to the page | yes | Set 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/snippet | write access to the page | yes | A 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/update | read access to the page | yes | Whether 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/update | write access to the page | yes | Offer 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/records | the create_root_pages capability | yes | Set 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/views | read access to the page | yes | The saved views of this workspace. |
POST | /api/views | the manage_views capability | yes | Save a view. |
GET | /api/views/{viewId} | read access to the page | yes | A view, evaluated: its rows and columns now. |
PATCH | /api/views/{viewId} | the manage_views capability | yes | Change a view’s query, columns or layout. |
DELETE | /api/views/{viewId} | the manage_views capability | yes | Delete a view. The pages it showed are untouched. |
POST | /api/views/{viewId}/move | write access to the page | yes | Move a card between board columns, which writes the property on its page. |
POST | /api/proposals/{proposalId}/apply | write access to the page | yes | Accept a proposal, block by block. |
POST | /api/proposals/{proposalId}/close | write access to the page | yes | Close a proposal without applying it. |
POST | /api/import/preview | the create_root_pages capability | yes | What importing this folder would do. Writes nothing. |
POST | /api/import/pages | the create_root_pages capability | yes | Create the pages an import needs. |
POST | /api/import/content | write access to the page | yes | Write the imported content into those pages. |
GET | /api/shared | anybody | yes | Pages shared with you from other workspaces. |
GET | /api/billing | the manage_billing capability | yes | This 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/profile | the manage_billing capability | yes | Who 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 capability | yes | One of this workspace’s invoices, with its lines, payments, credit notes and refunds. |
GET | /api/billing/invoices/{id}/document | the manage_billing capability | yes | The 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}/document | the manage_billing capability | yes | A 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/choices | the manage_workspace capability | yes | The 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/request | the manage_workspace capability | yes | Ask 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/request | the manage_workspace capability | yes | Withdraw this workspace’s open package request. |
GET | /api/plan | the list_members capability | yes | This 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-tokens | the manage_members capability | yes | This workspace’s directory sync tokens, and the SCIM endpoint they unlock. |
POST | /api/scim-tokens | the manage_members capability | yes | Make a directory sync token ({label}), shown once. ADR 0023. |
DELETE | /api/scim-tokens/{token} | the manage_members capability | yes | Revoke a directory sync token. |
GET | /api/sign-in-policy | the manage_sso capability | yes | How members must sign in here: through SSO, with a second factor, without a password. |
PATCH | /api/sign-in-policy | the manage_sso capability | yes | Require 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/account | a signed-in person (not a key) | no | Your account: name, address, and any move to a new address still waiting. |
PATCH | /api/account | a signed-in person (not a key) | no | Change 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/email | a signed-in person (not a key) | no | Ask to move to a new address. A link goes there; nothing changes until it is followed. |
DELETE | /api/account/email | a signed-in person (not a key) | no | Withdraw a move to a new address. The link sent stops working. |
GET | /api/account/sessions | a signed-in person (not a key) | no | Where you are signed in, by handle — never by session id. |
DELETE | /api/account/sessions | a signed-in person (not a key) | no | Sign out everywhere but here. |
DELETE | /api/account/sessions/{handle} | a signed-in person (not a key) | no | End one session, and close the pages it has open. |
GET | /api/account/billing | a signed-in person (not a key) | no | Your 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/plan | a signed-in person (not a key) | no | Your 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/request | a signed-in person (not a key) | no | Ask for an offered package for your own account: {planId, note?}. An operator decides. |
DELETE | /api/account/plan/request | a signed-in person (not a key) | no | Withdraw your open package request. |
GET | /api/account/identities | a signed-in person (not a key) | no | Which workspaces’ SSO may sign you in, having been confirmed once. |
DELETE | /api/account/identities/{connection} | a signed-in person (not a key) | no | Stop a workspace’s SSO signing you in without asking your email again. |
POST | /api/account/deletion | a signed-in person (not a key) | no | Ask to erase your account. A link goes to your address; nothing happens until it is followed and confirmed. |
DELETE | /api/account/deletion | a signed-in person (not a key) | no | Withdraw a request to erase your account. The link sent stops working. |
PUT | /api/account/password | a signed-in person (not a key) | no | Set 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/password | a signed-in person (not a key) | no | Remove your password; sign in by link from then on. Needs current. |
POST | /api/account/two-step | a signed-in person (not a key) | no | Start 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-step | a signed-in person (not a key) | no | Switch two-step sign-in off, with a current code or a recovery code. |
POST | /api/account/two-step/confirm | a signed-in person (not a key) | no | Finish setting up two-step sign-in with the first code from the app. Answers ten recovery codes, shown once. |
POST | /api/account/recovery-codes | a signed-in person (not a key) | no | Replace your recovery codes, with a current code. The old ones stop working. |
DELETE | /api/account/membership | a signed-in person (not a key) | no | Leave this workspace. Your keys here are revoked; your writing stays. The last admin is refused. |
GET | /api/workspace | the manage_workspace capability | no | This workspace’s icon, who may join without an invitation, and what they become. |
PATCH | /api/workspace | the manage_workspace capability | no | Change 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.zip | the export_workspace capability | yes | The 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/assistant | the use_assistant capability | no | The 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/settings | the manage_assistant capability | no | The workspace’s policy and its own models, and whether the deployment has a model of its own. |
PUT | /api/assistant/policy | the manage_assistant capability | no | Change 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/preferences | the use_assistant capability | no | Your 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/endpoints | the use_assistant capability | no | Add 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 capability | no | Change a model, tried again before it is saved. Omit apiKey to keep the saved one. |
DELETE | /api/assistant/endpoints/{endpointId} | the use_assistant capability | no | Remove a model, and every default that named it. |
POST | /api/assistant/endpoints/{endpointId}/try | the use_assistant capability | no | Try a saved model as it is saved. Answers ok, or the reason it did not answer. |
GET | /api/assistant/threads | the use_assistant capability | no | Your conversations with the assistant here, newest first. Nobody else’s, ever. |
GET | /api/assistant/threads/{threadId} | the use_assistant capability | no | One 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 capability | no | Forget one of your conversations. |
POST | /api/assistant/runs | the use_assistant capability | no | Ask 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}/answer | the use_assistant capability | no | Answer 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/webhooks | the manage_webhooks capability | no | Where this workspace sends word of what happens here. |
POST | /api/webhooks | the manage_webhooks capability | no | Point 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}/test | the manage_webhooks capability | no | Queue a test delivery, to see it arrive and verify the signature. |
GET | /api/webhooks/{webhookId}/deliveries | the manage_webhooks capability | no | Recent deliveries, with what the endpoint answered. |
DELETE | /api/webhooks/{webhookId} | the manage_webhooks capability | no | Stop sending to an endpoint. Its history is kept. |
GET | /api/workspaces | anybody | yes | The workspaces this account belongs to. |
POST | /api/workspaces | an operator, or anybody the deployment’s workspace-creation policy admits | yes | Make 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/requests | a signed-in person (not a key) | no | The workspaces you have asked for, and what became of each. |
POST | /api/workspaces/requests/seen | a signed-in person (not a key) | no | Say 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) | no | Withdraw a request of yours that is still waiting. |
People and permissions
| Method | Path | Needs | Keys | What it does |
|---|---|---|---|---|
GET | /api/members | the list_members capability | yes | Who is in this workspace. |
PATCH | /api/members/{accountId} | the manage_members capability | yes | Change what somebody may do here. |
DELETE | /api/members/{accountId} | the manage_members capability | yes | Remove somebody from this workspace. |
GET | /api/invitations | the manage_invitations capability | yes | Invitations outstanding. |
POST | /api/invitations | the manage_invitations capability | yes | Invite an address, naming the role it may join as. |
DELETE | /api/invitations/{invitationId} | the manage_invitations capability | yes | Withdraw an invitation. |
GET | /api/groups | the manage_groups capability | yes | The groups pages can be shared with. |
POST | /api/groups | the manage_groups capability | yes | Make a group. |
PATCH | /api/groups/{groupId} | the manage_groups capability | yes | Rename a group, or change who is in it. |
DELETE | /api/groups/{groupId} | the manage_groups capability | yes | Delete a group. |
GET | /api/roles | the list_members capability | yes | The roles this workspace has, preset and its own. |
POST | /api/roles | the manage_roles capability | yes | Write a role: a named set of capabilities and a default page level. |
PATCH | /api/roles/{roleId} | the manage_roles capability | yes | Change a role. |
DELETE | /api/roles/{roleId} | the manage_roles capability | yes | Delete a role nobody holds. |
GET | /api/usage | the list_members capability | yes | What 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/audit | the read_audit capability | yes | This workspace’s audit log. |
GET | /api/sso | the manage_sso capability | yes | This workspace’s identity provider connections. |
POST | /api/sso | the manage_sso capability | yes | Connect an identity provider. |
PATCH | /api/sso/{connectionId} | the manage_sso capability | yes | Change a connection, or the domains it admits. |
DELETE | /api/sso/{connectionId} | the manage_sso capability | yes | Disconnect a provider. Refused for the last enabled connection while SSO is required. |
GET | /api/sso/requirement | the manage_sso capability | yes | Whether members must sign in through this workspace’s own SSO. |
PUT | /api/sso/requirement | the manage_sso capability | yes | Require (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}/mappings | the manage_sso capability | yes | Which 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}/mappings | the manage_sso capability | yes | Replace 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}/verify | the manage_sso capability | yes | Prove 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
| Method | Path | Needs | Keys | What it does |
|---|---|---|---|---|
GET | /api/sites | the publish_sites capability, or manager on that site | yes | The 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/sites | the publish_sites capability | yes | Start 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 site | yes | One site: its settings, its list of people, and what is live. |
PATCH | /api/sites/{siteId} | the publish_sites capability, or manager on that site | yes | Change a site’s title, address or audience. Making a published site public needs { confirm: <slug> }. |
DELETE | /api/sites/{siteId} | the publish_sites capability | yes | Delete a site: it stops being served, and its address is free. |
GET | /api/sites/{siteId}/sitemap | the publish_sites capability, or manager on that site | yes | The 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}/pages | the publish_sites capability, or manager on that site | yes | Choose 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}/publish | the publish_sites capability, or manager on that site | yes | Publish 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}/unpublish | the publish_sites capability, or manager on that site | yes | Take a site down. Its decisions are kept for the next publish. |
PUT | /api/sites/{siteId}/members | the publish_sites capability, or manager on that site | yes | Name 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 list | no | A 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 list | no | A published page, as HTML. ?preview shows a manager what the next publish would serve. |
GET | /sites/{site}/_handoff | anybody | no | With 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}/search | whoever the site’s audience admits: anybody, anybody signed in, or its list | no | Search a site’s own pages, as HTML. ?q= is the question; nothing off the site is ever searched. |
GET | /sites/{site}/sitemap.xml | whoever the site’s audience admits: anybody, anybody signed in, or its list | no | Every 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 list | no | An attachment of a published page. |
Credentials
| Method | Path | Needs | Keys | What it does |
|---|---|---|---|---|
GET | /api/keys | a signed-in person (not a key) | no | Your API keys; ?all=1 for everybody’s. all=1 needs manage_api_keys. |
POST | /api/keys | a signed-in person (not a key) | no | Make a key. The token is in the answer, and never again. |
POST | /api/keys/{keyId}/rotate | a signed-in person (not a key) | no | New secret, same key and scopes. |
DELETE | /api/keys/{keyId} | a signed-in person (not a key) | no | Revoke a key. Revoked stays revoked. |
GET | /api/services | the list_members capability | no | The service identities of this workspace. |
POST | /api/services | the manage_members capability | no | Make a service identity and its first key. |
DELETE | /api/services/{accountId} | the manage_members capability | no | Disable a service identity and revoke its keys. |
The deployment
| Method | Path | Needs | Keys | What it does |
|---|---|---|---|---|
GET | /api/platform/assistant | an operator of the deployment | no | The 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/assistant | an operator of the deployment | no | Set 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/assistant | an operator of the deployment | no | Forget the console’s model; the environment’s, if any, is used again. |
GET | /api/platform/workspaces | an operator of the deployment | no | Every workspace, with counts. No titles. |
PATCH | /api/platform/workspaces/{slug} | an operator of the deployment | no | Rename, re-address, suspend or set the quotas of a workspace. An old address stays reserved to it and keeps working. |
GET | /api/platform/trials | an operator of the deployment | no | Every trial: its address, its identity and when it was last opened — never its content (ADR 0049). |
GET | /api/platform/trials/settings | an operator of the deployment | no | The trial switch, package, clocks and cap, and whether trials can work on this deployment. |
PUT | /api/platform/trials/settings | an operator of the deployment | no | Set any of: enabled (on, off, or null to follow NOTESFLOW_TRIAL_WORKSPACES), plan, inactiveDays, graceDays, cap. An owner only. |
POST | /api/platform/trials/{slug}/revoke | an operator of the deployment | no | Revoke a trial’s identity: its cookie stops working and the trial is scheduled for deletion. |
POST | /api/platform/workspaces/{slug}/deletion | an operator of the deployment | no | Schedule 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}/deletion | an operator of the deployment | no | Cancel a scheduled deletion. Nothing has been lost until the purge runs. |
GET | /api/platform/accounts | an operator of the deployment | no | Accounts across the deployment, by address or name, with how many workspaces each is in. |
PATCH | /api/platform/accounts/{accountId} | an operator of the deployment | no | Disable an account — sessions, keys, sign-in and live sockets — or enable it again. Memberships are kept. |
GET | /api/platform/operators | an operator of the deployment | no | Who operates the deployment: owners and support. |
PUT | /api/platform/operators | an operator of the deployment | no | Appoint an owner or support, or step one down. An owner only; never the last owner. |
DELETE | /api/platform/accounts/{accountId}/credentials | an operator of the deployment | no | Start 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-in | an operator of the deployment | no | How people get in: sign-up, what a workspace does with newcomers by default, passwords, the breach check, personal workspaces. |
PATCH | /api/platform/sign-in | an operator of the deployment | no | Change how people get in. An owner only. Opening sign-up is refused while sign-in links are only printed. |
GET | /api/platform/oauth | an operator of the deployment | no | The 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 deployment | no | An 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 deployment | no | Forget the console’s setting for a provider; the environment decides again. |
GET | /api/platform/purging | an operator of the deployment | no | What a purge does on this deployment: erase, or keep out of sight (ADR 0048). |
PATCH | /api/platform/purging | an operator of the deployment | no | Set what a purge does: erase, retain, or null to follow NOTESFLOW_PURGE_MODE. An owner only. |
GET | /api/platform/settings | an operator of the deployment | no | Who may create workspaces, how many each person may start, and the quotas those start with. |
PATCH | /api/platform/settings | an operator of the deployment | no | Set the workspace-creation policy or the per-account limit. An owner only. |
GET | /api/platform/creation-overrides | an operator of the deployment | no | Accounts that are an exception to the workspace-creation policy. |
PUT | /api/platform/creation-overrides | an operator of the deployment | no | Make one account an exception to the policy, or return it to it. An owner only. |
GET | /api/platform/workspace-requests | an operator of the deployment | no | Requests for new workspaces: those waiting, then recent decisions. |
POST | /api/platform/workspace-requests/{requestId} | an operator of the deployment | no | Approve or decline a request. Approving makes the requester the new workspace’s admin. |
GET | /api/platform/plans | an operator of the deployment | no | Every 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/plans | an operator of the deployment | no | An 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 deployment | no | An 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 deployment | no | An owner only. Delete a package nothing is on; 409 otherwise — archive it instead. |
GET | /api/platform/plan-requests | an operator of the deployment | no | Customers’ 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 deployment | no | An owner only. Decide a request: {decision: "approve" | "decline", until?, reason?}. Approving assigns the package; whoever asked is told either way. |
GET | /api/platform/billing | an operator of the deployment | no | What 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/settings | an operator of the deployment | no | Who 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/settings | an operator of the deployment | no | An owner only. Change any of them. |
GET | /api/platform/billing/customer | an operator of the deployment | no | One customer’s billing, by ?workspace=<slug> or ?account=<email>: details, tax override, hold, invoices, and account credit (balance and entries). |
PUT | /api/platform/billing/customer | an operator of the deployment | no | An 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/invoices | an operator of the deployment | no | Every invoice, newest first. ?status= all, draft, open, paid, void or overdue; ?period=2026-09. |
POST | /api/platform/invoices/run | an operator of the deployment | no | An 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 deployment | no | One invoice with its lines and payments. /document for the printable page. |
DELETE | /api/platform/invoices/{id} | an operator of the deployment | no | An owner only. Delete a draft; an issued invoice is voided instead. |
POST | /api/platform/invoices/{id}/issue | an operator of the deployment | no | An 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}/void | an operator of the deployment | no | An 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}/payments | an operator of the deployment | no | An owner only. Record money received: {amount (cents), method?, reference?, receivedAt?}. Paid in full releases any hold it caused. |
POST | /api/platform/invoices/{id}/credit-notes | an operator of the deployment | no | An 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}/refunds | an operator of the deployment | no | An 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}/carry | an operator of the deployment | no | An 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/errors | an operator of the deployment | no | Where 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/errors | an operator of the deployment | no | An 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/telegram | an operator of the deployment | no | The 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/telegram | an operator of the deployment | no | An 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/telegram | an operator of the deployment | no | An owner only. Forget the console’s bot; the environment’s, if any, is used again. |
GET | /api/platform/chat/signal | an operator of the deployment | no | The deployment’s Signal bridge (ADR 0047 step 3, experimental): from the console or the environment, its address and number. |
PUT | /api/platform/chat/signal | an operator of the deployment | no | An 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/signal | an operator of the deployment | no | An owner only. Forget the console’s bridge; the environment’s, if any, is used again. |
GET | /api/platform/mail | an operator of the deployment | no | How 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/mail | an operator of the deployment | no | An 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/retry | an operator of the deployment | no | An 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/settings | an operator of the deployment | no | An 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/settings | an operator of the deployment | no | An owner only. Forget the console's mail settings; the environment decides again. |
GET | /api/platform/backups | an operator of the deployment | no | Backups (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/backups | an operator of the deployment | no | An owner only. Take a backup now. 409 when this server takes none, or one is already being taken. |
GET | /api/platform/credits | an operator of the deployment | no | Every customer holding account credit, per currency. |
POST | /api/platform/credits | an operator of the deployment | no | An 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}/document | an operator of the deployment | no | A credit note as a printable HTML page. |
GET | /api/platform/default-plan | an operator of the deployment | no | The package for every workspace and account nobody assigned one. Null: everything, unlimited. |
PUT | /api/platform/default-plan | an operator of the deployment | no | An owner only. Set it ({planId}, or null). |
GET | /api/platform/workspaces/{slug}/plan | an operator of the deployment | no | A 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}/plan | an operator of the deployment | no | An 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}/plan | an operator of the deployment | no | An account’s own package: what the workspaces it owns fall back to, and how many workspaces it may start. |
PUT | /api/platform/accounts/{accountId}/plan | an operator of the deployment | no | An owner only. Any of {planId, until, workspaces}. |
GET | /api/platform/audit | an operator of the deployment | no | The deployment-wide audit log. |
GET | /api/platform/break-glass | an operator of the deployment | no | Break-glass grants, current and past. |
POST | /api/platform/break-glass | an operator of the deployment | no | Let yourself into a workspace, with a reason and an expiry. |
DELETE | /api/platform/break-glass/{grantId} | an operator of the deployment | no | End a break-glass grant. |
Signing in
| Method | Path | Needs | Keys | What it does |
|---|---|---|---|---|
GET | /api/auth/me | anybody | yes | Who this caller is here, and what they may do. |
POST | /api/auth/logout | anybody | no | End this session. |
POST | /api/auth/request-link | anybody | no | Send a sign-in link to an address. |
POST | /api/auth/redeem | anybody | no | Turn a sign-in link into a session. |
POST | /api/auth/app/token | anybody | no | The 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/ticket | anybody | no | A 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/push | anybody | no | This 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/push | anybody | no | Stop sending this phone notices. ADR 0037. The device token only. Signing the phone out does this too. |
POST | /api/auth/confirm-email | anybody | no | Follow 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-deletion | anybody | no | Follow 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/options | anybody | no | What the sign-in page may offer: OAuth providers, whether passwords are on, and whether a new address may sign up. |
POST | /api/auth/signup | anybody | no | Sign 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/password | anybody | no | Sign 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-step | anybody | no | Finish 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/reset | anybody | no | Forgot the password: sends a link to choose a new one. Answers { sent: true } whatever the address. |
POST | /api/auth/reset/confirm | anybody | no | Follow the reset link with a new password. Every session of the account ends; it does not sign in. |
POST | /api/auth/sso/confirm | anybody | no | Confirm 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/sso | anybody | no | Whether an address’s domain has an identity provider connected. |
GET | /api/auth/sso/{connectionId}/start | anybody | no | Begin single sign-on against a workspace’s provider. |
GET | /api/auth/sso/{connectionId}/callback | anybody | no | The provider’s answer. |
GET | /api/auth/{provider}/start | anybody | no | Begin OAuth sign-in. |
GET | /api/auth/{provider}/callback | anybody | no | The provider’s answer. |
The process
| Method | Path | Needs | Keys | What it does |
|---|---|---|---|---|
GET | /api/health | anybody | yes | Liveness: the process is running. |
GET | /api/ready | anybody | yes | Readiness: the database answers and the server is not draining. |
GET | /api/metrics | anybody | yes | Prometheus metrics. Absent unless NOTESFLOW_METRICS_TOKEN is set. Guarded by its own bearer token, not by a session or a key. |