Anchors API

Anchors are visual marker widgets that you place on a canvas to designate named regions or points of interest. They act as spatial bookmarks -- use them to label zones on a large canvas, define navigation targets for workspace views, or mark areas that other automation should reference by name.

Anchors behave like other canvas widgets (they have position, size, depth, and scale) but carry no media content. Their purpose is purely organizational: a named rectangle on the canvas that humans and integrations can use as a reference point.

Every anchor shares these properties with other canvas widget types:

id (string, uuid) -- Unique identifier assigned by the server. Read-only.
location (object) -- Position on the canvas as {"x": float, "y": float}. Coordinates are relative to the anchor's parent widget.
size (object) -- Dimensions as {"width": float, "height": float}.
depth (number, float) -- Z-order relative to sibling widgets. Higher values render on top. Must be >= 1.0.
scale (number, float) -- Scale factor. Default is 1.
pinned (boolean) -- When true, the anchor cannot be moved or resized through the touch UI. API writes are unaffected.
state (string) -- Widget state. Typically "normal".
parent_id (string, uuid) -- ID of the parent widget or canvas root. Read-only in responses.
widget_type (string) -- Always "Anchor" for this resource. Read-only.

Anchor-Specific Properties

anchor_name (string) -- A human-readable label for the anchor. Patchable. Defaults to "New anchor".
anchor_index (number, integer) -- Numeric index assigned to the anchor. Patchable.

Auto-Raise

All PATCH requests accept an optional auto_raise boolean parameter (default false). When set to true, the anchor's depth is automatically set to one level above the highest sibling, matching the UI's bring-to-front behavior.

List Anchors

Returns all anchors on the specified canvas.

GET /api/v1/canvases/:canvas_id/anchors

Path parameters:

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

Query parameters:

subscribe (boolean, optional) -- When present, the server holds the connection open and streams updates as newline-delimited JSON. See Streaming.

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors

Example response:

[
  {
    "anchor_index": 0,
    "anchor_name": "Stage Left",
    "depth": 3,
    "id": "5da69125-a5f5-417d-8d8d-a633a0499560",
    "location": {
      "x": 4676.818359375,
      "y": 2432.80126953125
    },
    "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 800,
      "width": 1200
    },
    "state": "normal",
    "widget_type": "Anchor"
  }
]

Get Single Anchor

Returns a single anchor by ID.

GET /api/v1/canvases/:canvas_id/anchors/:anchor_id

Path parameters:

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

Query parameters:

subscribe (boolean, optional) -- Enable streaming updates

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors/5da69125-a5f5-417d-8d8d-a633a0499560

Example response:

{
  "anchor_index": 0,
  "anchor_name": "Stage Left",
  "depth": 3,
  "id": "5da69125-a5f5-417d-8d8d-a633a0499560",
  "location": {
    "x": 4676.818359375,
    "y": 2432.80126953125
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 800,
    "width": 1200
  },
  "state": "normal",
  "widget_type": "Anchor"
}

Create Anchor

Creates a new anchor on the canvas. All properties are optional -- the server assigns sensible defaults.

POST /api/v1/canvases/:canvas_id/anchors

Path parameters:

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

Body parameters (JSON):

anchor_name (string, optional) -- Label for the anchor. Defaults to "New anchor".
anchor_index (number, optional) -- Numeric index.
location (object, optional) -- Position as {"x": float, "y": float}.
size (object, optional) -- Dimensions as {"width": float, "height": float}.
depth (number, optional) -- Z-order. Must be >= 1.0.
scale (number, optional) -- Scale factor.
pinned (boolean, optional) -- Whether the anchor is pinned in the UI.

Example request:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "anchor_name": "Presenter Zone",
    "location": {"x": 1000, "y": 500},
    "size": {"width": 1920, "height": 1080}
  }' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors

Example response:

{
  "anchor_index": 1,
  "anchor_name": "Presenter Zone",
  "depth": 1,
  "id": "8cf37672-e642-449d-881e-6ee6e42afc16",
  "location": {
    "x": 1000,
    "y": 500
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 1080,
    "width": 1920
  },
  "state": "normal",
  "widget_type": "Anchor"
}

Update Anchor

Updates one or more properties of an existing anchor. Only include the fields you want to change.

PATCH /api/v1/canvases/:canvas_id/anchors/:anchor_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
anchor_id (uuid, required) -- ID of the anchor to update

Body parameters (JSON):

anchor_name (string, optional) -- New label.
anchor_index (number, optional) -- New index.
location (object, optional) -- New position.
size (object, optional) -- New dimensions.
depth (number, optional) -- New z-order. Must be >= 1.0.
scale (number, optional) -- New scale factor.
pinned (boolean, optional) -- New pinned state.
auto_raise (boolean, optional) -- When true, depth is set above all siblings.

Example request:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"anchor_name": "Region A", "pinned": true}' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors/5da69125-a5f5-417d-8d8d-a633a0499560

Example response:

{
  "anchor_index": 0,
  "anchor_name": "Region A",
  "depth": 3,
  "id": "5da69125-a5f5-417d-8d8d-a633a0499560",
  "location": {
    "x": 4676.818359375,
    "y": 2432.80126953125
  },
  "parent_id": "08596c44-389c-45d6-9f32-a9940c54b7d9",
  "pinned": true,
  "scale": 1,
  "size": {
    "height": 800,
    "width": 1200
  },
  "state": "normal",
  "widget_type": "Anchor"
}

Delete Anchor

Permanently removes an anchor from the canvas. Any connectors attached to this anchor are also deleted.

DELETE /api/v1/canvases/:canvas_id/anchors/:anchor_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
anchor_id (uuid, required) -- ID of the anchor to delete

Example request:

curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors/5da69125-a5f5-417d-8d8d-a633a0499560

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

Streaming

All GET endpoints support the ?subscribe query parameter. When present, the response uses long-polling to stream updates as newline-delimited JSON. Each time an anchor's properties change, the server pushes the updated anchor object. See Streaming for connection management details.

curl -H "Private-Token: YOUR_TOKEN" \
  "https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/anchors?subscribe"

Error Cases

400 Bad Request -- Invalid JSON, depth below 1.0, or zero/negative size dimensions.
401 Unauthorized -- Missing or invalid Private-Token header.
403 Forbidden -- View-only users cannot create, update, or delete anchors.
404 Not Found -- The canvas ID or anchor ID does not exist.

Anchors API

Common Widget Properties

Anchor-Specific Properties

Auto-Raise

List Anchors

Get Single Anchor

Create Anchor

Update Anchor

Delete Anchor

Streaming

Error Cases