Calling Tools

Every capability Monofile exposes to agents is a tool, and you call every tool the same way: one POST to /api/tools/<toolName> with a JSON body.

The pattern

{ ...input }

curl -s -X POST "https://www.monofile.ai/api/tools/<toolName>" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ...input }'

There is no GET form, no query-string form, and no batching of different tools in one call. The tool name in the path is the whole routing decision. An empty body is {}; do not omit the body.

A real call:

{"path": "/notes/today.md", "content": "# Today\n\n- ship the docs\n"}

curl -s -X POST "https://www.monofile.ai/api/tools/write" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/notes/today.md", "content": "# Today\n\n- ship the docs\n"}'

The envelope

Results come back in the MCP content envelope, whichever transport you use. The tool's own result is a JSON string in content[0].text:

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\":true,\"file\":{\"id\":\"clx123\",\"path\":\"/notes/today.md\"},\"created\":true}"
    }
  ]
}

So a shell client parses twice:

curl -s -X POST "https://www.monofile.ai/api/tools/read" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/notes/today.md"}' | jq -r '.content[0].text' | jq -r '.content'

An MCP client receives the same envelope from the hosted endpoint at /api/mcp and from the local stdio server, because Monofile generates both from this registry. A tool behaves the same on all three. See Monofile over MCP.

The error contract

A tool-level failure is a successful HTTP request carrying an error payload:

{
  "content": [
    { "type": "text", "text": "{\"error\":{\"code\":\"NO_MATCH\",\"message\":\"old_string was not found in the file\"}}" }
  ]
}

Getting the live tool list

Tool counts change as tools are added. Read the live list; do not trust a number in any document, including this one.

# Every tool your key can use, with its required scopes and its description
curl -s "https://www.monofile.ai/api/tools" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" | jq -r '.content[0].text' | jq '.tools[].name'

# No key needed: names, descriptions and a JSON Schema for every input
curl -s "https://www.monofile.ai/skill.json" | jq '.tools[] | {name, requiredScopes}'
curl -s "https://www.monofile.ai/skill.json" | jq '.tools_manifest'

skill.json is the published manifest. It carries a full JSON Schema per tool, enough to generate a typed client, and tools_manifest.count is the authoritative number of tools at that moment. GET /api/tools describes the same registry for your key, so a description may reflect what your plan and scopes can do.

Every tool, by area

Each group links to the page that documents its inputs and outputs in full.

Writes and changesets

Every tool call that writes something records one changeset, the reviewable and revertable unit of work. A read-only call records nothing. A human can therefore undo any single write, edit or create_canvas call after the fact, with no extra work on your side. See Changesets.

Two paths group more work into a single changeset. A full shell bash command is one changeset however many files it touched, and it accepts a run id header so several shell calls fold into one:

X-Monofile-Run-Id: my-refactor-2026-09-17

The value is 8 to 64 characters of letters, digits, - and _. The same header groups a bulk write on POST /api/fs/batch, described in Filesystem API.

To describe a goal instead of choosing tools, hand it to the built-in assistant, which is also reachable with a key; see Driving the Assistant.

Next steps