Browsers

Browsers are embedded web view widgets on a Canvus canvas. Each browser widget renders a live web page directly on the canvas, functioning as a fully interactive browser window that can be positioned, scaled, and pinned alongside other canvas content.

Use browsers to display dashboards, documentation, web applications, or any URL-accessible content within a collaborative canvas session.

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 browser 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 "Browser" 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. This defines the viewport size of the embedded browser.
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.

Browser-Specific Properties

url -- string (patchable). The URL loaded in the embedded browser. Changing this navigates the browser to the new URL. Default: "https://www.google.com/".
title -- string (patchable). Display title for the browser widget. This is typically set automatically from the web page title but can be overridden. Default: "".
transparent_mode -- boolean (patchable). When true, the browser renders with a transparent background, allowing canvas content behind it to show through. Default: false.
main_frame_scroll_offset -- object (patchable). Current scroll position of the main frame, with x and y float fields. Default: {"x": 0, "y": 0}.

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 Browsers

Retrieves all browser widgets on a canvas.

GET /api/v1/canvases/:canvas_id/browsers

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/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers

Example response:

[
  {
    "depth": 5.0,
    "id": "82796808-84e4-4309-8d76-bd0cee281a22",
    "location": {
      "x": 4932.95,
      "y": 2223.87
    },
    "main_frame_scroll_offset": {
      "x": 0,
      "y": 320
    },
    "parent_id": "51e47ebf-bab1-4412-a48a-5f635ed22f33",
    "pinned": false,
    "scale": 1,
    "size": {
      "height": 800,
      "width": 1200
    },
    "state": "normal",
    "title": "Project Dashboard",
    "transparent_mode": false,
    "url": "https://dashboard.example.com/overview",
    "widget_type": "Browser"
  }
]

Get Single Browser

Retrieves a single browser widget by ID.

GET /api/v1/canvases/:canvas_id/browsers/:browser_id

Path parameters:

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

Query parameters:

subscribe (boolean, optional) -- Enable streaming updates

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers/82796808-84e4-4309-8d76-bd0cee281a22

Example response:

{
  "depth": 5.0,
  "id": "82796808-84e4-4309-8d76-bd0cee281a22",
  "location": {
    "x": 4932.95,
    "y": 2223.87
  },
  "main_frame_scroll_offset": {
    "x": 0,
    "y": 320
  },
  "parent_id": "51e47ebf-bab1-4412-a48a-5f635ed22f33",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 800,
    "width": 1200
  },
  "state": "normal",
  "title": "Project Dashboard",
  "transparent_mode": false,
  "url": "https://dashboard.example.com/overview",
  "widget_type": "Browser"
}

Create Browser

Creates a new browser widget on the canvas. All properties are optional -- the server assigns sensible defaults for any omitted fields, including a default URL of https://www.google.com/.

POST /api/v1/canvases/:canvas_id/browsers

Path parameters:

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

Request body (JSON):

url -- string. URL to load in the browser.
title -- string. Display title.
transparent_mode -- boolean.
main_frame_scroll_offset -- object with x and y floats.
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 -- with URL:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://dashboard.example.com/overview",
    "title": "Project Dashboard",
    "size": {"width": 1920, "height": 1080},
    "depth": 3.0
  }' \
  https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers

Example request -- minimal (defaults):

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers

Example response:

{
  "depth": 3.0,
  "id": "cb1f6489-13c0-4f8a-b94e-3b56ddbd2aba",
  "location": {
    "x": 5010.69,
    "y": 2646.40
  },
  "main_frame_scroll_offset": {
    "x": 0,
    "y": 0
  },
  "parent_id": "51e47ebf-bab1-4412-a48a-5f635ed22f33",
  "pinned": false,
  "scale": 1,
  "size": {
    "height": 1080,
    "width": 1920
  },
  "state": "normal",
  "title": "Project Dashboard",
  "transparent_mode": false,
  "url": "https://dashboard.example.com/overview",
  "widget_type": "Browser"
}

Update Browser

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

PATCH /api/v1/canvases/:canvas_id/browsers/:browser_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
browser_id (uuid, required) -- ID of the browser to update

Request body (JSON):

Any combination of patchable properties: url, title, transparent_mode, main_frame_scroll_offset, location, size, depth, scale, pinned, parent_id, auto_raise.

Example request -- navigate to a new URL:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://docs.example.com/api-reference"}' \
  https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers/82796808-84e4-4309-8d76-bd0cee281a22

Example request -- enable transparent mode:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transparent_mode": true}' \
  https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers/82796808-84e4-4309-8d76-bd0cee281a22

Example request -- resize and pin:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"size": {"width": 1920, "height": 1080}, "pinned": true}' \
  https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers/82796808-84e4-4309-8d76-bd0cee281a22

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/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers/82796808-84e4-4309-8d76-bd0cee281a22

Example response:

{
  "depth": 5.0,
  "id": "82796808-84e4-4309-8d76-bd0cee281a22",
  "location": {
    "x": 4932.95,
    "y": 2223.87
  },
  "main_frame_scroll_offset": {
    "x": 0,
    "y": 0
  },
  "parent_id": "51e47ebf-bab1-4412-a48a-5f635ed22f33",
  "pinned": true,
  "scale": 1,
  "size": {
    "height": 1080,
    "width": 1920
  },
  "state": "normal",
  "title": "Project Dashboard",
  "transparent_mode": true,
  "url": "https://docs.example.com/api-reference",
  "widget_type": "Browser"
}

Validation errors:

Setting depth below 1.0 returns 400 Bad Request: Depth must be >= 1.0, got <value>
Setting size with zero or negative dimensions is rejected

Delete Browser

Permanently removes a browser widget from the canvas.

DELETE /api/v1/canvases/:canvas_id/browsers/:browser_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
browser_id (uuid, required) -- ID of the browser to delete

Example request:

curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/d098152c-8abf-4ebd-8a33-2fdf3ffe0214/browsers/82796808-84e4-4309-8d76-bd0cee281a22

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 browser does not exist

Example error response:

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

Browsers

Authentication

Common Widget Properties

Browser-Specific Properties

Streaming

List Browsers

Get Single Browser

Create Browser

Update Browser

Delete Browser

Error Responses