HTTP API

A versioned JSON API for server-side scripts, command-line tools and agent integrations.

Every API operation requires Pro.

• Base: https://mdflow.cz/api/v1
• Auth: Authorization: Bearer mdf_…
• Spec: openapi.json — OpenAPI 3.1
• Docs: mdflow.cz/docs/api

A first request

curl -H "Authorization: Bearer mdf_your_token" \
     https://mdflow.cz/api/v1/workspaces

What you can do

Workspaces

• GET /api/v1/workspaces — list
• POST /api/v1/workspaces — create
• PATCH /api/v1/workspaces/{id} — rename, update description
• DELETE /api/v1/workspaces/{id} — delete, with everything inside

Folders

• List all folders, each with its workspace and full path
• Create a folder, optionally inside a parent
• Update a folder's description
• Move a folder to a different parent
• Delete a folder

Documents

• List documents in a folder, a workspace, or across the whole account, each with its full path
• Fetch an individual document including its markdown body, its full path (workspace → … → document), and its compounded description
• Create, rename, replace the body, move, delete

Sharing

• Turn public link sharing and commenting on or off
• Manage private email shares: list, add a person, revoke one, revoke all

The compounded description

Fetching a document returns its compounded description — the cascade of descriptions from the workspace, down through each parent folder, to the document.

This exists for AI grounding. A model receiving a document body alone has to guess at its significance; the same body with "Workspace: my consulting business → Folder: client contracts, signed and countersigned" is far better placed to reason about it.

You get this by writing good descriptions once. See 02 Folders and Subfolders.

Scope

The API is account-wide. A token sees every workspace. There is no per-workspace token, and no read-only mode. See 01 Personal Access Tokens.

Response shape

• List responses exclude document bodies, keeping payloads small. Fetch the body when you need it.
• Duplicate titles and folder names are auto-disambiguated server-side. The response contains the final name — always read it back rather than assuming your requested name was used.
• Responses are Cache-Control: no-store.

Rate limits

60 requests per minute, per token and per authenticated user. Exceeding it returns 429 with a Retry-After header, in seconds.

Note the limit applies per user, not just per token — so spreading work across several tokens does not raise your ceiling.

Errors worth recognizing

Status	Meaning
401	The bearer credential is invalid, expired, or revoked
403	The workspace owner is not on Pro. The token is fine; the plan is not
400	A malformed id or filter
404	Not found, or not yours — ownership is enforced server-side
429	Rate limited; see Retry-After

403 is the one that confuses people. It does not mean your token is wrong.

What the API cannot reach

• Version history — private to the owner by design.
• Encrypted document contents — you get ciphertext.
• Cross-workspace folder moves — the API only reparents within a workspace. Use the web app.
• Collections, comments, search, and workspace export — these are web app features.

Limits

• 500 KiB per document body, UTF-8.
• 100 documents on Free / 10,000 on Pro — though Free cannot use the API at all.
• 10,000 images on Pro.

Keeping the contract honest

The OpenAPI 3.1 spec is the machine-readable contract, and its schemas are strict (additionalProperties: false). Generate a client from it rather than hand-rolling one, and you will find out immediately if something drifts.