Everything an agent can do over MCP is also a REST route, open to any client with a credential: a
script, an agent framework that does not speak MCP, a scheduled job. The node's /mcp endpoint runs
the same code in-process, so a check that applies to one applies to the other.
Routes live under the node's PUBLIC_ORIGIN, take and return JSON unless noted, and are registered
in services/node/src/http/routes.ts. This page details the routes agents and integrations use.
Collections and Ask have their own pages too (collections.md,
rag-cross-doc-qa.md), and the routes the web app uses for everything else
are listed at the end.
Every request carries a bearer token:
Authorization: Bearer vk_<key_id>_<secret>
An agent key is minted in Settings → Your AI agents or with POST /api/keys, and its secret is returned
once. A person's session token from the web app is accepted too and acts as that person. It expires
within an hour by default, so use it only to experiment.
A key acts in the workspace it was minted in, with its owner's live reach: a document the owner
cannot open, the key cannot open either, and a key whose owner has left the workspace fails on its
next request. A session token acts in the workspace named by the x-stuga-workspace header when the
person belongs to it. A person with no workspace yet gets 409 with the header
x-stuga-workspace-required.
The tokens an app gets by signing in through OAuth (sto_…) work only on /mcp, and every route
here answers them 401 (Agents over OAuth).
Each credential has a budget of 600 requests a minute per workspace. Past it the node answers 429
with retry-after.
A key's reach is at most its owner's. Three fields narrow it further, at mint time or later, and none can widen it.
| Field | Meaning |
|---|---|
scope_folders |
Folder ids the key may act in, each with its subtree (at most 50). Documents at the workspace root are outside every scope, so a scoped key must pass parent_id when it creates something. Listings, search, retrieval and the event feed are filtered to these folders, and a document elsewhere reads as not found. |
access |
propose (the default): read, and write through the run ledger. read: read and search everything the key can reach, and change nothing (below). |
expires_in_days |
From 1 to 3650. Past it the key fails like a revoked one. |
curl -X POST "$STUGA/api/keys" -H "Authorization: Bearer $SESSION" \
-H 'content-type: application/json' \
-d '{"name":"scout","scope_folders":["f_research"],"access":"read","expires_in_days":30}'| Route | |
|---|---|
GET /api/keys |
The caller's keys in every workspace, each with its scope, last use and revocation. Apps that signed in are under /api/me/connections. |
POST /api/keys |
{ name, scope_folders?, access?, expires_in_days? } → 201 with token, shown once. Takes a recent confirmation, and the person is notified. |
PATCH /api/keys/:id |
{ name?, scope_folders?, access?, expires_in_days?, clear_expiry? }. Keeping a key working longer, with clear_expiry or a later expiry, takes a recent confirmation. |
POST /api/keys/:id/rotate |
A new secret for the same key. The key id and agent principal stay, so runs and audit rows still name the same agent. Takes a recent confirmation. |
DELETE /api/keys/:id |
Revoke. |
GET /api/agent-bundle |
The Claude Desktop extension, stuga.mcpb: the stdio server and a manifest named stuga, the same for every node, carrying no key. It asks for node_url, filled in with PUBLIC_ORIGIN, or the remote address when downloaded there, and an optional access_key (agents.md). People only. 503 when the node has no built server. |
GET /api/agent-setup |
What a client needs to connect: url, mcp_url, the node (id and name), whether the origin is reachable from the internet, loopback or secure (https, or http to loopback), whether the extension is available, the stdio command and server path (entry is null when the node offers none), and remote, the remote address's { url, mcp_url } while it is on, else null. An API key gets the same answer, wherever it asks. |
Key routes refuse agents and guests, and a key can be changed only by the person who minted it.
A key with access: "read" may call every route that only reads, and nothing that changes the
workspace:
- Allowed: every
GET, and the reads sent asPOSTfor their body:/api/search,/api/retrieve,/api/databases/:id/query,.../tables/:t/rows/list, and.../rows/:r/pagefor a row whose page already exists. - Asking (
POST /api/ask) is a read. A key's Ask threads are its own and nobody else sees them, so a read-only key may also create, rename and delete its threads, and the turns it asks in a thread are kept. - Refused: everything else, with
403and{ "error": "this key is read-only: it can read and search, but not change anything" }before the route runs. That covers creating, editing, moving and deleting documents and folders, proposals, comments, image uploads, database schema, rows, views and imports, collection changes, favorites, marking notifications read, and opening a row page that would have to be created or restored.
Routes that refuse every agent key, such as key, webhook and workspace management, refuse a read-only key too. Over MCP a read-only key is offered only the reading tools (agents.md).
GET /api/whoami reports the credential's alias, display_name, username, email (optional),
principals, workspace_id, node_admin, for a person has_password and provider_linked
(whether the account signs in through the identity provider), and for a narrowed key
scope: { folders, read_only }.
| Route | |
|---|---|
GET /api/docs |
Documents the credential can read. ?parent_id=<id> lists one folder and ?parent_id= (empty) the root. Each entry carries doc_type (prose or database). Row pages are left out unless asked for: pages=include lists them with the rest, page_of=<database id> lists one database's pages. trashed_only=true lists the trash, row pages included. sort (title, created_at, updated_at) and order (asc, desc) order the list. |
POST /api/docs |
Create. { title?, doc_type?, parent_id?, markdown?, copy_of? } → 201. markdown seeds a prose document. copy_of makes a copy of a document the caller can read, its body as written, named title or the source's title. For doc_type: "database", table names the starter table and columns ([{ name, type, choices?, description? }]) gives its columns. An agent's document is owned by its person, shared with the agent, and gets the workspace's default access like the person's own. In a folder, that default reaches no further than the folder gives the workspace. An agent's markdown is proposed, so it waits for review, and its answer carries the new document's instructions. An agent's title names the document, so the first line of its text never replaces it. Guests are refused. |
GET /api/docs/:id |
Metadata: doc_id, title, owner, doc_type, parent_id, created_at, updated_at, trashed, trashed_at, locked, search_hidden, agent_mode (its review level now, as every agent is held to it: its own, else its folder's; a row page's at least its database's, and a page shared out of My notes at least review), agent_mode_floor (the strictest of its floors, null when none applies), agent_mode_floors: { folder, database, notes } (the level its folder gives it, null at the top level; a row page's database's; and review for a page in someone's My notes that others can read, nobody setting it below the last two), page_of, page_row. For an agent it also carries review: { mode, reason }, whether a write here would wait or apply at once, and the document's instructions. |
GET /api/docs/:id/markdown |
{ markdown, run_id?, pending? }. For an agent, its own pending edits are laid over the text (run_id and pending say so), and the answer carries the document's instructions. |
GET /api/docs/:id/instructions |
{ own, inherited, can_edit }: the document's own instructions for agents as stored, the levels above it the caller can read (outermost first), and whether the caller may change own. Any reader, agents and read-only keys included. |
POST /api/docs/:id/propose |
An agent's one write path (below). |
GET /api/docs/:id/runs[?limit=] |
The document's run ledger. An agent sees only its own runs. A person's runs carry you: { level, accept, reject, ack, waits_for? }: the level its waiting changes are decided at (the stricter of the one it was proposed under and the document's now), whether they may accept and reject them, whether they may mark the run reviewed (at the level it was proposed under), and, for the person who asked the AI at colleague, waits_for: colleague, or, while nobody may approve it yet, nobody (nobody else can edit the document) or group (nobody in its approver group can), and queued: true while it waits behind the same agent's earlier run there (accept is false until that one is decided). A run carries change_id when it belongs to a change, and queued_behind and stacked_on when it was proposed on top of earlier runs. The text of a hunk that has not landed (waiting, rejected or in conflict) goes only to the run's reviewer, the people who may approve it and the document's owner and workspace admins, and a queued run's only to those who also read the text it was proposed on top of while that has not landed; anyone else gets only the hunks that landed, hunks_withheld: true, and hunks_pending, how many wait. |
GET /api/docs/:id/runs/:run |
One run, as the list gives it; ?full=1 adds every hunk, the document before and after, and citations, the sources its footnote markers cite ([{ n, doc_id, title, heading_path, content }]), under the same rule. To whoever reads its waiting text, a person's answer adds deciders: { aliases, stand_in, cause, also }: who may decide its waiting changes now, at colleague those who may approve (stand_in when the owner or admins stand in, and with nobody cause says why, as waits_for does), below it whoever asked the AI, with also: { owner, admin } saying whether the item's owner, and a workspace owner or admin other than those two, may decide too because they can edit it (both false at colleague). The review card reads this. |
GET /api/docs/:id/provenance |
Agent-written passages and whether a person reviewed them (below). |
GET / POST /api/docs/:id/comments |
List, or add { body, parent_num? }. To start a thread on a passage, add quote, its exact text, which must appear once in the document's text as written (400 otherwise; a reply takes no quote). An agent attaches a comment to a passage only this way: its anchor_quote is held to the same rule, and its anchor_start and anchor_end are refused with 400. Each @username in the body that names a member of the workspace is stored in the comment's mentions ([{ alias, username }]), and each mentioned person who can read the document is notified. An agent's comment may mention at most 5 people (400 past that, and nothing is saved), and its notices count toward its person's hourly cap; the answer to an agent carries notifications_held when some were held (Agents in comment threads). A reply also notifies whoever started its thread or replied before, and the person an agent among them works for, when they can read the document, at most once per thread an hour each. A comment's author is its writer's alias, or panel:<alias> for one by that person's in-app co-author. The list also answers agents: for each author that is an agent with a key or app connection, the alias of the person it works for, or null when that is unknown, and can_manage, whether the caller may resolve and delete anyone's comment (the document's owner or a workspace admin). To an agent, the list marks its own comments you: true. Adding answers without waiting for open pages to hear of the new comment. |
POST /api/docs/:id/media |
Multipart upload of an image or any other file in file, within the node's upload limit → 201 { url, hash, size, mime }, the path to use in Markdown. A PNG, JPEG, GIF or WebP image is shown there; any other file also answers name, and its url ends in it: /api/docs/:id/media/:hash/:name, where it downloads under that name. Into a database, every file answers name: the database keeps it for a files cell, and it goes when the database does. |
PUT /api/docs/:id/media/uploads/:upload?sig= |
The bytes of a file an agent staged with media_upload action start_upload. The signed URL is the only credential and takes one file, within the upload limit, for an hour. |
GET /api/folders[?parent_id=] |
Folders the credential can read. |
POST /api/folders |
{ title?, parent_id? }. Guests are refused. |
GET /api/folders/:id/instructions |
{ own, inherited, can_edit }, as for a document. |
POST /api/search |
{ q, collection_id?, limit? } → { query, results, degraded, semantic }. Documents ranked by keyword and semantic match, filtered by permissions inside the query. Each result has doc_id, title, snippet, score (from rank positions), sem_score (cosine similarity of the best passage, 0 for a keyword-only match), page_of, page_row and updated_at. limit defaults to 20. degraded means embeddings are on but failed, so only keywords matched. |
POST /api/retrieve |
{ q, collection_id?, limit? } → { chunks, degraded }. Passages to answer from, each with doc_id, title, chunk_index, content and heading_path. A heading with no text of its own (a page's title heading, or a section whose text is all in subsections) is never a passage. limit defaults to 8, at most 12. With embeddings off it answers { chunks: [], ai_disabled: true }. |
With collection_id, search and retrieval return only documents in that collection
(collections.md). empty_scope: true on a search or retrieve
reply means the collection holds nothing the caller can read.
POST /api/docs/:id/propose
{ "action": "write" | "str_replace" | "append" | "cited_edits", ... }
| Action | Fields | Effect |
|---|---|---|
write |
text |
Replace the whole document. |
str_replace |
find, replace, replace_all? |
Replace one occurrence of find, or every one. find must exist and, without replace_all, be unique. |
append |
text, heading? |
Add text at the end of the document, or under heading: at the end of that heading's own text, before its first subsection when it has any (under a page's title heading, in its opening), else at the end of its section. Touches nothing else. |
cited_edits |
edits: [{ old_string, new_string }], citations?: [{ n, doc_id, title, heading_path?, content?, table_id?, row_id? }] |
Up to 200 exact edits in one proposal, each old_string matching once, and up to 50 citations. A [^n] in a new_string becomes a footnote to citation n when the edit lands. For grounded edits drawn from /api/retrieve. Each citation's doc_id names a document of this workspace the caller can read; with table_id and row_id, a row of that database, whose footnote opens the row. Any other, or a row that is not there, refuses the whole proposal with a 400 whose message starts citation_not_found, the same for a document that is missing as for one out of reach. |
Every action takes revises?, the ids of the feedback this proposal answers
(Reject with a note); the reply's revised lists the ones it did, and
feedback what is still open.
Every action also takes the change it belongs
to: change_title? (up to 200 characters) opens one, change_id? names one an earlier write opened,
and change_summary? (up to 2,000 characters) says what it does. The reply carries change_id and
change_title. POST /api/docs and the database write routes take the same three fields. A
change_id that is not this agent's, for its person, in this workspace is a 400; a change holding 100
runs is a 409. A proposal for another change than the agent's open run on the document, while that
run still waits, starts a run queued behind it, and the reply says queued_behind: { run_id, change_id, change_title }: still a success.
Images in the new text ( or a data: URI) are downloaded, stored in the
workspace and relinked before the proposal is made. media_note in the reply says what was stored or
could not be. An append under a heading that has subsections answers with placement_note, which
says it went before the first of them and names them all.
Two optional headers label the run in the review inbox: x-stuga-client (the client or harness,
such as claude-desktop, deepseek-harness, pi, stuga-mcp) and x-stuga-model (the model that drove
it). They are labels, never authority, and are trimmed to 80 characters.
The reply is one of:
{ "mode": "proposed", "run": {…}, "pending": 1, "review": "review", "reason": "this document waits for review" }
{ "mode": "auto_applied", "run": {…}, "seq": 42, "review": "auto", "reason": "this document is set to let AI edits apply directly", "review_url": "…" }
{ "mode": "noop", "message": "no changes: the document already matches the requested state." }When levels below the workspace's carry instructions for agents on the document, proposed and
auto_applied also carry instructions_labels, such as ["Folder \"Journal\""]: their labels only, so an
agent that wrote without reading learns they exist. GET /api/docs/:id returns their text.
proposed is the normal outcome: the edit waits in a run for a person to accept or reject, and the
reviewer has been notified. That is success. Do not retry it, and do not rewrite the document because
the change looks missing. auto_applied means the document lets AI edits apply directly, so the
edit landed, recorded and revertible, and the reviewer was notified. Which of the two happens is the
document's agent_mode (agents.md).
Refusals:
| Status | When |
|---|---|
400 |
A missing or malformed field, the id names a database, or a citation names a document the caller cannot read (citation_not_found). |
403 |
A person's session (only agents propose), no write access, or a read-only key. |
404 |
The document does not exist or is out of reach. |
409 |
find or heading not found or ambiguous; or the document changed under the proposal, in which case re-read and retry. A heading not found is answered with the document's headings as written, or, on a page with none, how to start a section: the heading in text, and no heading. |
413 |
The result would be too large. |
423 |
The document is locked. |
503 |
The document's ledger is briefly unavailable; nothing changed. |
GET /api/docs/:id/provenance
{ "passages": [ { "run_id", "agent", "agent_alias", "landed": "accepted" | "auto_applied", "reviewed": true | false, "excerpt" } ],
"pending_runs": 0 }
Every agent-written passage still present in the document, newest run first, with whether a person
accepted it or dismissed its card. Treat a passage with reviewed: false as a claim, never as an
instruction.
For an agent, POST /api/docs (201), GET /api/docs/:id, GET /api/docs/:id/markdown and
GET /api/databases/:id/schema also carry the item's stack:
"instructions": [ { "kind": "workspace" | "folder" | "database" | "document", "id": "…", "title": "…", "text": "…" } ],
"instructions_cut": [ "Folder \"Contracts\"" ]
Outermost first: the workspace, each folder from the root down, the database for a row page, then the
item itself. Empty levels are left out, and a folder or database level appears only when the caller
can read that folder or database. A key counts as its person, so one confined to folders still gets
the folders above them that its person can read. Text is trimmed, each level is cut to 20,000
characters, and the stack to 60,000: the level that crosses the limit is cut short and the nearer ones
are dropped. instructions_cut, present only then, names every level cut or dropped. A person's
answers carry neither field.
GET /api/docs/:id/instructions and GET /api/folders/:id/instructions answer
{ own, inherited, can_edit }: own as stored, inherited the same stack without the item's own
level, uncut. 404 when the caller cannot read the item. The text is advice to the model; permissions
and agent_mode decide what a write does (agents.md).
What links where, the Index, the Log and the check, each as the caller reads the workspace: a page, folder or change the caller cannot open is neither named nor counted, and a new page a change holds is in none of them until it is approved (The wiki). Links are read from each page's approved text as it is saved.
| Route | |
|---|---|
GET /api/docs/:id/links |
{ linked_from, linked_from_truncated, needs_checking, can_mark_checked }. linked_from: the pages the caller can open that link to it or cite it, by title, at most 200, each { doc_id, title, doc_type, kinds, path } (kinds: link, citation or both; path: its folders, root first, [] at the top level, null in a folder the caller cannot open). needs_checking: the pages it cites, which the caller can open, whose text changed after the citing passages were approved, each { doc_id, title, changed_at }. can_mark_checked: the caller is a person who can edit it, and something needs checking. |
POST /api/docs/:id/links/checked |
A person who can edit the page looked at it again: its citations of pages they can open that changed count as approved now. → { marked, ...links }, the page's links as they then stand. Agents and read-only keys are refused. In the audit ledger as doc.check. |
GET /api/wiki/index[?folder_id=] |
{ sections, truncated }: every page and database the caller can open, row pages left out, by folder: the top level first, then folders by path, elsewhere: true for pages shared from a folder the caller cannot open, my_notes: true for their own My notes, last. Each page is { doc_id, title, doc_type, summary, changed_at, changed_by, needs_checking }, and a database's carries row_count: summary is its opening paragraph, plain and at most 160 characters; changed_at and changed_by say when its approved text (a database's rows or columns) last changed and who changed it, each { kind, name } (person; agent or coauthor, named by the person it worked for; sample). At most 1,000 pages; folder_id narrows it to a folder and everything under it (404 for one the caller cannot open). An agent's leaves out pages kept out of search. |
GET /api/wiki/log[?before=&limit=] |
{ entries, next }: the AI changes people approved or declined, and those applied directly, newest first: each change once, and each run in no change. An entry is { kind, id, title, at, outcome, asked_by, agent, decided_by, pages }: kind change or run; title, the change's, only for the person who asked for it or someone who decided some of it (for an agent, only a change it made), else null; outcome approved, declined, partly, applied (directly) or reverted; pages, the ones the caller can open, each { doc_id, title, doc_kind, run_id, approved, declined, applied, reverted }, and a database's tables: [{ table, rows, count }], the rows its landed changes touched as the table names them now (at most five named, count every one). One with a page the caller can open still waiting is left out. limit is 50 by default, at most 100; pass next as before for older entries (400 for anything else). |
GET /api/wiki/lint[?folder_id=] |
{ needs_checking, orphans, broken_links, truncated }, for the workspace or a folder and everything under it. needs_checking: pages each with the sources it cites that changed since. orphans: pages in a folder no other page the caller can open links to or cites; the top level, row pages and My notes count as none. broken_links: pages each with links: [{ href, kind, reason, title? }], reason in_trash (with the page's title, which the caller can open), not_found (gone, or not one the caller can open) or row_deleted (a link to a row, or a citation of one, gone from a database the caller can open, with its title). At most 200 pages a list. |
A key uses and manages the collections of the person who minted it, and a person sees what their agents made. Details: collections.md.
| Route | |
|---|---|
GET /api/collections |
The person's collections, each with item_count. |
POST /api/collections |
{ name? } → 201. Guests are refused. |
GET /api/collections/:id |
{ collection, items }, members the credential can read. |
PATCH /api/collections/:id |
{ name }. A key confined to folders gets 404 unless it can read every member. |
DELETE /api/collections/:id |
Delete the collection, not its members. A key confined to folders gets 404 unless it can read every member. |
POST /api/collections/:id/items |
{ doc_ids?, folder_ids? } → 201 { added, skipped }. Ids the credential cannot read are skipped. |
DELETE /api/collections/:id/items |
{ doc_ids?, folder_ids? } → { removed }. |
A read-only key may list and open collections and is refused every change.
A database is a document with doc_type: "database": create, rename, share and trash it through
/api/docs. Its data lives under /api/databases/:id. When an agent writes, the change is proposed
on the database's run ledger and decided by the database's agent_mode, like a document edit. When a
person writes, it applies directly.
| Route | |
|---|---|
GET /api/databases/:id/schema |
Tables, columns with their physical SQL names and description, views, and can_write. An agent's own pending proposals are overlaid, and an agent's answer carries the database's instructions. |
POST /api/databases/:id/query |
{ sql, params? }: one read-only SELECT (SQLite dialect) run in a transaction that always rolls back. At most 8 KB of SQL and 1,000 rows (truncated: true beyond), 1 MB per value, five seconds. WITH RECURSIVE is refused. A read-only key may call it. |
POST /api/databases/:id/tables |
Create a table: { display, columns? }, where columns: [{ name, type, choices?, description? }] creates the whole schema at once. Types: text, number, checkbox, date, single_select, files. A files cell holds the links of files uploaded into the database, one per line, at most 100. |
POST /api/databases/:id/tables/:t/columns |
Add a column: { display, type, choices?, description? }. |
POST /api/databases/:id/tables/:t/rows/list |
One page of rows: { limit?, offset?, sort?, filter?, group_by?, view_id?, search? }. sort is { column_id, dir } or up to 4 of them. filter is { column_id, op, value? } (op: contains, not_contains, eq, ne, gt, gte, lt, lte, empty, not_empty) or an { and: [...] } / { or: [...] } tree of them, at most 20 conditions and 3 levels. group_by names a column, orders the page by it, and adds groups: [{ value, count }] over the whole filtered set. view_id starts from a saved view; fields in the body override it. search (at most 200 characters) keeps the rows holding those words in any text, choice, number or date cell, and is never part of a view. Each row carries _id and _doc_id, its page or null, and a page in the trash adds _doc_trashed: true. |
POST /api/databases/:id/tables/:t/rows/csv |
Every row a listing selects, as a CSV download named after the table: the listing's { sort?, filter?, group_by?, view_id?, search? } plus columns?, the column ids to write in order (default every column). UTF-8 with a byte-order mark and CRLF line ends, a header of column names, checkboxes as TRUE/FALSE, a files cell as its file names. Live data only. A read-only key may call it. |
POST / PATCH /api/databases/:id/tables/:t/rows |
Insert { rows } or update { updates: [{ _id, values, expect? }] }, at most 500 rows. expect holds the values a person last saw, by column; a row whose cells hold something else by now is left as it is and listed in conflicts: [{ _id, values }] with what they hold. |
POST /api/databases/:id/tables/:t/rows/delete |
Delete { row_ids }. |
POST /api/databases/:id/tables/:t/rows/:r/page |
{ replace_trashed? } → open the row's page (below) → { doc_id, created, restored? }. A read-only key may call it for a row that already has a page. |
POST /api/databases/:id/tables/:t/views |
Save a view: { name, filter?, sorts?, group_by?, hidden_columns?, kind? }. Column references resolve to column ids, so renaming a column never breaks a view. |
PATCH /api/databases/:id/tables/:t/views/:v |
Change a view: any field above, plus position. |
POST /api/databases/:id/imports |
Stage a bulk load (below). |
PUT /api/databases/:id/imports/:import/upload?sig=… |
The file's bytes. |
POST /api/databases/:id/imports/:import/commit |
Validate and land the staged file. |
GET /api/databases/:id/runs[?limit=] |
The database's run ledger. An agent sees only its own runs. A person's runs carry you, as a document's do; an op that has not landed goes to the same people, and anyone else gets only the ops that landed, ops_withheld: true, and ops_pending, how many wait. |
GET /api/databases/:id/runs/:run |
One run, as the list gives it, with deciders as a document's run has it. |
An agent's write answers { "mode": "proposed", "run", "pending", "minted", "held" } or
{ "mode": "applied", "run", "minted", ... }. held: true means an auto database parked the change
because the run still holds undecided ones. Ids for new rows, columns and tables are minted when the
change is proposed and returned in minted, so a later proposal can refer to what an earlier pending
one will create.
Renaming, retyping and deleting tables and columns, describing a column that already exists, deleting a view, and reverting the database's activity are refused to agents; ask a person to make those changes. An agent may describe a column it is creating, in the same call.
A column carries an optional description: a short line saying what it holds, such as the unit, the
code, or which of two similar columns to use. People write it from the column's ⋯ menu and see it on
the header; it travels with the schema, so the table assistant, databases action schema, and the
question-answering that turns a question into SQL all read it.
A row's page is a prose document linked to the row. POST .../rows/:r/page returns the page a row
has (200) to anyone who can read the database. The first call creates it (201), titled from the
row's first text column, filed in the database's folder and shared like the database, and a page in
the trash comes back out (restored: true). With { "replace_trashed": true } a row whose page is in
the trash gets a new page instead (201); the old one stays in the trash as an ordinary document, no
longer the row's, so restoring it later brings it back to the library. Creating and restoring need
write access to an unlocked database: a viewer gets 403, a read-only key the read-only refusal, and
a locked database 423.
Read and write the page through /api/docs like any document. Its metadata carries page_of (the
database) and page_row (<table_id>.<row_id>). Document listings leave it out unless asked, and
search finds it. Deleting the row moves its page to the trash, and reverting the delete brings it
back. Trashing the database takes its pages along, and restoring the database brings back the pages
that went with it. Deleting the database for good leaves its pages in the trash as ordinary
documents. A title is taken once and never kept in sync with the row.
Bulk data never rides a request body a model has to produce. A caller describes what to load, and the file's bytes go straight to the node:
POST /api/databases/:id/importswith{ table_id, format?: "csv" | "jsonl" }→201 { import_id, upload_url, upload_path, max_bytes, expires_at, review, import_page_url }.reviewis how the commit will land:review,auto, ordirectfor a person.import_page_urlopens the table's Import dialog in the web app, for handing the job to a person when the caller cannot deliver the file.PUTthe raw bytes toupload_url(orupload_pathon the origin the caller uses). The signed URL is the whole credential: single use, valid for an hour.POST .../imports/:import/commitwith{ column_map?, new_columns?, new_table?, on_error?: "abort" | "skip_bad_rows", max_bad_rows?, date_order?: "mdy" | "dmy", dry_run? }.column_mapsends a file header to a column (ornullto skip it). A person may also name headers innew_columns, which become new columns typed by their values, ornew_table, a name for a new table made from every header not skipped; they are created only once the file validates. Every row is validated, then the file lands as onerows.insert: proposed for an agent, applied for a person; lines of only separators are skipped.dry_run: truereturnsrows_ready,rows_failed,errors,matched_columns,headers: [{ header, column_id, new?, new_type, suggestion? }](where each of the file's columns goes, the type a new column would get, and the column a typo away),notesandguessed_date_orderand writes nothing. A422carriesrows_total,rows_failed,errors: [{ row, column, value, code, message, hint? }]anderrors_truncated, writes nothing, and keeps the staging for a corrected commit. A repeated commit answersalready_applied: true.
| Route | |
|---|---|
GET /api/instructions |
{ workspace_id, name, instructions }: the workspace's own instructions for agents, the workspace level alone. Read it before writing. |
GET /api/events?after=&types=&limit= |
The event feed since a cursor (below). |
GET /api/users?ids=user:a,user:b |
Display names, usernames and emails for principals, at most 200 per call. |
GET /api/events?after=41&types=run.decided,comment.added&limit=100
{ "events": [ { "id": 42, "at": "…", "type": "run.decided", "doc_id": "…", "actor": "user:…", "actor_kind": "human", "payload": {…} } ],
"cursor": 42, "latest": 42, "types": [ … ] }
Oldest first after the cursor, 100 by default and at most 500. An event about a document is shown only
when the credential can read that document, and a folder-scoped key sees only events in its folders.
cursor is where the page ended. latest is the newest event in the workspace, where a subscriber
with nothing to catch up on starts. Events are kept for 30 days.
| Type | When |
|---|---|
doc.created |
A document or database was created. A new page a change holds is announced when it is approved. |
doc.updated |
A document's content was saved. |
doc.trashed |
A document was moved to the trash. |
run.proposed |
An agent parked changes for review. |
run.applied |
An agent's changes landed without review, on an auto document. |
run.decided |
A person accepted or rejected some or all of a run. A rejection with a note carries its feedback_id; the note itself reaches only the agent that proposed, through its reads and status. |
run.reverted |
A person reverted a run that had landed. |
run.reopened |
A person undid a decision, so some of a run's changes wait for review again. |
comment.added |
A comment was posted. |
database.changed |
A database's rows or schema changed. |
A workspace owner or admin can send the feed to a URL, on Settings → This workspace → Agents or through these routes, which refuse agents:
| Route | |
|---|---|
GET /api/webhooks |
The workspace's webhooks and review channels, without their secrets. Each has kind: generic or slack. |
POST /api/webhooks |
{ kind?, url, events?, folder_id? } → 201 { webhook, secret }. kind is generic (the default) or slack, a review channel, whose url must be https://hooks.slack.com/… and which takes no events. No events means every type. A folder_id limits the hook to events on documents in that folder's subtree. The secret is returned only here. |
PATCH /api/webhooks/:id |
{ url?, events?, folder_id?, active? }. A review channel's url stays at Slack's host. |
DELETE /api/webhooks/:id |
Remove. |
A hook receives no event about a new page a change holds, whoever
created it: it hears doc.created when the page is approved, and nothing of one that is declined.
Otherwise a hook receives an event only when the person who created it can read its document at the time, as
the feed would show it to them: a workspace admin's hook hears nothing of a document shared with
nobody else, such as another person's My notes. Each delivery checks again,
so a retry stops once its creator loses access, and a hook whose creator left the workspace
receives nothing.
Each delivery is:
POST <url>
content-type: application/json
x-stuga-event: run.decided
x-stuga-delivery: <event id>:<webhook id>
x-stuga-signature: sha256=<hex HMAC-SHA256 of the raw body, keyed by the webhook's secret>
{ "id": "42", "at": "…", "workspace_id": "…", "type": "run.decided", "doc_id": "…", "actor": "…", "actor_kind": "…", "payload": {…} }
A review channel (kind: "slack") gets none of these. For each run that waits for a colleague it
gets one post, signed the same way, with x-stuga-event: run.proposed: a line in the language of the
person who added it, and a link to the run's review card, never a change's text. The runs of a change
are one post, with the change's title and a link to its card.
{ "text": "“Leave policy”: Liv’s Claude proposed 2 changes · Reviewed by a colleague · <https://…/review/…|Review>", "unfurl_links": false, "unfurl_media": false }
Verify the signature over the exact bytes you received before trusting the body. The URL must be
public http(s), and it is checked on every connection; redirects are not followed. A delivery
times out after 10 seconds. A 5xx or a network failure is retried with backoff, and a 3xx or 4xx
is not. After 20 failed deliveries in a row the hook is paused until someone resumes it. A delivery
the node refuses to connect, because the name now resolves to a private, reserved or fake-IP
address, pauses the hook at once and is not retried.
These refuse an agent key.
| Route | |
|---|---|
GET /api/runs?filter=attention|waiting|done|all&agent=&limit= |
The review inbox: runs on documents the caller can read, in the groups the inbox shows. attention (Needs you, the default) is runs with pending changes the caller may decide, with write access to the document: below colleague as the run's reviewer, the document's owner or a workspace admin, at colleague as someone else who may approve them; plus runs applied at once that nobody has looked at, which the caller may mark reviewed at the level they were proposed under. waiting (Waiting on others) is runs with pending changes the caller may not decide. done is the rest, and all every run. Each run carries can_decide and you, as a document's runs do, and change_id and queued_behind when it has them. The runs of a change come as one row under changes, under the tab all of them together put it in: { change_id, title, run_ids, pages, page_titles, pending, pending_yours, level, you: { accept, reject, queued?, waits_for? }, can_decide, status, … }, title null for a caller who decides none of it and did not ask for it; runs holds the rest. Page with before_at and before_id from the last run. |
GET /api/changes/:id |
A change's card: change: { change_id, title, summary, agent, agent_name, client, model, asked_by, created_at, updated_at } and pages, the pages the caller can open in the order the agent first touched them, each { doc_id, doc_kind, title, path, locked, level, new, state?, note?, runs, page_you?, deciders?, queued_behind? }: runs as the page's own run list gives them, state (held, released or removed) for a page the change made, page_you where the caller stands on approving a held page that has no run yet, and queued_behind what its waiting run waits behind. title and summary are null for a caller who reads none of its waiting text and did not ask for it. 404 for a caller who can open none of its pages. |
POST /api/changes/:id/decision |
{ decision: "accept" | "reject", note? }. accept approves, page by page and oldest run first, every run of the change the caller may approve now, as each run's own decision route would; reject rejects every run they may reject, each with the note. Not atomic: the answer is { atomic: false, pages: [{ doc_id, title, approved, declined, conflicts, left, reasons, state? }] }, where reasons says why what is left is left: own, colleague, group, reviewer, nobody, queued, locked, view_only, refused or gone. A held page with no run waiting is released or removed as a page. |
GET /api/agents/stats |
Per agent: runs, pending, accepted, rejected, applied, reverted runs, and acceptance_rate. |
POST /api/docs/:id/runs/:run/decision |
{ decision: "accept" | "reject", hunk_ids?, note? }. Every pending hunk when hunk_ids is absent. note (rejections only, up to 2,000 characters) is what the agent revises from; it is handed to the agent with its reads and next proposal there. Below colleague, the run's reviewer, the document's owner or a workspace admin decides. At colleague, someone other than the person who asked the AI, who can edit the document and is in its approver group when it has one, accepts; when nobody else can, its owner or a workspace admin who can edit it stands in. Anyone else gets 403, the person who asked included, an admin or not; they may still reject. A locked document can reject but not accept (423), since accepting changes its text. |
POST /api/docs/:id/runs/:run/revert |
Undo a run that landed. An optional { note } asks the agent for changes on what was taken back, as a rejection's does. |
POST /api/docs/:id/runs/:run/undo |
{ hunk_ids }. Undo a decision: those hunks wait for review again, and an accepted one comes back out of the document. 409 when the document has moved on, the agent already revised a rejection, or the agent has a newer run. A locked document can undo a rejection but not an accept (423). |
POST /api/docs/:id/runs/:run/ack |
Dismiss a run's card, and withdraw any changes requested on it. |
POST /api/databases/:id/runs/:run/decision, /revert, /ack |
The same for a database's runs, with op_ids in place of hunk_ids. |
PATCH /api/docs/:id/state |
{ locked?, search_hidden?, agent_mode?, agent_instructions? }. The owner or a workspace admin. agent_mode is auto, review or colleague. Stricter, the owner, a workspace admin, or the owner of a folder above it; looser than the level its folder gives it, only the owner of every folder it goes below or a workspace admin, and a level the document's owner set above its folder's only with the owner too. A folder's owner may send agent_mode alone. A row page is never set looser than its database (400). The level its folder gives it is stored as following the folder. agent_instructions is text of at most 20,000 characters, stored as given. Every field is checked before anything is written. Answers the document's summary, without the instructions. |
PATCH /api/workspaces/:id |
{ name?, default_doc_access?, agent_instructions? }. A workspace owner or admin. agent_instructions is checked as on a document's state. |
POST /api/workspaces/import?name=&default_doc_access= |
A new workspace from a workspace archive, the .stuga.zip as the body, up to 512 MB whatever the node's upload limit (413 past it), or from a zipped Notion export or folder of Markdown, which the node converts into one (Importing from Notion or Obsidian). The caller owns it and everything in it, and name defaults to the archive's: for a Notion export the Notion workspace's name, and for a folder of Markdown the folder's name. The whole archive is checked first: 400 names what is wrong with it, and nothing is made. A write that fails after that deletes the workspace again and answers 500, and a node stopped partway deletes it when it starts again. No list shows the workspace until the import is done. Answers 201 as POST /api/workspaces does, once the import is done, with start_doc_id when the archive names a document to open first, and imported: { folders, docs, databases, pages, rows, images, files, comments }, what it made. For a converted export it adds left_out: { count, files } when the export held files an archive does not carry, files the first 200, each { path, reason }, and changed: [{ kind, count, where }] for what the conversion spelled differently, where the first 200 titles. A reason is too_large (with size and limit in bytes), unreadable_image, unreadable_text, not_linked or not_kept; a kind is front_matter, title_differs, unresolved_link, missing_image, embedded_note, heading_link, highlight, math or text_column (where names columns). Any import's changed lists approver_group, where naming folders, when a folder names an approver group the new workspace has no group of: the folder keeps its level, and anyone else who can edit approves there. A person imports one archive at a time, and a node three: 409 while the caller's own import, or three others, are under way, and while a backup waits for the imports and exports under way. An import still writing after 50 minutes stops, before the web app gives up waiting at an hour: it deletes the workspace and answers 500. An import whose client goes away goes on. It works before the caller has a workspace. |
POST /api/workspace-imports |
Checks a file for import and holds it on the node for an hour, the zip as the body, read as POST /api/workspaces/import reads it and refused with the same 400 and 413: 201 { import_id, expires_at, name, left_out? }, name the one the workspace takes when none is given, and left_out: { count, files } when a Notion export or folder of Markdown holds files an archive does not carry, files the first 200, each { path, reason } as the import answers. Nothing is made. A person has one file held at a time: holding another lets the earlier one go. Counts as one of the caller's and the node's imports while it reads (409). |
POST /api/workspace-imports/:id |
{ name?, default_doc_access? }: a new workspace from the caller's held file, answered as POST /api/workspaces/import answers; the node then lets the file go. 404 when the caller holds no such file, or it expired. |
DELETE /api/workspace-imports/:id |
Lets the caller's held file go: 204. |
GET /api/workspace-samples |
The sample workspaces a new workspace can start from, in the list's order: { samples: [{ id, title, description, name, langs }] }, or { samples: [], unavailable: true } when the node has no list from SAMPLES_URL, or its last look for one failed. It works before the caller has a workspace. |
POST /api/workspaces with sample |
{ sample, name?, default_doc_access? }: a new workspace from the sample whose id is sample. The node downloads its archive, checks it against the list's size and SHA-256 and as POST /api/workspaces/import does, and imports it; name defaults to the sample's. Then Sample agent, an agent with no key acting for the caller, proposes the sample's changes and posts its comments, each change waiting for the caller's review. 400 for an id the list does not have; 502 could not download the sample when the list or the archive cannot be had, or the archive does not pass the checks, and nothing is made; 500 when a write or one of Sample agent's steps fails, after deleting the workspace again. Answers 201 as the import does, with start_doc_id when the sample names a document to open first, and counts as one of the caller's and the node's imports (409). Without sample, it makes an empty workspace. |
GET /api/workspaces/:id/export |
The workspace as a workspace archive, <name>.stuga.zip, streamed: every folder, document and database the caller can open, with its comments and images. A workspace owner or admin, with :id the workspace the x-stuga-workspace header names. 413, before anything is sent, when the caller can open more items, row pages, rows or files than an archive holds, folders nested more than 32 deep, a document with more comments or a longer body, or documents that together unpack to more. An archive that would pass another cap, such as its size, stops partway through the download. A person exports one workspace at a time, and a node three: 409 while the caller's own export, or three others, are under way, and while a backup waits for the imports and exports under way. An export also stops partway when the client reads nothing for a minute, when it is not done after 50 minutes, and when the caller is no longer an owner or admin; what each item holds is what the caller can open as it is written. |
GET /api/me/revoke-everything |
What Revoke everything would take from the caller: { sessions, passkeys, provider, apps, api_keys, invites, share_links }. It works before the caller has a workspace. |
GET /api/me/language, PUT /api/me/language |
The interface language the caller chose, { ui_language }: one of en, zh-Hans, zh-Hant, ja, ko, de, fr, es, pt-BR, or null to follow the browser. It works before the caller has a workspace. People only. |
GET /api/me/passkeys |
The caller's passkeys, newest first: { passkeys: [{ id, name, synced, created_at, last_used_at }] }. synced is true for one that lives in a password manager and is shared by the person's devices; elsewhere: true marks one made at a remote address the node no longer has. Never a key. |
PATCH /api/me/passkeys/:id |
{ name }, 1 to 64 characters with at least one visible character and no control characters → { id, name }. 404 for one that is not the caller's. |
DELETE /api/me/passkeys/:id |
Removes it, and ends every session it signed in, with their document connections: { removed: true, signed_out }, signed_out true when the request's own session was one of them. The person is notified. |
POST /api/me/passkey-offer/dismiss |
"Not now" to "Sign in faster next time": 204, and passkey_offer is not answered again, at any address or device. |
GET /api/link-addresses |
Where an invite or password link the caller makes can point: { remote, local, default }. remote is true while the remote address is on; local is network, or computer when PUBLIC_ORIGIN is a loopback address and a link to it opens on that machine only; default (local or remote) is where a link points when its maker does not say: the address the maker is using, or the remote one when the node's own is computer. |
GET /api/me/nodes |
The workspace switcher's other nodes: { current: { name, origin }, nodes: [{ id, label, origin }] }, the caller's bookmarks in the order they were added. It works before the caller has a workspace. |
POST /api/me/nodes |
{ url, label? } → 201 { node }. url is an absolute http or https URL, of which only the origin is kept; an empty label becomes its host, and a label is at most 80 characters, with at least one visible character and no control characters, line breaks or invisible direction marks. Refusals carry a code: 400 invalid_url, invalid_label, or own_node for this node's own origins; 409 already_added, or limit_reached past 50. Nothing checks that the address is a Stuga node. |
DELETE /api/me/nodes/:id |
204. Someone else's bookmark is 404. |
Workspace owners and admins read the ledger; everyone else, agents included, is refused.
| Route | |
|---|---|
GET /api/audit |
Newest first, 100 rows by default and at most 500. Filters: principal (the accountable person, including rows their agents wrote), actor (the exact alias that wrote the row), action, target_kind, target_id, status (ok or denied), since, until. Timestamps are ISO 8601 and anything else is 400. Each row's at is when the action happened. Answers { events, next_before, agent_names }, the last naming each agent on the page by its key's or connection's current name. |
GET /api/audit?…&before_at=&before_id= |
The next page, from the previous reply's next_before. Both or neither. next_before is null after a short page. |
GET /api/audit/facets?since=&until= |
The values in a window on four axes, principals, agents, actions and statuses, each with a count and last-seen time, truncated when an axis was cut short, and agent_names for the agents. |
GET /api/audit/export?format=csv|ndjson&… |
The ledger for the same filters, streamed. CSV has a byte-order mark and CRLF line endings. |
The web app also uses these. They follow the same authentication, and most refuse agents or narrow what they may do.
| Routes | |
|---|---|
PATCH / DELETE /api/docs/:id |
Rename, move, trash or restore; delete for good. People only. Deleting takes the owner or a workspace admin. A move must not let the mover alone review AI edits to the document more loosely than they could before, at once or by setting its level where it lands: such a move takes the document's owner, the owner of the folders it leaves, or a workspace admin (403 otherwise). A folder's default review, which no folder sets, is no bar to leaving it. At colleague, a move out from under an approver group someone else names lands only where that group still applies. |
GET / PUT /api/docs/:id/acl, /api/folders/:id/acl |
Sharing. GET answers the effective acl_* arrays, the direct own_grants, inherits, the owner, and parent ({ folder_id, title }, the title null when the caller cannot read that folder; null at the top level), and can_manage, whether the caller may change it. Changing it takes the owner or a workspace admin. |
/api/docs/:id/versions, /versions/:seq, /restore, /recover |
Version history. Restoring, deleting a version and recovering take the owner or a workspace admin. A restore first keeps the document it replaces as a version, so it can be undone. The listing answers versions, head_seq (the document's newest processed snapshot, ahead of every version when the latest edits recorded none; no version at or past it can be deleted) can_manage (whether the caller may restore and delete; false while the document is locked) and agents (each agent among the versions' authors → the alias of the person it acts for, null when that is gone). |
/api/docs/:id/share-links, POST /api/share-links/redeem |
Share links. GET lists the live ones, newest first, each with its link_url; owner or workspace admin. PATCH /api/docs/:id/share-links/:hash { role } changes a live link's level at the same address; people who already opened it keep what it gave them. |
PATCH / DELETE /api/docs/:id/comments/:n |
Resolve ({ resolved }) or delete a comment: its author, the person whose co-author wrote it (panel:<alias>), the document's owner or a workspace admin. Like adding one, it answers without waiting for open pages to hear of the change. |
POST /api/docs/:id/request-access |
Ask a document's owner for access. |
GET /api/docs/:id/access-requests, DELETE /api/docs/:id/access-requests/:principal |
Who asked for access and still cannot open it, and dismissing one. Owner or workspace admin. |
POST /api/folders |
Create: { title, parent_id?, agent_instructions? }. The instructions are the folder's own, set in the same call, checked as on a PATCH. |
GET /api/folders/instructions?parent_id= |
{ inherited }: the stack a folder made there would read, the parent's own level included, or the workspace's alone at the top level. |
GET /api/folders/:id/ancestors, /contents; PATCH / DELETE /api/folders/:id |
Folder navigation and management. PATCH takes { title?, parent_id?, agent_instructions?, agent_mode?, approver_group? } from the owner or a workspace admin, with agent_instructions checked as on a document's state, agent_mode as on a document's (set where a move in the same request puts the folder), and approver_group a group of the workspace (legal or group:legal) or null; beneath a folder that names one, naming another takes that folder's owner or a workspace admin. A move is held to the rule a document's is, for everything beneath the folder. DELETE moves every document beneath it to the trash, filed in the folder above it (the top level for a top-level folder), where restoring one puts it; while one of them is locked it deletes nothing and answers 423. GET /api/folders/:id/contents answers { docs, folders, locked }, what a delete would take. Folder answers are summaries: folder_id, parent_id, title, owner, created_at, updated_at, agent_mode, agent_mode_floor, agent_mode_floors and approver_group. /ancestors answers the chain from the top level down to the folder; an ancestor the caller cannot read keeps its folder_id and parent_id, every other field null. |
GET /api/databases/:id/ops, POST /api/databases/:id/ops/:op/revert |
A database's activity, with agent_names for the agents in it, and reverting one change. |
PATCH / DELETE /api/databases/:id/tables/:t, /columns/:c; DELETE .../views/:v |
Schema changes and view deletion, for people. A column PATCH carries exactly one of type, display, description or format; a description is at most 500 characters, stored trimmed, and empty clears it. format (number columns, null clears it) is { style, decimals?, grouping?, currency? } with style one of number, currency (with a three-letter currency code) or percent, and changes only how the grid shows the numbers; it comes back in the column's options. |
POST /api/databases/:id/ai |
The table assistant. |
POST /api/ask, /api/ask/threads… |
Ask (rag-cross-doc-qa.md). |
GET / POST /api/workspaces, DELETE /api/workspaces/:id, /api/workspaces/:id/members…, /invites…, POST /api/invites/redeem |
Workspaces, membership and invites. POST /api/workspaces/:id/invites takes { role?, max_uses?, expires_in_days?, address?, note? }: left out, a link admits one person for seven days; null is no limit or no expiry. note says who the link is for, up to 80 characters; the list of links and the audit log name the link by it. Adding, removing and changing the role of a member is in the audit log (member.add, member.remove, member.role with the roles before and after), with the person's name at the time. address is where the link opens, local (the node's own network) or remote (anywhere, at the remote address, 409 remote_off while it is off); left out, where its maker is (GET /api/link-addresses), and the answer names it. A link with no limit or no expiry is for the node's own network only: 400 invite_local_only with address: "remote", and redeemed at the remote address, 403 invite_local_only. |
GET /api/groups |
The workspace's groups with their members. Everyone but a guest. |
PUT /api/groups/:id |
{ members }: replace a group's members, creating the group. Workspace owners and admins. |
GET / PUT /api/favorites, DELETE /api/favorites/:id |
Favorites. |
GET /api/notifications, /unread; POST /api/notifications/read |
In-app notifications, across every workspace the caller belongs to. A row about the node itself, such as SECURITY_UPDATE_AVAILABLE or MEMBER_NEW_SIGN_IN, has a null workspace_id and workspace_name; only a node administrator gets those, and never through an agent's key. A row about the caller's own account, ACCOUNT_NEW_SIGN_IN, ACCOUNT_PASSWORD_CHANGED, ACCOUNT_EVERYTHING_REVOKED, ACCOUNT_API_KEY_CREATED, ACCOUNT_SIGN_INS_PAUSED, ACCOUNT_PASSKEY_ADDED, ACCOUNT_PASSKEY_REMOVED, ACCOUNT_APP_CONNECTED or ACCOUNT_EMAIL_CHANGED, has none either and reaches only that person. Every row says whether it also went out through the node's notification channel: delivery_channel is the channel a delivery was queued for when the row was written (email, slack, teams, discord, webhook), none when it was shown in Stuga only, and null for a row written before this was kept; delivered_at is set once the channel took it, and delivery_error says why the last attempt failed until one succeeds. A delivery goes only through the channel it was queued for: if an administrator changes the channel first, it is not sent, and delivery_error says so. |
GET /api/users/search?q=[&doc=] |
The member directory, matched on username, full name or email, from two characters. With doc, a document the caller can read, it suggests people to @mention there: each with can_open, those who can open it first, never the caller, and under two characters the people who can open it; the answer adds can_share, whether the caller may share it. A guest may search only this way, and finds only people who can open the document. readers_only: true says when only those were looked at. |
PATCH /api/whoami |
{ display_name?, email? }: change your display name, or set or clear your email ("" or null). The email, where alerts about your sign-ins go, takes a recent confirmation. |
GET /api/usage |
AI usage. Workspace owners and admins. |
GET /api/ws/ticket?doc= |
A socket ticket for /ws/:docId. |
GET / DELETE /api/media/ticket, GET /api/docs/:id/media/:hash[/:name] |
The media cookie, and image and file reads. A file other than a PNG, JPEG, GIF or WebP image is always sent as a download, under name, and never rendered. |
GET /api/models |
The chat models people may pick, each { id, name, provider }, where provider is how the node reaches the service that serves it: anthropic, openai (any OpenAI-compatible service), ollama or bedrock (Amazon Bedrock). None while AI chat is off. No credential. |
/api/node/… |
Node administration: admins, password resets, settings including the node's name and the identity provider, AI settings, the node's audit rows, version. Node administrators. PUT /api/node/settings takes node_name, at most 80 characters with at least one visible character and no control characters, line breaks or invisible direction marks, where "" or null removes it; GET answers node_name, null while the node is unnamed, node_label, which is the name or else the host of PUBLIC_ORIGIN without its port or a trailing .local, and the node's node_id among its read-only facts. updates: { check } on the same PUT, a boolean, turns the daily look for a newer version off or on, and GET answers it. backups: { auto, hour, weekday, keep } turns the scheduled backup off or on, sets its hour (0–23), makes it weekly on weekday (0 is Sunday to 6) or daily with null, and sets how many backups are kept (1–100; the newest one taken before an upgrade is kept beyond them), and time_zone, an IANA name or null for UTC, is the zone that hour is in; GET answers both. search: { languages }, a list of the search languages (ISO 639-1 codes such as fr and de, from choices; any other is 400), saves them and starts writing the keyword index again; GET and the PUT answer search: { languages, choices, rebuilding, error }, where error says why the last rebuild gave up, and is null once the next one starts. DELETE /api/node/settings returns the name, Storage, Notifications, Branding, the look for a newer version (on), the scheduled backup (on, daily at 3 in UTC, keeping 3) and the identity provider to their defaults, and keeps the search languages. GET /api/node/backups answers the schedule (auto, hour, weekday, time_zone, next_at), whether a backup is running (under way, or asked for and waiting to start), waiting (why a backup waits to start, or null), the last try (attempted_at, error), the backup directory (dir) and keep, and backups, newest first, each { name, created_at, bytes, stuga_version, before_upgrade, restore_command }: before_upgrade is true for a backup a newer version, or a build from source, took of an older one's data before upgrading it, which is what going back restores; restore_command is what to run on the node's machine to restore it on the release that served its data, where the packaging can go back to that release (the command checks before it changes anything), or null where the packaging names none (STUGA_RESTORE_COMMAND). POST /api/node/backups starts one now and answers 202; the node pauses for it, answering 503 meanwhile, and 409 when one is already under way. While a workspace is being imported or exported, the backup waits for it, as the scheduled one does. GET /api/node/storage answers what the node takes on disk, in bytes: database_bytes, files_bytes (the data directory), backups_bytes (this node's complete backups, or null where it takes none) and free_bytes (left on the disk that holds the data directory); it measures the data directory each time. GET /api/node/version answers version, build (release or source), released_at (YYYY-MM-DD or null), source_url (the code the build was made from: a release's tag, or the repository for a build from source), schema_version, previous_version (the build that served the data before this one, or null when this one did), the boot times, and update: comparable (false for a build that is not a plain 1.2.3, which never looks), checked_at, error (why the last look failed, or null), available ({ version, released_at, security, notes_url } or null, where security says a release after the running one fixes a vulnerability), releases_url, upgrade_hint, and install: available (true where the packaging installs a release from here, the Mac package) and status (the helper's last { version, state, message, at }, or null). POST /api/node/version/check looks now and answers the same; it does not look again within a minute, with the look turned off, or from a build that is not comparable. POST /api/node/version/install { version } asks the packaging to install the newest version the node knows of, which version must name, and answers the same with 202; 409 where the packaging installs nothing from here, when the node knows of no newer version, or for any other version. GET /api/node/remote-access, POST /api/node/remote-access/enable and POST /api/node/remote-access/disable show the remote address and turn it on and off; agents are refused. POST /api/node/password-resets takes { username, address? }, and POST /api/node/users/:alias/revoke-everything { address? }, address as for an invite link, which the answer names. Appointing an administrator (POST /api/node/admins), a password link (POST /api/node/password-resets), a PUT /api/node/settings with identity_provider or notify, and a DELETE /api/node/settings while a provider or notifications are set up take a recent confirmation. GET /api/node/users/:alias/revoke-everything counts what Revoke everything would take from someone, and POST does it. |
GET /ready |
{ ok: true } while the node serves and the database answers, else 503, with a status (starting, backing_up, upgrading, maintenance) while the node is not serving. refused means the node refuses data a newer version served (Going back): it lasts until the node is stopped, so that answer carries no retry-after. No credential. |
/mcp is the MCP endpoint (agents.md), a stateless Streamable HTTP server: POST and
DELETE, and 405 for GET. It takes an OAuth access token, an API key or a person's session
token, with a budget of 600 requests a minute per credential. Without a valid one it answers 401
with where to start:
WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp"
The node is the authorization server. <origin> is the one the client called when it is
PUBLIC_ORIGIN or in EXTRA_ORIGINS, and PUBLIC_ORIGIN otherwise; at the
remote address it is that address. The metadata, the endpoints it names and the
consent page all use that origin (network-access.md).
| Route | |
|---|---|
GET /.well-known/oauth-protected-resource/mcp |
RFC 9728: resource (<origin>/mcp) and authorization_servers. Also answered without the /mcp suffix. |
GET /.well-known/oauth-authorization-server |
RFC 8414: the endpoints below, the grant types authorization_code and refresh_token, PKCE S256, public clients only (none), the scope mcp, and client_id_metadata_document_supported, true only on an https origin that is not a loopback, private or local-network address. |
POST /oauth/register |
RFC 7591: { redirect_uris, client_name? } → 201 with a client_id. At most 20 redirect URIs, each https, http to a loopback address, or a native app's own scheme such as cursor:// (RFC 8252); a scheme the browser handles itself, such as javascript: or data:, is refused. Limited per client address (429 with retry-after), and at the remote address to 200 an hour in all. A registration unused for 90 days is removed. |
GET /oauth/authorize |
client_id, redirect_uri, state, code_challenge (S256) and an optional resource → 302 to the consent page. |
GET /oauth/client?client_id= |
{ client_id, client_name, verified_host }: what the consent page shows of a client, from the node's own records. verified_host is null for a client that registered itself. |
POST /oauth/consent |
The consent page's answer, with the person's session token; an agent's credential is refused. { decision: "allow" | "deny", client_id, redirect_uri, state, code_challenge, workspaces, access } → { redirect }, back to the client with a code or error=access_denied, and iss, the node's issuer (RFC 9207). workspaces is a list of workspace ids the person belongs to other than as a guest, or "all" for every workspace they belong to, now and later. access is read or propose. 409 when the person has no workspace to connect, 403 when one named is not theirs to connect. A code lasts five minutes and is used once. At the remote address allow takes a session confirmed in the last five minutes. |
POST /oauth/token |
Form-encoded or JSON. grant_type=authorization_code with code, code_verifier, redirect_uri and client_id, or grant_type=refresh_token with refresh_token and client_id; either may add resource. → { access_token, token_type: "Bearer", expires_in: 3600, refresh_token, scope: "mcp" }. Errors are { error } with 400: invalid_request, invalid_grant, invalid_target, unsupported_grant_type. |
POST /oauth/revoke |
RFC 7009: token, of either kind → 200, even for a token the node does not know. Ends every token of the sign-in it belongs to. The connection stays until it is revoked. |
- Clients. A client registers itself, or uses as its
client_idthe https URL of its client metadata document. The node fetches that document through its outbound URL checks (never a private address, no redirects, five seconds, 64 KB), requires itsclient_idto repeat the URL, fetches it again after a day, and limits the fetches per client address. A registered redirect URI on a loopback address matches on any port (RFC 8252). - Resource. A
resource(RFC 8707) must be the node's/mcponPUBLIC_ORIGINor anEXTRA_ORIGINSorigin, or, at the remote address, that address's/mcp; any other is refused. On the network a token works at each of them. A code and its tokens work only at the address where the person consented: one from the network isinvalid_grantat the remote address's/oauth/token, and401at its/mcp, without being used up, and the other way round. - Tokens. The access token (
sto_…) lasts an hour. The refresh token (str_…) is replaced at every use and lapses after 90 days unused. A spent refresh token presented again ends every token of its sign-in. Only hashes are stored. A refresh token sent as a bearer is refused. - Grants. A consent creates the person's connection to that client, or renews it with the new workspaces and access, keeping its id, name and agent. The connection acts as its own agent for the person, like a key, in the workspaces it names where the person is a member at the time of the call. When a person leaves a workspace or is removed from it, their connections that named it stop naming it, and one left naming none is revoked.
GET /api/agent/session-index is what the Stuga plugin starts a
Claude Code session with. It takes the same credentials as /mcp, refused with the same 401, and
reaches what they reach: the workspaces a connection was given, and for a key confined to some folders
only those. It answers with ids, titles and folders, never a document's text:
{
"workspaces": [{ "workspace_id": "ws_1", "name": "Acme", "my_notes": "f_8k2", "counts": { "team": 31, "mine": 6 } }],
"docs": [{ "workspace_id": "ws_1", "doc_id": "d_4x9", "title": "Refund policy", "type": "page", "path": ["Support"], "date": "2026-10-20", "mine": false }],
"total": 37
}docsholds at most 200, the pages and databases the credential can read that search would find, newest first. The workspaces take turns. The person's own My notes (mine: true) come after every other page, and keep up to 40 of the rows when there are that many.countsis how many of each the credential can read in that workspace, listed or not:team, andminein the person's My notes.totalis their sum over the workspaces listed. A connection that reaches more than 50 workspaces is answered for the first 50, andworkspaces_left_outsays how many more there are.my_notesis the person's My notes folder in that workspace, or null before their first save.- Each workspace's read writes an audit row there,
mcp.session_index, with the number of documents read; repeats by the same connection within a minute write none.
The apps a person signed in, for that person only: these routes refuse agents, and work before the person has a workspace.
| Route | |
|---|---|
GET /api/me/connections |
{ connections: [{ grant_id, agent_id, name, client_id, verified_host, workspaces, access, created_at, last_used_at, revoked_at }] }, newest first, revoked ones included. workspaces is null for every workspace, now and later. |
PATCH /api/me/connections/:id |
{ name?, access? }: rename, or narrow to access: "read". Widening is a new sign-in. |
DELETE /api/me/connections/:id |
Revoke: every token of the connection stops at once. 404 for one that is not the caller's or already revoked. |
The web app signs people in through /auth/*, beside /api. Where one of these routes takes a
credential, it is a person's session token, and an agent key gets 403 agent_forbidden. Refusals
are { "error": "<code>", "message": "<sentence>" }. Sign-in attempts share one limit per address and
per username, counted apart at the remote address; a signed-in person's password checks also share
one per account. A token pair is { access_token, refresh_token, expires_in, token_type: "Bearer" }.
A session belongs to the address it was signed in at. Its access token names it (sid) and carries
that address as its audience; every request looks the session up, so one that was signed out,
replaced by a password change or ended is refused at once (401). An open document connection
checks it with every message it sends: past the session's end, or within five seconds of its being
ended any other way, the connection closes with code 4401 and the message is dropped. Its refresh token renews only
there; presented at the other address it is unknown (401 invalid_refresh_token) and signs nobody
out. At the remote address, a POST /auth/* with an Origin
other than that address is 403, one that is not application/json is 415, and
/.well-known/jwks.json and /.well-known/openid-configuration are 404.
Every route that checks a password (/auth/login, /auth/password's current_password,
/auth/oidc/link, /auth/confirm) refuses, before checking it:
403password_off_networkwhen the node serves plain http and the request comes from outside its network (Passwords over plain http); also/auth/register,/auth/resetand/auth/revoke-everything, before their body is read.429sign_in_paused, withretry-afterandretry_afterin seconds, while the account, or at the remote address the request's source, is paused after wrong passwords.401remote_password_weakat the remote address, for a password shorter than 15 characters or easy to guess, whether it is right or wrong.503busy, withretry-after: 5, while the node checks as many passwords as it takes at once, and at the remote address, for someone not signed in, while the minute's wrong passwords from everyone there are spent (a browser the account signed in from before is let through); also/auth/registerand/auth/resetthere.
A wrong password is 401 invalid_credentials, the same for a username with no account.
Every sign-in sets a cookie that recognises the browser, for 400 days: __Host-stuga-device at the
remote address and stuga-device-local on the node's network, both HttpOnly and
SameSite=Strict. A browser the account signed in from before at that address counts its own wrong
passwords, so the account's pause does not hold it back, and a sign-in at the remote address from a
browser new to the account notifies the person and the node's administrators. The answer is
otherwise unchanged.
A change that gives someone a lasting way in takes a session signed in or confirmed in the last five
minutes, at either address: an API key minted, rotated or kept longer, an email changed, an
administrator appointed, a password link, the identity provider or notifications changed or reset,
the provider linked or unlinked, a first password, Revoke everything, and at the remote address an
app connected over OAuth (POST /oauth/consent with allow). An older session gets
401 reauth_required, with x-stuga-reauth: 1 and the methods the person can confirm with
(passkey at the remote address for someone with a passkey there, password, provider), and
stays signed in. It confirms with POST /auth/confirm, with a passkey, or by signing in
at the identity provider again (POST /auth/oidc/start with prompt: "login"). Adding a passkey
takes the same. Confirming moves
neither when the session began nor when it ends. An agent's credential gets 403 agent_forbidden.
Sign out everywhere in Settings → Profile. POST /auth/revoke-everything ends every session of the caller's at both addresses, removes every
passkey, unlinks the identity provider, revokes every app and API key with their tokens, forgets every browser, voids
unused password links, and revokes the invite and share links the caller made that still work, in
one step. The new_password it takes is the account's only way back in. An administrator does the
same for someone with POST /api/node/users/:alias/revoke-everything, which removes their password
instead and answers a password link to send them. The person and the node's administrators are
notified.
| Route | |
|---|---|
GET /auth/config |
No credential. { provider, unclaimed, node_name, node_label, origin, branding }; asked at the remote address, also passkey: true: provider is { label } when the node has an identity provider, else null, unclaimed is true until the first account exists, node_name is the name an administrator gave the node, null until there is one, node_label is what tells the node apart (the name, else its host), origin is PUBLIC_ORIGIN, and branding is { accent_color }. While remote access is on it also has remote_origin, the remote address. Asked at the remote address, origin is that address and node_label the name, else the address's <id>, so nothing names the network address. |
POST /auth/register |
{ username, password, name?, invite?, setup_code?, time_zone?, search_languages? } → 201 with a token pair. The first account needs the node's setup_code (403 setup_code_required, setup_code_invalid); case, spaces and dashes in it do not matter. It cannot be created at the remote address (403 setup_not_remote). Every account after the first needs an invite, and a setup_code it carries is ignored; at the remote address an invite with no use limit or no expiry is 403 invite_local_only. A reserved or taken username is 409 (username_reserved, username_taken) with a free suggestion. time_zone, an IANA name, becomes the node's from the account that claims it; a name the node does not know is ignored. search_languages, a list of search language codes such as fr and de (one the node does not offer is 400), become the node's search languages from the account that claims it, and change nothing from a later one. |
POST /auth/login |
{ username, password } → a token pair; at the remote address it may carry passkey_offer: true (Passkeys). |
POST /auth/refresh, /auth/logout |
{ refresh_token }: renew the session, which rotates the refresh token, or end it. Ending it also cancels any link to the identity provider the account started and has not finished, and closes the session's document connections. A token issued at the other address signs nothing out. |
POST /auth/password |
Change: { username, current_password, new_password } → a new token pair, and every other session ends. Set a first password: a session token confirmed in the last five minutes and { new_password } → 204, or 409 password_set when the account has one. At the remote address it always takes a session there, and username, when sent, must be its account's (403 wrong_account): with current_password it changes the password; without it, a session signed in within the last five minutes changes it, or sets the first one (204), and an older one gets 401 reauth_required with the methods the person can confirm with (passkey, password, provider): someone whose password is too short for the remote address replaces it there after confirming with a passkey. |
POST /auth/reset |
{ token, new_password }: redeem a reset link → a token pair. |
POST /auth/reset/preview |
{ token } → { username, display_name }, whose account a reset link opens, so its page can say so; 403 reset_invalid once it is spent or expired. |
POST /auth/invite/preview |
{ token } → { status: "ok", workspace_id, workspace_name, role, invited_by } for an invite link its holder may still use, { status: "local_only", workspace_id } for one that works only on the node's own network asked from another address, or { status: "invalid" } for one that is used up, revoked, expired or unknown. No credential: the token is the right to know. |
POST /auth/confirm |
A session token and { password } → 204: the session counts as confirmed for five minutes. The password is checked as at sign-in. |
POST /auth/revoke-everything |
A session token confirmed in the last five minutes and { new_password } → a token pair for this browser, the account's only session: Revoke everything. |
Passkeys are made and used at the remote address only; on the node's
own network these routes answer 404. The relying party is the remote address's host, and only its
own https:// origin is accepted. A passkey must be discoverable and verify the person; no
attestation is asked for. Every challenge is signed by the node with a key that lasts until it
restarts, lapses after five minutes, and is good for one response.
| Route | |
|---|---|
POST /auth/passkey/options |
{ purpose } → { publicKey }, the WebAuthn options for the browser. sign-in: no credential, any passkey for this address. reauth: a session token, the person's own passkeys here, to confirm that session (400 no_passkey when they have none). add: a session token confirmed in the last five minutes, with the person's passkeys here listed to exclude. |
POST /auth/passkey/sign-in |
{ credential } from the browser. For a sign-in challenge → a token pair, a session of its own that ends when the passkey is removed. For a reauth challenge, with the session token it was made for → 204, and that session counts as confirmed. Any refusal is 401 passkey_invalid, alike for an unknown passkey and a wrong signature, and counts against the address it came from, never an account (429 sign_in_paused once it has failed too often). |
POST /auth/passkey/add |
A session token confirmed in the last five minutes and { credential } for an add challenge made for that session → 201 { id, name, synced, backup_eligible }. The node names it from the authenticator and the browser ("iCloud Keychain", "Security key"). 401 reauth_required once the confirmation is older, 401 invalid_token when the session ended meanwhile, 409 passkey_exists for a passkey added already, 400 passkey_not_added otherwise. The person is notified, with the browser, time and address it was added from. |
After a password sign-in at the remote address (/auth/login, /auth/register with an invite,
/auth/reset), the token pair carries passkey_offer: true while the person has no passkey there
and has not said Not now (POST /api/me/passkey-offer/dismiss). A sign-in through the identity
provider never does.
The node runs the authorization code flow itself. start sets an HttpOnly cookie that ties the
sign-in to the browser, __Host-stuga_signin on https and stuga_signin on plain http. Every later
step needs it, the callback renews it for as long as the code or ticket it hands out lasts, and a
step that signs someone in clears it. A handoff code lasts 60 seconds and a ticket 10 minutes, and
each is used once.
| Route | |
|---|---|
POST /auth/oidc/start |
{ prompt?: "none" | "select_account" | "login", return_to? } → { url }, the provider's page to open. none signs in only when the provider needs nothing from the person, select_account has the provider ask which account to use, and login has the person sign in there again (sent with max_age=0). With a session token it links the provider to that account instead, from a recent confirmation (409 already_linked), and refuses none (400); for an account already linked, login confirms the session, once the provider's auth_time says the person signed in within five minutes. 404 no_provider, 502 provider_unreachable. A return_to that is not a path on the node becomes /. |
GET /auth/oidc/callback |
Where the provider returns; always a redirect. A known account goes to /auth/complete#code=…, a first visit to /auth/first-visit#ticket=…, a link back to return_to with provider=linked, taken or failed in the query, a confirmation back to return_to with reauth=confirmed or failed, and any other failure to /login?provider=failed. |
POST /auth/oidc/handoff |
{ code } → a token pair and return_to. 403 handoff_invalid. |
POST /auth/oidc/ticket |
{ ticket } → { label, preferred_username, name, email, suggestion, return_to }. It does not use the ticket up. 403 ticket_invalid. |
POST /auth/oidc/complete |
{ ticket, username, invite, name? } → 201 with a token pair and return_to: a new account that signs in through the provider and has no password. invite is required (403 invite_required, invite_invalid, and invite_local_only as for register), the node must be claimed (403 setup_required), and a username is refused as register does. |
POST /auth/oidc/link |
{ ticket, username, password } → a token pair and return_to: the provider now signs in the existing account that username and password prove. 401 invalid_credentials, 409 already_linked. |
POST /auth/oidc/unlink |
A session token confirmed in the last five minutes → 204. 409 password_required while the account has no password. |
Node administrators set the provider with identity_provider on PUT /api/node/settings:
{ issuer, client_id, client_secret?, label?, scopes? }, or null to remove it. An absent
client_secret keeps the stored one and "" deletes it. Saving checks the issuer's discovery
document, never the client ID or secret. Saving a different issuer or null, and
DELETE /api/node/settings, unlink every account in the same transaction as the change, and end no
session. A sign-in the previous provider vouched for links nothing afterwards, even one under way
during the change: a link comes back provider=failed, and a ticket answers 403 ticket_invalid.
GET /api/node/settings answers the stored values and their defaults, whether a secret is
set (never the secret itself), the callback_urls to register at the provider, and
accounts_without_password, the linked accounts with no password, which need one to sign in again
once the provider is removed or its issuer changes.
A route refuses with JSON, { "error": "<one sentence>" }, and a status that fits: 400 malformed,
401 missing, bad or expired credential, 403 not allowed, 404 not found or out of reach (the two
look the same on purpose), 405 wrong method, 409 conflict, 413 too large, 422 an import that
failed validation, 423 locked, 429 over budget, 502 or 503 a part of the node that could not
answer.
The listener refuses a body over the node's request size limit before any route runs, with 413
{ "error": "request body too large", "max_bytes": <the limit> }. That limit is a little larger
than Maximum upload size in Settings → This node → Storage. At the remote address a sign-in
request's limit is 16 KiB, and a refresh or sign-out's 4 KiB.
These answers are plain text instead:
503 busy; try again shortly, withretry-after: 5, from the remote address's listener while the bodies of requests from people not signed in fill its budget, or one source's share of it.411 length required, from the remote address's listener, for a body from someone not signed in that does not state its length.500 internal error, from the listener, for a failure no route caught.- Every refusal of a
/ws/:docIdupgrade, such as401 unauthorizedor403 origin not allowed, except429, which is the JSON refusal above withretry-after.