> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canvasview.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> How agents and scripts authenticate to CanvasView, and where to find the generated reference for every tool, building block and error.

CanvasView serves the same operations two ways: as MCP tools at `https://app.canvasview.dev/mcp`, and as a REST API under `https://app.canvasview.dev/api`.

## Generated reference

The full reference is generated from CanvasView's code and checked against it on every build. It is written for agents, and people can read it too.

| Reference | What it covers |
| - | - |
| [llms.txt](https://app.canvasview.dev/llms.txt) | An overview for agents: how to connect, current prices, every tool in one line, and the examples. |
| [tools.md](https://app.canvasview.dev/agents/tools.md) | Every MCP tool with its description and input fields. |
| [kit.md](https://app.canvasview.dev/agents/kit.md) | The building blocks, their props, the component hooks and layout. |
| [errors.md](https://app.canvasview.dev/agents/errors.md) | Every error code, its HTTP status and its message. |
| `/agents/examples/<name>.json` | Complete `create_canvas` inputs. See [What you can build](https://docs.canvasview.dev/what-you-can-build.md). |

## Skills

CanvasView's skills teach an agent to create canvases, build components and apps, arrange canvases, work with people and recover from errors. The Claude Code and Codex plugins install them. Every MCP client can also read them from the server: as `skill://canvasview/<name>/SKILL.md` resources, or with the `get_skill` tool for clients that do not show resources.

## The canvas card in chat

In chat apps that support MCP Apps, CanvasView shows a live card beside the results of `create_canvas`, `update_canvas`, `patch_canvas`, `get_canvas` and `wait_for_answer`. The card shows the canvas's title and status, a small map of its components, and how many people are viewing it and how many comments and answers it has.

* **Open canvas** opens the canvas.
* **Tell Claude** appears when there are new comments or answers. It posts a message with the counts, so the agent reads them with `list_comments` and `get_answers`. It never quotes what people wrote.

The card shows no canvas content beyond component titles. Clients without MCP Apps, such as the Claude Code CLI, show the usual text result.

## Authenticate

### MCP clients that sign in through the browser

Clients that support MCP OAuth, such as Claude Code and Codex, connect to `https://app.canvasview.dev/mcp` with no key. The first time, they open your browser so you can sign in to CanvasView and approve the connection. Codex needs the `offline_access` scope. See [Connect your agent](https://docs.canvasview.dev/index.md).

You can disconnect a client at any time on the API keys page. See [Keys and connected agents](https://docs.canvasview.dev/account/keys-and-agents.md).

### API keys

Scripts, headless agents and MCP clients that cannot sign in through the browser use an API key. Create one on the [API keys](https://app.canvasview.dev/settings/keys) page and send it as a bearer token:

```bash theme={null}
curl https://app.canvasview.dev/api/balance \
  -H "Authorization: Bearer cvk_your_key_here"
```

The REST API accepts API keys only. The MCP endpoint accepts an API key or a browser sign-in.

## REST routes

Request bodies take the same fields as the matching tool in [tools.md](https://app.canvasview.dev/agents/tools.md). `get_skill` is served over MCP only. The canvas ID, or the component, template or example name, goes in the path instead of the body. `GET` routes take their fields as query parameters. `validate_canvas` keeps `id` in the body when it checks an update or a patch.

| Tool | Method and path |
| - | - |
| `create_canvas` | `POST /api/canvases` |
| `list_canvases` | `GET /api/canvases` |
| `find_canvas_by_key` | `GET /api/canvases?idempotencyKey=` |
| `validate_canvas` | `POST /api/canvases/validate` |
| `get_canvas` | `GET /api/canvases/:id` |
| `list_canvas_viewers` | `GET /api/canvases/:id/viewers` |
| `update_canvas` | `PATCH /api/canvases/:id` |
| `patch_canvas` | `PATCH /api/canvases/:id/nodes` |
| `arrange_canvas` | `POST /api/canvases/:id/arrange` |
| `set_canvas_access` | `PUT /api/canvases/:id/access` |
| `close_canvas` | `POST /api/canvases/:id/close` |
| `extend_canvas` | `POST /api/canvases/:id/extend` |
| `pin_canvas` | `PUT /api/canvases/:id/pin` |
| `delete_canvas` | `DELETE /api/canvases/:id` |
| `get_answers`, `wait_for_answer` | `GET /api/canvases/:id/answers`, with `?wait=` seconds to wait |
| `get_canvas_state`, `set_canvas_state` | `GET` and `PUT /api/canvases/:id/state` |
| `list_comments`, `add_comment` | `GET` and `POST /api/canvases/:id/comments` |
| `list_canvas_changes` | `GET /api/canvases/:id/changes?limit=&before=` |
| `get_canvas_lock`, `acquire_canvas_lock`, `release_canvas_lock` | `GET`, `POST` and `DELETE /api/canvases/:id/lock` |
| `get_repository` | `GET /api/canvases/:id/repository?limit=` |
| `get_repository_token` | `POST /api/canvases/:id/repository/token` |
| `pull_repository` | `POST /api/canvases/:id/repository/pull` |
| `list_tools`, `publish_tools` | `GET` and `PUT /api/canvases/:id/tools` |
| `test_tool` | `POST /api/canvases/:id/tools/test` |
| `call_tool` | `POST /api/canvases/:id/tools/call` |
| `get_tool_log` | `GET /api/canvases/:id/tools/log?tool=&limit=` |
| `list_events`, `wait_for_event` | `GET /api/events`, with `?wait=` seconds to wait |
| `list_examples`, `get_example` | `GET /api/examples`, `GET /api/examples/:name` |
| `list_widgets` | `GET /api/widgets` |
| `get_kit_reference` | `GET /api/kit` |
| `list_data_sources` | `GET /api/data-sources` |
| `request_data_source` | `POST /api/data-sources/requests` |
| `list_notifications` | `GET /api/notifications?unreadOnly=&severity=&limit=` |
| `get_balance` | `GET /api/balance` |
| `send_feedback` | `POST /api/feedback` |
| `search_components` | `GET /api/components?query=&limit=` |
| `get_component`, `save_component`, `delete_component` | `GET`, `PUT` and `DELETE /api/components/:name` |
| `search_templates` | `GET /api/templates?query=&limit=` |
| `get_template`, `save_template`, `delete_template` | `GET`, `PUT` and `DELETE /api/templates/:name` |

## Errors

A failed REST call returns an HTTP status and a JSON body with `error`, a code, and usually `message`, which says what to change. Invalid input returns `invalid_input` with `issues`, each with a `path` and a `message`. Over MCP, the same JSON comes back as a tool result with `isError: true`. See [errors.md](https://app.canvasview.dev/agents/errors.md).

Until CanvasView approves your account, only `list_examples`, `get_example`, `get_kit_reference`, `get_skill`, `list_widgets`, `validate_canvas` and `get_balance` work. Other calls return `account_pending` with status 403.

## Retries

`create_canvas` takes an `idempotencyKey`. Reuse the same key when you retry a create whose outcome you do not know: CanvasView returns the first result and charges once. If a create times out, look it up with `find_canvas_by_key` before retrying.

A request sent too quickly is refused with status 429, `rate_limit` and a `Retry-After: 1` header. Wait a second and retry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.