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

```http
POST /api/tools/<toolName>
{ ...input }
```

```bash title="Terminal"
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:

```http
POST /api/tools/write
{"path": "/notes/today.md", "content": "# Today\n\n- ship the docs\n"}
```

```bash title="Terminal"
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`:

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

So a shell client parses twice:

```bash title="Terminal"
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:

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

| Situation | HTTP | Code |
|---|---|---|
| Missing or malformed `Authorization` header | `401` | `UNAUTHORIZED` |
| Invalid or expired key | `401` | `UNAUTHORIZED` |
| No such tool | `404` | `TOOL_NOT_FOUND` |
| A tool that was renamed | `404` | `TOOL_RENAMED`, with the new name in the message |
| Key lacks a required scope | `200` | `INSUFFICIENT_SCOPE` |
| Bad input, missing file, edit did not match, shell refused | `200` | tool-specific code |

> [!WARNING]
> Never treat `200` as success. Parse `content[0].text` and branch on the presence of `error`. Every code, its cause and its fix are in [[Errors and Limits]].

## 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.

```http
GET /api/tools
```

```bash title="Terminal"
# 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'
```

```bash title="Terminal"
# 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.

| Area | Tools | Reference |
|---|---|---|
| Files and shell | `bash`, `read`, `write`, `edit` | [[File and Shell Tools]] |
| Versions and checkpoints | `list_versions`, `read_version`, `revert_file`, `checkpoint`, `list_changesets`, `revert_changeset` | [[Content Tools]] |
| Diagrams and canvas boards | `create_diagram`, `create_canvas`, `canvas_edit`, `canvas_check` | [[Content Tools]] |
| Folder shares | `get_folder_share_status`, `share_folder`, `unshare_folder` | [[Sharing and Community]] |
| Private share links | `create_share_link`, `get_share_link`, `revoke_share_link` | [[Sharing and Community]] |
| Community | `list_community_folders`, `fork_folder`, `public_bash` | [[Sharing and Community]] |
| Votes and comments | `vote_folder`, `vote_comment`, `list_comments`, `add_comment`, `edit_comment`, `delete_comment` | [[Sharing and Community]] |
| Follows and the feed | `follow_user`, `unfollow_user`, `get_followers`, `get_following`, `get_feed` | [[Sharing and Community]] |
| Profiles and users | `get_my_profile`, `update_profile`, `get_user`, `list_users` | [[Account and Search]] |
| Search and key info | `semantic_search`, `get_key_info` | [[Account and Search]] |

## 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:

```text
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

:::cards
- [[File and Shell Tools]] — Reading, writing and editing files, plus the two shell tiers.
- [[Errors and Limits]] — Every error code, what causes it, and how to recover.
- [[Scopes]] — Every scope, what it unlocks, and the presets.
- [[Filesystem API]] — The manifest and batch endpoints for bulk sync clients.
:::