Filesystem API

Two endpoints serve clients that mirror a whole workspace. The manifest lists every file with its content hash and is cheap to poll. The batch endpoint applies many ordered operations as one changeset. The CLI's local-folder sync and the desktop app both use them.

GET /api/fs/manifest

Returns every non-directory file in the workspace with its content hash, sorted by path. It reads no file content, so it is cheap even on a large workspace.

Requires files:read.

curl -s "https://www.monofile.ai/api/fs/manifest" \
  -H "Authorization: Bearer $MONOFILE_API_KEY"

{
  "etag": "6f1c4b2a9d0e7f3b8c5a1e4d2b7f9c0a3e6d8b1f4c7a2e5d9b0f3c6a8e1d4b7f",
  "generatedAt": "2026-09-17T10:04:11.229Z",
  "count": 3,
  "entries": [
    {
      "path": "/Projects/README.md",
      "fileId": "clx9a1b2c3d4e5f6",
      "contentHash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
      "size": 1284,
      "mimeType": "text/markdown",
      "updatedAt": "2026-09-16T18:22:03.117Z",
      "hasMedia": false
    },
    {
      "path": "/Projects/diagram.draw",
      "fileId": "clx7f6e5d4c3b2a1",
      "contentHash": "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9",
      "size": 8801,
      "mimeType": "application/json",
      "updatedAt": "2026-09-15T09:41:55.004Z",
      "hasMedia": false
    },
    {
      "path": "/Photos/cover.png",
      "fileId": "clx1a2b3c4d5e6f7",
      "contentHash": null,
      "size": 481920,
      "mimeType": "image/png",
      "updatedAt": "2026-09-10T12:00:00.000Z",
      "hasMedia": true
    }
  ]
}

What a row means

Polling cheaply

The response carries ETag: "<etag>" and Cache-Control: private, no-cache. Send the value back on the next poll and an unchanged workspace answers 304 Not Modified with an empty body:

If-None-Match: "6f1c4b2a9d0e7f3b8c5a1e4d2b7f9c0a3e6d8b1f4c7a2e5d9b0f3c6a8e1d4b7f"

curl -s -o /dev/null -w "%{http_code}\n" "https://www.monofile.ai/api/fs/manifest" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H 'If-None-Match: "6f1c4b2a9d0e7f3b8c5a1e4d2b7f9c0a3e6d8b1f4c7a2e5d9b0f3c6a8e1d4b7f"'

304

The ETag covers the whole manifest, so any create, edit, rename or delete changes it. If-None-Match accepts strong and weak forms, comma-separated lists and *. Poll on an interval, and read the body only when the status is 200.

POST /api/fs/batch

Applies up to 500 operations in the order given, through the same write path the editor uses, so versions, wiki-link indexing and media cleanup all still happen.

Requires files:write for any write, rename, mkdir or link operation, and files:delete if any operation is a delete. The scope check runs before any operation is applied. A missing scope returns 403 with INSUFFICIENT_SCOPE and nothing in the batch lands.

Request

{
  "ops": [
    { "op": "mkdir",  "path": "/Notes/2026" },
    { "op": "write",  "path": "/Notes/2026/week-38.md", "content": "# Week 38\n", "ifHash": null },
    { "op": "write",  "path": "/Notes/README.md", "content": "# Notes\n\n- week-38\n",
      "ifHash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" },
    { "op": "rename", "from": "/Notes/old.md", "to": "/Notes/2026/old.md" },
    { "op": "delete", "path": "/Notes/scratch.md" }
  ],
  "onConflict": "overwrite",
  "stopOnError": false,
  "kind": "sync"
}

curl -s -X POST "https://www.monofile.ai/api/fs/batch" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Monofile-Run-Id: local-sync-8814" \
  -d '{
    "ops": [
      { "op": "mkdir",  "path": "/Notes/2026" },
      { "op": "write",  "path": "/Notes/2026/week-38.md", "content": "# Week 38\n", "ifHash": null },
      { "op": "write",  "path": "/Notes/README.md", "content": "# Notes\n\n- week-38\n",
        "ifHash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" },
      { "op": "rename", "from": "/Notes/old.md", "to": "/Notes/2026/old.md" },
      { "op": "delete", "path": "/Notes/scratch.md" }
    ],
    "onConflict": "overwrite",
    "stopOnError": false,
    "kind": "sync"
  }'

The operations

Preconditions and conflicts

ifHash is a precondition on the path's current text hash, the same value the manifest gave you. Pass null to assert the path is absent.

When the hash does not match, somebody changed the file since you last looked. The response reports a conflict, and by default the operation is applied anyway. The content you overwrote goes into the file's version history. Send onConflict: "skip" to leave the path untouched instead; the operation then comes back with status: "skipped" and its conflict recorded.

Compare hashes, not timestamps. A clock can drift and a save can leave the content identical, but the hash changes only when the bytes do.

Response

{
  "results": [
    { "index": 0, "op": "mkdir",  "path": "/Notes/2026", "status": "ok", "fileId": "clx0011223344aabb" },
    { "index": 1, "op": "write",  "path": "/Notes/2026/week-38.md", "status": "ok",
      "hash": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c",
      "fileId": "clx5566778899ccdd" },
    { "index": 2, "op": "write",  "path": "/Notes/README.md", "status": "ok",
      "hash": "7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730",
      "fileId": "clxaabbccddeeff00",
      "conflict": { "expectedHash": "2c26b46b...e7ae", "actualHash": "9f86d081...0865" } },
    { "index": 3, "op": "rename", "path": "/Notes/2026/old.md", "status": "ok", "fileId": "clx1122334455667" },
    { "index": 4, "op": "delete", "path": "/Notes/scratch.md", "status": "ok" }
  ],
  "conflicts": [
    { "index": 2, "path": "/Notes/README.md",
      "expectedHash": "2c26b46b...e7ae", "actualHash": "9f86d081...0865", "applied": true }
  ],
  "applied": 5,
  "failed": 0,
  "skipped": 0,
  "changesetId": "clx8c1f0e4b7a92dd"
}

Four details of the response:

• results[i].status is one of ok, skipped or error, and applied, failed and skipped are the counts of each.

• A rename reports its destination in result.path.

• With stopOnError: true the remaining operations come back as skipped with code ABORTED.

• One changeset per batch. changesetId names it, and it is null when the batch wrote nothing. Reverting that changeset undoes the whole batch in one action. If you sent X-Monofile-Run-Id, the batch joins that run's changeset instead of opening its own.

Limits

Media does not go through write. Upload the bytes with the presigned upload flow, then attach them with a link operation.

Next steps