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

# canvas_read

> Read one canvas as text, or follow its lines from a card.

> [!NOTE]
>
> Free · Your own key only

Gives back every card and every line on a canvas. To follow the lines from one card (a tree, a chain), pass `from_ids`: it then returns only the cards on that path, nearest first, with their full text.

> [!NOTE]
>
> The cloud tools only read canvases. They never draw on one.

Call it at `POST /platform/v1/me/tools/canvas_read`. On MCP, your AI tool calls `canvas_read` with the same arguments.

## Arguments

Send these inside `arguments`.

**canvas\_id** `string` *required*

The canvas id, from `canvas_list`.

**from\_ids** `string | string[]` (default: null)

Start from these cards. A note card's id is its note id, so a note you found can be a start.

**hops** `integer` (default: 2)

How many steps to follow, 0-6.

**direction** `string` (default: "both")

`down` follows the arrows, `up` goes against them, `both` goes both ways.

## Returns

The tool's answer comes back under `result`.

**name** `string`

The canvas name.

**items** `object[]`

Each card: `id`, `noteId`, `type`, `title`, `text` (up to 1,500 characters) and `color`.

**links** `object[]`

Each line: `from`, `to`, and when set `directionality`, `kind` and `label`.

**trace** `object`

Only with `from_ids`: the cards on the path, nearest first, with `hop` and full text.

```bash Your key theme={"system"}
curl https://api.constella.app/platform/v1/me/tools/canvas_read \
  -H "Authorization: Bearer $CONSTELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"canvas_id": "c_81a..."}}'
```

```python Python theme={"system"}
import os, requests

r = requests.post(
    "https://api.constella.app/platform/v1/me/tools/canvas_read",
    headers={"Authorization": f"Bearer {os.environ['CONSTELLA_API_KEY']}", "X-Constella-Client": "my-script"},
    json={"arguments": {"canvas_id": "c_81a..."}},
)
print(r.json()["result"])
```

```javascript JavaScript theme={"system"}
const res = await fetch("https://api.constella.app/platform/v1/me/tools/canvas_read", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CONSTELLA_API_KEY}`,
    "X-Constella-Client": "my-script",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"arguments": {"canvas_id": "c_81a..."}}),
});
const { result } = await res.json();
```

```json 200 theme={"system"}
{
  "result": {
    "name": "Launch plan",
    "items": [
      {
        "id": "n_1",
        "type": "note",
        "title": "Ship on Friday",
        "text": "...",
        "color": "green"
      }
    ],
    "links": []
  }
}
```


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