Use FormWise as a data layer

Your Knowledgebases hold the documents and pages your Agents draw on. The same store is open to everything else you run: an AI client on your desktop, an agent you built with a framework, a nightly job. They search the same documents and pages, with citations, and file what they learned back as pages for your Agents to use on the next run. One place to keep context, read and written by every agent you have.

Connect

Pick the client. Every one of them reaches the same Knowledgebases with the same rules.

https://builder.formwise.ai/api/v1/orgs/<your-org-slug>/mcp

Personal keys and sign-in connections act as you; an organization key acts as the organization. Both are created under Settings → API. See Authentication.

Every loop starts with what changed

A recurring agent should not re-read everything. Ask what changed, act on that, and write back:

# 1. What is new since the last run
curl "https://builder.formwise.ai/api/v1/knowledgebases/all/changes?since=2026-09-24T00:00:00Z" \
  -H "Authorization: Bearer fw_live_..."

# 2. Look up what the new material says
curl -X POST https://builder.formwise.ai/api/v1/knowledgebases/all/search \
  -H "Authorization: Bearer fw_live_..." -H "Content-Type: application/json" \
  -d '{ "query": "changes to the refund window", "kinds": ["documents", "pages"] }'

# 3. File the conclusion for the Agents (and the next run)
curl -X POST https://builder.formwise.ai/api/v1/knowledgebases/<knowledgebase-uuid>/pages \
  -H "Authorization: Bearer fw_live_..." -H "Content-Type: application/json" \
  -d '{ "title": "Refund policy digest", "templateKey": "meeting_notes", "bodyMarkdown": "- Annual plans: 30 days, unchanged.\n- New: partial refunds need a manager." }'

Over MCP the same loop is list_changes → search_knowledgebase → save_page or append_page. The changes feed is keyed by when something arrived or changed, not by dates inside documents, and it hands back a cursor, so a job that polls it never misses a row and never re-reads one. Pass the previous run's nextCursor instead of a timestamp.

What you can do

Every search result carries a citation: a document hit names its source, a page hit carries the page id to read in full, a memory hit its id. Pass kinds: ["pages"] when documents are not needed and the call costs nothing. Memories are personal, so they come back only for a personal key or a signed-in connection; an organization key does not see them.

There is no delete over a connection, so a confused client cannot wipe a page. Everything that reaches the API is governed by the same rules as the builder: a page has a title and a body under 256 KB, a parent must be a page of the same Knowledgebase, and templates seed the sections you would get in the editor.

Editing in place

A client that has read a page edits it with operations anchored to the text it read, never by sending the whole page back:

{
  "patch": [
    { "op": "replace", "oldString": "refund within 30 days", "newString": "refund within 45 days" },
    { "op": "insert_after", "anchor": "## Exceptions", "text": "\n\nOrders over $500 need a manager." },
    { "op": "append", "text": "\n\nUpdated by the support bot." }
  ]
}

The operations are replace (oldString → newString, or replaceAll: true for every occurrence), insert_before and insert_after an anchor, prepend, append, and replace_range (from inclusive to to exclusive). Every anchor must appear exactly once in the page as it currently is, operations apply in order, and if any anchor misses or is ambiguous the whole request is refused and nothing is written, so a client never trims a page it has only partly read. Up to 50 operations per request. The same operations edit an Agent's system prompt (systemInstructionPatch on the draft) and a Flow node's prompt (promptPatch over MCP).

Keeping your documents current

Pages are for notes a client writes; upload_source is for documents it already has. A transcript from a meeting bot, a report a backend job produced, a page from your public site: send it once and every Agent that uses the Knowledgebase sees it on its next run.

curl -X POST https://builder.formwise.ai/api/v1/knowledgebases/$KB/sources \
  -H "Authorization: Bearer fw_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: meeting-2026-09-26" \
  -d '{ "name": "Weekly sync 2026-09-26.md", "contentMarkdown": "# Weekly sync\n\n- Refunds now 45 days" }'

Give exactly one of contentMarkdown, contentText (inline, up to 1 MB) or url (a public http(s) page, checked and fetched on our side), or send multipart/form-data with a file part for a PDF, CSV, TXT or MD file under the 4.5 MB request limit (larger documents go in as a URL, or through the builder). The document takes the same path as an upload from the Sources tab: the original is kept, the source is attached to the Knowledgebase under your plan's sources-per-Knowledgebase cap, and the indexing service is handed the content. The answer is 202 with status: processing and the source; indexing takes a moment, so poll GET .../sources/{sourceId} (or get_source over MCP) until status is ready, at which point search finds it and the changes feed shows it as ready. If your organization reviews agent writes the status is pending_review instead, the document is in no search until a person approves it in Monitor → Reviews, and the answer says so. The Sources tab marks documents added this way "via API" or "via MCP". Idempotency-Key makes a retried upload return the first result instead of a second copy.

