Notes

Notes are text widgets on a Canvus canvas. They function as digital sticky notes: colored rectangles that hold a title and body text. Use notes for brainstorming, labeling, annotations, or any situation where you need to place readable text directly on the canvas.

Authentication

All endpoints require authentication via the Private-Token header or a CanvusSession cookie, unless the canvas has link sharing enabled (View or Edit permission). Write operations (POST, PATCH, DELETE) require edit access. View-only users receive 403 Forbidden on any write attempt.

Every note shares these properties with all other canvas widget types.

id -- string (uuid, read-only). Unique identifier assigned by the server on creation.
widget_type -- string (read-only). Always "Note" for this endpoint.
location -- object (patchable). Position relative to the parent widget, with x and y float fields.
size -- object (patchable). Dimensions in canvas units, with width and height float fields.
depth -- float (patchable). Z-order among sibling widgets. Higher values render on top. Must be >= 1.0 -- the server returns 400 Bad Request if you set depth below 1.0.
scale -- float (patchable). Uniform scale factor applied to the widget. Default: 1.
pinned -- boolean (patchable). When true, the widget cannot be moved or resized through touch interaction. API changes still apply. Default: false.
state -- string (read-only). Widget state, typically "normal".
parent_id -- string (uuid, patchable). ID of the parent widget. Changing this reparents the widget. Note that location coordinates are always relative to the parent -- changing parent_id without updating location will reinterpret the same x/y values in the new parent's coordinate space.
auto_raise -- boolean (patchable, PATCH only). When true, the server sets the widget's depth to the highest sibling depth + 1.0, bringing it to the front. Not persisted -- this is a one-shot parameter. Default: false.

Note-Specific Properties

text -- string (patchable). The body text content of the note. Default: "".
title -- string (patchable). The title displayed at the top of the note. Default: "".
background_color -- string (patchable). Hex color code for the note background, e.g. "#ffffff". Cannot be set while auto_text_color is true -- attempts return 409 Conflict. Set auto_text_color to false first, then set the color.
text_color -- string (patchable). Hex color code for the note text. Cannot be set while auto_text_color is true -- attempts return 409 Conflict. Set auto_text_color to false first, then set the color.
auto_text_color -- boolean (patchable). When true, the server automatically chooses a text color that contrasts with the background color. Default: true.

Streaming

All GET endpoints support real-time updates via the ?subscribe query parameter. When present, the server holds the connection open and sends newline-delimited JSON whenever the resource changes. The server sends periodic keepalive pings to maintain the connection.

List Notes

Retrieves all notes on a canvas.

GET /api/v1/canvases/:canvas_id/notes

Path parameters:

canvas_id (uuid, required) -- ID of the canvas

Query parameters:

subscribe (boolean, optional) -- Enable streaming updates

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes

Example response:

[
  {
    "auto_text_color": true,
    "background_color": "#ffffff",
    "depth": 3.0,
    "id": "f77e17a2-3716-46e4-8143-97dde114b20b",
    "location": {
      "x": 3892.45,
      "y": 3326.92
    },
    "parent_id": "fcc7bd6e-3334-4de6-ad95-2c0ab7d47b70",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 300,
      "width": 300
    },
    "state": "normal",
    "text": "Review Q3 objectives",
    "text_color": "#000000",
    "title": "Action Item",
    "widget_type": "Note"
  }
]

Get Single Note

Retrieves a single note by ID.

GET /api/v1/canvases/:canvas_id/notes/:note_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
note_id (uuid, required) -- ID of the note

Query parameters:

subscribe (boolean, optional) -- Enable streaming updates

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes/f77e17a2-3716-46e4-8143-97dde114b20b

Example response:

{
  "auto_text_color": true,
  "background_color": "#ffffff",
  "depth": 3.0,
  "id": "f77e17a2-3716-46e4-8143-97dde114b20b",
  "location": {
    "x": 3892.45,
    "y": 3326.92
  },
  "parent_id": "fcc7bd6e-3334-4de6-ad95-2c0ab7d47b70",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 300,
    "width": 300
  },
  "state": "normal",
  "text": "Review Q3 objectives",
  "text_color": "#000000",
  "title": "Action Item",
  "widget_type": "Note"
}

