---
title: "02 HTTP API"
canonical_url: https://mdflow.cz/share/c/h0L7MvX5Cy5sST3qPnApqHOmrQ36JTVy169qJMtDMya9Kc30zm04cg9OuPSSPwvj/bdb63d7f-857f-42ef-b13f-aa4d139e7cf8
md_url: https://mdflow.cz/share/c/h0L7MvX5Cy5sST3qPnApqHOmrQ36JTVy169qJMtDMya9Kc30zm04cg9OuPSSPwvj/bdb63d7f-857f-42ef-b13f-aa4d139e7cf8.md
visibility: public
---

# 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](https://mdflow.cz/openapi.json) — OpenAPI 3.1
- **Docs:** [mdflow.cz/docs/api](https://mdflow.cz/docs/api)

## A first request

```bash
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](/doc/ee296c64-ecda-49e9-a03f-1834eb1746d1).

## 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](/doc/bdefa552-e9b6-4382-a479-91615474cf69).

## 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](https://mdflow.cz/openapi.json) 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.