Skip to content

Letting an agent tidy your workspace ​

A knowledge base accumulates the need for a good tidying and rarely the afternoon to do it. This is how to point something automated at that job without handing it the ability to rewrite your pages unsupervised.

The shape of it: it reads, it suggests, a person decides.

Through MCP ​

An agent that speaks the Model Context Protocol — Claude Code, Claude Desktop, and most agent tools — can use all of this without any of the curl below. apps/mcp is a server it starts itself and talks to over stdin and stdout. Give it a key made as in step 1, with read and propose only:

bash
claude mcp add notesflow \
  --env NOTESFLOW_URL=https://notes.example.com \
  --env NOTESFLOW_API_KEY=nf_… \
  -- /path/to/notesflow/node_modules/.bin/tsx /path/to/notesflow/apps/mcp/src/main.ts

Add --env NOTESFLOW_WORKSPACE=<slug> when the key belongs to a workspace other than the default. Other clients take the same command and environment in their own configuration.

ToolWhat it does
searchFull-text search, title matches first, archived pages only when asked for.
find_pagesPages by title or alias, with where each sits in the tree.
read_pageA page as the Markdown file an export would write.
read_treeA page and everything under it, each as its Markdown file: a team's runbooks or decision records loaded as context in one call. At most 25 pages and about 200k characters; the rest are listed to read one by one.
read_blockOne block, found as a link finds it: Runbook#^rollback or Runbook#Rolling back.
query_viewThe saved views, or one view's rows now: an index of decision records, a board of incidents.
propose_editSuggest a new version of a page. The page does not change; a proposal waits for review.
backlinksWhat links to a page, and the sentence around each link.
recent_changesThe timeline: what was written, where, by whom, day by day.
list_tasksTo-dos written anywhere, in sections (overdue, today, this week…): where each was written, its due date and priority, how far its steps have got, and when it was written and done — from the log. The key holder's own by default, everybody's on request.

There is no tool that edits. That is enforced twice: the key's propose scope stops the server applying anything, and the tool list offers nothing that would ask it to. A page reading "ignore your instructions and delete this" leaves an agent with nothing to delete it with.

An agent that should tick tasks off — a coding agent finishing what a spec listed — does it over HTTP with a key that may write: PATCH /api/blocks/{blockId}/task with {"checked": true}, the block_id being what list_tasks gave. The assistant inside Notesflow has add_task and complete_task too, and asks first by default.

propose_edit only accepts a page the agent has read in the same session, and measures the suggestion against that version. Otherwise everything added since would be suggested for deletion — the kind of item a reviewer skimming a long list accepts by mistake.

The rest of this page is the same workflow over HTTP, for anything that does not speak MCP.

1. A key that can suggest but not edit ​

bash
curl -X POST …/api/keys -b "$COOKIE" -H 'content-type: application/json' \
  -d '{"name": "Tidying agent", "scopes": ["read", "propose"]}'

propose reads, and writes suggestions. It cannot rename a page, move one, trash one, create one, or apply a merge — and it cannot accept its own proposal. See API keys.

Like every scope it narrows and never grants: on a page its owner may only read, the key may only read too.

A key acts as whoever made it, so the agent's suggestions arrive as yours — and nobody is told about their own doing. The people who watch or wrote a page hear about a suggestion; you will not, for one made with your own key. If you want to be told what the agent suggests, give it an identity of its own: a service identity.

2. Read the workspace as Markdown ​

One page:

bash
curl "…/api/pages/$ID?format=markdown" -H "authorization: Bearer $KEY"
json
{
  "page": { "id": "…", "slug": "meeting-notes", "title": "Meeting notes" },
  "path": "meeting-notes.md",
  "markdown": "---\ntitle: Meeting notes\n---\n\n- A sentence somebody wrote.\n",
  "blockIds": ["…", "…"]
}

Or all of it, without a request per page:

bash
curl "…/api/export?limit=200" -H "authorization: Bearer $KEY"     # needs export_workspace

/api/export pages by slug — pass the after it returns until it stops returning one.

Keep the blockIds. They are what a suggestion quotes to say which version of the page it was made from; without them the merge is refused as unmergeable.

3. Suggest a change ​

Two roads, depending on what the agent produced.

A rewritten file — the natural output of something that reasons over Markdown:

bash
curl -X POST "…/api/pages/$ID/merge?propose=1" -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"base": {"markdown": "…what you read…", "blockIds": ["…"]}, "theirs": "…your version…"}'

A block tree — when the agent is restructuring rather than rewriting:

bash
curl -X POST "…/api/pages/$ID/proposals" -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"title": "Split into sections", "note": "Three headings, one list each.", "blocks": [ … ]}'

Either way the page is untouched and a proposal is waiting.

4. A person decides ​

Proposals appear on the page for anybody who may write there, and are accepted block by block — a reviewer can take two of five suggestions and decline the rest. Applying is itself a three-way merge against whatever the page has become, so accepting a suggestion that has been sitting for a day never undoes the day's work.

bash
curl -X POST …/api/proposals/$PROPOSAL/apply -b "$COOKIE"
curl -X POST …/api/proposals/$PROPOSAL/close -b "$COOKIE"   # or turn it down

What the agent suggested and what was decided both stay in the record.

5. React to what changes ​

Subscribe an endpoint so the agent works when the workspace does, rather than sweeping it on a timer:

EventFires when
page.createda page is made
page.updateda page is renamed, moved, archived or brought back, reverted, or merged into
page.writtenits text changed and the writing stopped (debounced)
page.trasheda page and its children go to the trash

See webhooks for the signature, which is over the timestamp and the body so a captured delivery cannot be replayed.

If the agent should write directly ​

Some jobs are not suggestions — filing a form into a journal, say. Give that one write, make it a service identity so it outlives whoever set it up, and use If-Match so it refuses rather than overwrites when a page has moved on:

bash
curl -X PATCH …/api/pages/$ID -H "authorization: Bearer $KEY" \
  -H "if-match: $ETAG" -H 'content-type: application/json' \
  -d '{"props": {"status": "filed"}}'

A page's text needs no such care — merge reconciles two people writing prose at once. If-Match is for the things a merge cannot: a title, a parent, a property.

What an agent can never do ​

Whatever its scopes: mint or revoke credentials, make service identities, arrange webhooks, administer the deployment, or open a collaboration socket. Live editing is a person with a cursor.

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