For programs
Read boards without touching them.
A dashboard, flows in n8n or a script of your own read nexcanvas through a small interface: which boards there are, what has changed lately and a picture of each board. A program can't change anything through it.
The operator switches it on first
Out of the box the interface is off. The operator switches it on under Settings, Server, API with “Accounts may make API tokens”. There they also see every token with its name and account, never the token itself, and can block individual ones for good.
If they switch the interface off again, all tokens answer with 401. The tokens are kept and work again as soon as it is back on.
Every account makes its own tokens
Under My account, Connections you create one with “New token”. You give it a name so that you know later what it was for, and you choose what it may read and how long it is valid.
- What it reads: all spaces you may read, including later ones, or only certain ones. Never more than your account may read.
- How long: 30 days, 90 days, one year or no expiry. A week before the end the list marks the token.
- Seen once: the token starts with
nxa_and appears only right after you create it. nexcanvas keeps only a checksum. - Up to 20 tokens per account.
The routes
Every request carries the token in a header. The answers are JSON, and the picture of a board is SVG.
curl -H "Authorization: Bearer nxa_..." https://canvas.example.com/api/v1/boards| Route | What comes back |
|---|---|
GET /api/v1/me | Who the token speaks for, which spaces it may read and the version of nexcanvas |
GET /api/v1/spaces | The readable spaces with name, colour, number of boards and your right there |
GET /api/v1/boards | The boards, most recently changed first; parameters space, order (updated or title) and limit (1 to 200, 50 by default) |
GET /api/v1/boards/{id} | One board, as in the list |
GET /api/v1/boards/{id}/picture.svg | The board as a small picture in a 16 to 10 format; look (dark or light) and width (120 to 1,600 pixels, 480 by default) |
GET /api/v1/dashboard | Numbers for a dashboard card and the five most recently changed boards |
Each board comes with its title, space, when it was created and last changed, by whom, how many things are on it, the address for opening it in the browser and the path of its picture. The full description is in docs/api.md.
A card for the dashboard
A card that shows the most recently changed boards asks /api/v1/dashboard every now and then, once a minute is enough. It gets the number of spaces and boards, how many were changed today and this week, and the five latest boards.
It fetches the picture of each board from its path with the same header, and a click opens the board's address. The picture shows shapes, notes, frames and drawings as they are, and words, photos and files only as plain boxes.
Limits and promises
| Answer | Code | Means |
|---|---|---|
| 401 | api_off | The operator has not switched the interface on. |
| 401 | token_invalid | The token doesn't exist, or it has expired, been blocked or been deleted. |
| 403 | origin_refused | The request came from a web page. |
| 404 | not_found | The board or space doesn't exist, or the token may not read it. Both sound the same. |
| 429 | slow_down | More than 600 requests in a minute with this token. Retry-After says when you can carry on. |
Cora saysWhat is under /api/v1 stays as it is. New fields may be added, but nothing is renamed or removed. A change that would break a program comes alongside it under /api/v2.