Create Note

Creates a new note on the canvas. All properties are optional -- the server assigns sensible defaults for any omitted fields.

POST /api/v1/canvases/:canvas_id/notes

Path parameters:

canvas_id (uuid, required) -- ID of the canvas

Request body (JSON):

text -- string. Body text for the note.
title -- string. Title displayed at the top.
background_color -- string. Hex color code (e.g. "#ffeb3b").
location -- object with x and y floats.
size -- object with width and height floats.
depth -- float. Must be >= 1.0.
scale -- float.
pinned -- boolean.
parent_id -- string (uuid).

Example request -- minimal (server picks defaults):

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes

Example request -- with properties:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Follow up with design team",
    "title": "TODO",
    "background_color": "#ffeb3b",
    "location": {"x": 1500, "y": 2000},
    "size": {"width": 400, "height": 300},
    "depth": 5.0
  }' \
  https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes

Example response:

{
  "auto_text_color": true,
  "background_color": "#ffeb3b",
  "depth": 5.0,
  "id": "65110c5c-3dd1-4d71-963e-ae1549fa2f9b",
  "location": {
    "x": 1500,
    "y": 2000
  },
  "parent_id": "fcc7bd6e-3334-4de6-ad95-2c0ab7d47b70",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 300,
    "width": 400
  },
  "state": "normal",
  "text": "Follow up with design team",
  "text_color": "#000000",
  "title": "TODO",
  "widget_type": "Note"
}

Update Note

Updates one or more properties of an existing note. Only the fields included in the request body are changed -- all other properties remain untouched.

PATCH /api/v1/canvases/:canvas_id/notes/:note_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
note_id (uuid, required) -- ID of the note to update

Request body (JSON):

Any combination of patchable properties: text, title, background_color, text_color, auto_text_color, location, size, depth, scale, pinned, parent_id, auto_raise.

Example request -- update text:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Updated action item text", "title": "DONE"}' \
  https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes/f77e17a2-3716-46e4-8143-97dde114b20b

Example request -- bring to front:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"auto_raise": true}' \
  https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes/f77e17a2-3716-46e4-8143-97dde114b20b

Example request -- set custom colors:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"auto_text_color": false, "background_color": "#1a237e", "text_color": "#ffffff"}' \
  https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes/f77e17a2-3716-46e4-8143-97dde114b20b

Example response:

{
  "auto_text_color": false,
  "background_color": "#1a237e",
  "depth": 3.0,
  "id": "f77e17a2-3716-46e4-8143-97dde114b20b",
  "location": {
    "x": 3892.45,
    "y": 3326.92
  },
  "parent_id": "fcc7bd6e-3334-4de6-ad95-2c0ab7d47b70",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 300,
    "width": 300
  },
  "state": "normal",
  "text": "Updated action item text",
  "text_color": "#ffffff",
  "title": "DONE",
  "widget_type": "Note"
}

Validation errors:

Setting depth below 1.0 returns 400 Bad Request: Depth must be >= 1.0, got <value>
Setting background_color or text_color while auto_text_color is true returns 409 Conflict

Delete Note

Permanently removes a note from the canvas.

DELETE /api/v1/canvases/:canvas_id/notes/:note_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
note_id (uuid, required) -- ID of the note to delete

Example request:

curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/78cfbcc8-aed9-4bbb-95ca-a0b9a5358d5a/notes/f77e17a2-3716-46e4-8143-97dde114b20b

A successful deletion returns an empty response with status 200 OK.

Error Responses

All endpoints return errors as JSON with a msg field.

400 Bad Request -- Invalid input (e.g. depth below 1.0, malformed JSON)
401 Unauthorized -- Missing or invalid authentication token
403 Forbidden -- View-only user attempted a write operation
404 Not Found -- Canvas or note does not exist
409 Conflict -- Attempted to set color properties while auto_text_color is enabled

Example error response:

{"msg": "Depth must be >= 1.0, got -1.0"}

Notes

Authentication

Common Widget Properties

Note-Specific Properties

Streaming

List Notes

Get Single Note

Create Note

Update Note

Delete Note

Error Responses