Skip to content

Workspaces

A workspace is a rectangular display area on a connected Canvus client. Each workspace can show one canvas at a time, and a single client may have multiple workspaces arranged side by side across its physical displays.

Workspaces control what part of a canvas is visible on screen. The view_rectangle property defines the viewport -- the region of the canvas currently displayed in the workspace. By updating the view rectangle, you can programmatically pan and zoom the display.

When you would use this API:

  • Opening a specific canvas on a physical display
  • Controlling which part of a canvas is visible (pan and zoom)
  • Pinning a workspace to prevent touch interaction from changing the view
  • Showing or hiding the info panel
  • Building automation that cycles through canvases on a display wall
  • Monitoring which canvases are currently being shown on which displays

Authentication

All Workspaces endpoints require authentication via the Private-Token header.

Private-Token: YOUR_TOKEN

Streaming

All GET endpoints support the ?subscribe query parameter for long-poll streaming. When present, the server holds the connection open and sends newline-delimited JSON updates whenever the data changes. See the API overview for details.

List All Workspaces for a Client

Returns all workspaces belonging to a specific client.

  • Method: GET
  • URL: /api/v1/clients/:client_id/workspaces
  • Authentication: Required
  • Streaming: Supported via ?subscribe

Path parameters:

  • client_id (uuid, required) -- ID of the client

Query parameters:

  • subscribe (boolean, optional) -- Enable long-poll streaming

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/workspaces

Example response (200 OK):

[
  {
    "canvas_id": "df172fda-5e85-4b5c-b602-2eda5a6602f1",
    "canvas_size": {
      "height": 5400,
      "width": 9600
    },
    "index": 0,
    "info_panel_visible": true,
    "location": {
      "x": 0,
      "y": 0
    },
    "pinned": false,
    "server_id": "71ac3376-5020-4033-a159-71c213dc9be6",
    "size": {
      "height": 1080,
      "width": 1271
    },
    "state": "normal",
    "user": "guest",
    "view_rectangle": {
      "height": 648,
      "width": 762.6,
      "x": -2244.5,
      "y": -1080.0
    },
    "workspace_name": "Workspace 1",
    "workspace_state": "open"
  },
  {
    "canvas_id": "",
    "index": 1,
    "info_panel_visible": true,
    "location": {
      "x": 1271,
      "y": 0
    },
    "pinned": false,
    "server_id": "",
    "size": {
      "height": 1080,
      "width": 649
    },
    "state": "normal",
    "user": "",
    "view_rectangle": {
      "height": 648,
      "width": 389.4,
      "x": -3191,
      "y": -1080.0
    },
    "workspace_name": "Workspace 2",
    "workspace_state": "canvas_list"
  }
]

Response fields:

  • index (number) -- Zero-based index of this workspace on the client
  • workspace_name (string) -- Display name (e.g., "Workspace 1")
  • workspace_state (string) -- Current state of the workspace. Values include:
    • "open" -- A canvas is open and being displayed
    • "canvas_list" -- The workspace is showing the canvas browser, no canvas is open
  • canvas_id (string) -- ID of the canvas currently open in this workspace. Empty string if no canvas is open.
  • canvas_size (object) -- Width and height of the open canvas in canvas units. Only present when a canvas is open.
  • server_id (string) -- ID of the server hosting the open canvas. Empty string if no canvas is open. "internal" refers to the local server.
  • location (object) -- Position of this workspace on the client's display layout, in pixels
  • size (object) -- Width and height of this workspace in pixels
  • view_rectangle (object) -- The visible region of the canvas, in canvas coordinates. This defines what part of the canvas the user sees. Contains x, y, width, height.
  • pinned (boolean) -- Whether the workspace is pinned. A pinned workspace cannot be panned or zoomed by touch interaction.
  • info_panel_visible (boolean) -- Whether the workspace info panel is visible
  • user (string) -- The user logged into this workspace. "guest" for guest access, empty string if not logged in.
  • state (string) -- General state of the workspace object

Get a Single Workspace

Returns details for a single workspace identified by its index.

  • Method: GET
  • URL: /api/v1/clients/:client_id/workspaces/:workspace_index
  • Authentication: Required
  • Streaming: Supported via ?subscribe

