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 (flag, optional) -- Enable streaming updates. The parameter takes no value; its presence alone turns streaming on, so ?subscribe=false also streams.

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 (flag, optional) -- Enable streaming updates. The parameter takes no value; its presence alone turns streaming on, so ?subscribe=false also streams.

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.
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, 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

Current behavior

An invalid or expired token returns 403 Forbidden, not 401. See Current behavior.
Create does not yet enforce the depth limit. A widget created without depth gets 0, and a value below 1.0 is accepted. Only update rejects it.
A zero or negative size is not rejected. Create stores it; update ignores it and still returns 200 OK.
An update rejected with 400 Bad Request can still apply other fields sent in the same request.
title is not yet applied on create or update. The request succeeds, but the title stays as set by the client.

These are being corrected.

Example error response:

{"msg": "Depth must be >= 1, got 0"}

Browsers

Authentication

Common widget properties

Browser-specific properties

Streaming

List browsers

Get single browser

Create browser

Update browser

Delete browser

Error responses