Paging and narrowing

The page and source lists page the same way the changes feed does: ?limit=&cursor= over REST, limit and cursor over MCP, and every answer carries nextCursor (null on the last page). fields (comma-separated over REST) keeps only the named fields on each item, and updatedSince skips anything older, so a nightly job can ask for exactly the ids and titles that changed since it last ran. read_page answers with a 2 KB preview by default; pass view: "full" for the whole markdown.

Folders

Pages nest. A folder is a page with templateKey: "folder": no content of its own, a folder icon in the sidebar, and pages under it. Pass a folder's id as parentPageId when creating a page to file it there, or move an existing page (or a whole folder) with move_page / POST .../pages/{pageId}/move; parentPageId: null puts it back at the top level. The page index carries parentPageId and, over MCP, is_folder and a path of folder names, so a client sees the same tree as the sidebar. Moves are structural: nothing is rewritten, nothing waits for review, and a page can never be moved inside its own sub-pages.

Linking pages and files

The mention pills you place in the editor are plain markdown links with two private schemes, and a connected client writes the same thing:

See [Refund policy](fwpage://3f2c…) and the signed [Rate card 2026.pdf](fwsource://9b1e…).

• fwpage://<page-id> mentions another page of the same Knowledgebase. Page ids come from list_pages or the page index in GET /knowledgebases/{id}.
• fwsource://<source-id> mentions an uploaded file. Source ids come from list_sources or the same GET.

Both render as pills in the editor, appear as related pages and attached files on read_page, feed the Related rail and backlinks, and give your Agents a path to follow. Only references inside the same Knowledgebase resolve; a foreign or stale id renders struck through. Every write answers with links: which pages and files resolved and which ids pointed at nothing, so a client can correct itself in one step.

Trust

• Scopes follow the role. A personal key or a sign-in connection can never do more than the member's current role allows, and a role change applies on the next call. Viewers read; members and above write.
• Access ends when membership ends. Removing a member from the organization stops their keys and connections on the next call.
• Every write carries its author. A page written through a personal key shows that member in the page's revision history; an organization key's writes are marked as agent writes. Appends keep everything that was there, and an in-place edit changes only the text it names; every version stays in the page's history.
• Review mode can hold outside writes. If your organization reviews agent writes, a page, an edit or an append from a connected client waits as a pending revision until a person approves it in the dashboard, and the client is told so.
• You can see what connected apps did. Each key and each connected app in Settings → API has a "Recent knowledgebase activity" list: what was searched or read, in which Knowledgebase, and what came back. Search text itself is never stored, only a fingerprint of it.
• Content written by outside clients is read by your Agents later. The tools tell the model to treat text copied from the web or from messages as untrusted before saving it; keep that rule in your own agents too.

For your Portal users

If your Portal offers MCP access, your customers connect the same way, and what they can reach is their own: the Agents, Flows and Apps their plan includes, and, where you allow it, their own notes. They never see your organization's Knowledgebases. The connection carries your Portal's name, not ours. Copy you can reuse with them:

Connect your assistant to your account and it can use everything your plan includes as tools, wherever you work. Your data stays yours: the assistant only ever sees what you can see, and you can disconnect it at any time from Account settings → Connected apps.

Taking it with you

Rent the reasoning, own the context. Everything in a Knowledgebase comes out as a zip, in a shape another tool can read without us:

curl -o handbook.zip https://builder.formwise.ai/api/v1/knowledgebases/$KB/export \
  -H "Authorization: Bearer fw_live_..."

Inside: manifest.json (what it is and when it was taken), pages/ with every live page as markdown carrying YAML front matter (id, title, template, path, created, updated, author), folders as directories so the tree opens as an Obsidian vault, sources.json with each document's name, type, status, size and dates, and, for a personal key, memories.json with your own memories in that Knowledgebase. File bodies are not inside: they stay in FormWise storage and the indexing service. Export needs the knowledge:read scope, is limited to a few per minute per key, and refuses a Knowledgebase over 50 MB with export_too_large, in which case read its pages one by one. The same zip is one click in the builder (the menu on a Knowledgebase card, Export as zip), and your Portal users get their own notebook the same way from Account settings → Download my data, with nothing of yours inside. There is no import from the zip yet.