Path parameters:

  • client_id (uuid, required) -- ID of the client
  • workspace_index (number, required) -- Zero-based index of the workspace

Query parameters:

  • subscribe (boolean, optional) -- Enable long-poll streaming

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/workspaces/0

Example response (200 OK):

{
  "canvas_id": "df172fda-5e85-4b5c-b602-2eda5a6602f1",
  "canvas_size": {
    "height": 5400,
    "width": 9600
  },
  "index": 0,
  "info_panel_visible": true,
  "location": {
    "x": 0,
    "y": 0
  },
  "pinned": false,
  "server_id": "71ac3376-5020-4033-a159-71c213dc9be6",
  "size": {
    "height": 1080,
    "width": 1271
  },
  "state": "normal",
  "user": "guest",
  "view_rectangle": {
    "height": 648,
    "width": 762.6,
    "x": -2244.5,
    "y": -1080.0
  },
  "workspace_name": "Workspace 1",
  "workspace_state": "open"
}

Update a Workspace

Modifies workspace properties such as the viewport, pinned state, or info panel visibility. To open a different canvas, use the Open Canvas endpoint instead.

  • Method: PATCH
  • URL: /api/v1/clients/:client_id/workspaces/:workspace_index
  • Authentication: Required
  • Streaming: Not applicable

Path parameters:

  • client_id (uuid, required) -- ID of the client
  • workspace_index (number, required) -- Zero-based index of the workspace

Request body fields (all optional):

  • info_panel_visible (boolean) -- Show or hide the info panel
  • pinned (boolean) -- Pin or unpin the workspace
  • view_rectangle (object) -- Set the visible canvas region. Contains x, y, width, height in canvas coordinates.

Example request -- pin a workspace:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}' \
  https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/workspaces/0

Example request -- zoom to a specific area:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"view_rectangle": {"x": 1000, "y": 500, "width": 2000, "height": 1200}}' \
  https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/workspaces/0

Example response (200 OK):

Returns the full workspace object with updated values. See the response fields documented under List All Workspaces.

Open Canvas

Opens a canvas in a specific workspace. This is how you programmatically control which canvas is displayed on a physical screen.

This endpoint does not report errors from the client side. If the request passes basic data validation, the server returns 200 OK immediately. To confirm whether the canvas actually opened, monitor the workspace state using the Get a Single Workspace endpoint with ?subscribe.

  • Method: POST
  • URL: /api/v1/clients/:client_id/workspaces/:workspace_index/open-canvas
  • Authentication: Required
  • Streaming: Not applicable

Path parameters:

  • client_id (uuid, required) -- ID of the client
  • workspace_index (number, required) -- Zero-based index of the workspace

Request body fields:

  • canvas_id (uuid, required) -- ID of the canvas to open
  • server_id (string, optional) -- ID of the server where the canvas is hosted. Defaults to the local server.
  • user_email (string, optional) -- The user on whose behalf the canvas is opened

server_id values:

  • A server UUID -- Opens a canvas on a specific remote server. That server must be configured on the client and be online.
  • "internal" -- The local server (same as omitting the parameter)
  • Empty string or omitted -- Same as "internal"

user_email values:

  • An email address -- Opens the canvas as that user. If the user is not currently logged in, the client will prompt for login.
  • "guest" -- Opens the canvas as the guest user
  • Empty string or omitted -- Uses the current workspace user

Example request:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "canvas_id": "df172fda-5e85-4b5c-b602-2eda5a6602f1",
    "server_id": "71ac3376-5020-4033-a159-71c213dc9be6"
  }' \
  https://canvus.example.com/api/v1/clients/e5cad8d4-7051-4051-97bc-13e41fd81ca7/workspaces/0/open-canvas

Response (200 OK):

An empty response body. Monitor the workspace state to confirm the canvas opened successfully.

Error Responses

  • 401 Unauthorized -- Missing or invalid Private-Token
  • 404 Not Found -- The specified client or workspace does not exist

All errors return a JSON body:

{
  "msg": "error description"
}