BEEOS CLOUD / DEVELOPER REFERENCE

Canvases

Canvas share links, snapshots, and conversation canvas sessions.

Overview

The canvases domain manages the share links and snapshots of an instance's canvases and resolves the canvas session of a conversation.

6 operations · SDK resource: TypeScript cloud.canvases · Python cloud.canvases · Go cloud.Canvases · API overview

Main objects

CanvasShare: a canvas share link.
CanvasSnapshot: a saved state of a canvas.
CanvasSessionDocument: the canvas session of a conversation.

CanvasShare

Field	Type	Required	Description
`id`	`string`	yes	Unique ID of the share.
`canvasId`	`string`	yes	ID of the canvas that is shared. A canvas has at most one share.
`slug`	`string`	yes	Public identifier of the share, used to build the share link. It stays the same when the share is updated.
`mode`	`string`	yes	How visitors get access. `password` requires visitors to enter the password set when the share was created. Any other value, for example `link`, lets anyone who has the link open the canvas.
`allowInteraction`	`boolean`	yes	Whether visitors can interact with the canvas. When false, visitors can only view it.
`expiresAt`	`string`	no	Time the share stops working, as an RFC 3339 timestamp. Omitted when the share does not expire; shares created through this API never expire.
`createdAt`	`string`	yes	Time the share was first created, as an RFC 3339 timestamp. Updating the share does not change it.

Every field, and the methods that use this object: appendix.

CanvasSnapshot

Field	Type	Required	Description
`id`	`string`	yes	Unique ID of the snapshot. Pass it to the restore operation.
`canvasId`	`string`	yes	ID of the canvas the snapshot belongs to.
`componentsSnapshot`	`string`	no	Content of the canvas when the snapshot was taken, as base64-encoded JSON: an array of surfaces, each with `surfaceId`, `presentation`, `components` and `root`. Omitted when no content was captured.
`actorType`	`string`	yes	Kind of actor that made most of the changes recorded by the snapshot: `user` for a person (restore points are also recorded as `user`), `agent` for an agent, or `system` for an automatic snapshot with no known actor.
`actorId`	`string`	yes	ID of the actor named by `actorType`. `system` for automatic snapshots with no known actor.
`description`	`string`	no	Short note about the snapshot, for example `Auto-snapshot` for automatic snapshots or `Restored from v3` for a restore point. Omitted when there is none.
`version`	`integer`	yes	Version of the canvas content the snapshot records. A higher number is newer.
`createdAt`	`string`	yes	Time the snapshot was taken, as an RFC 3339 timestamp.

Every field, and the methods that use this object: appendix.

CanvasSessionDocument

Field	Type	Required	Description
`transport`	`string`	yes	How the ticket connects: always `relay`.
`protocolVersion`	`integer`	yes	Version of the ticket protocol. Currently 1.
`header`	RealtimeTicketHeader	yes	Header of the signed ticket.
`relayUrl`	`string`	yes	WebSocket URL of the canvas relay for the canvas, ending in `/ws/{canvasId}`.
`ticket`	`string`	yes	Signed single-use ticket (a JWT) that authorizes one relay connection. It is valid for 60 seconds.
`issuedAt`	`string`	yes	Time the ticket was issued, as an RFC 3339 timestamp. Constraints: `format=date-time`.
`expiresAt`	`string`	yes	Time the ticket expires, as an RFC 3339 timestamp. Tickets are valid for 60 seconds. Constraints: `format=date-time`.
`claims`	CanvasTicketClaims	yes	Claims contained in the signed ticket.

Every field, and the methods that use this object: appendix.

RealtimeTicketHeader

Field	Type	Required	Description
`alg`	`string`	yes	Signature algorithm of the ticket: `RS256`.
`typ`	`string`	yes	Token type: `JWT`.
`kid`	`string`	yes	ID of the key that signed the ticket.

Every field, and the methods that use this object: appendix.

CanvasTicketClaims

Field	Type	Required	Description
`iss`	`string`	yes	Issuer of the ticket.
`sub`	`string`	yes	Unused. Cloud does not accept an external user id, so this claim is empty.
`jti`	`string`	yes	Unique ID of the ticket.
`purpose`	`string`	yes	Purpose of the ticket: always `canvas_session`.
`instance_id`	`string`	yes	ID of the instance the canvas belongs to.
`platform_agent_id`	`string`	yes	ID of the agent the canvas session is for, the `platformAgentId` of the request.
`client_id`	`string`	yes	ID generated for this relay client connection.
`conversation_id`	`string`	yes	ID of the conversation the canvas belongs to, the `conversationId` of the request.
`canvas_id`	`string`	yes	ID of the canvas the ticket grants access to.
`role`	`string`	yes	Access role granted on the canvas: `viewer` or `editor`. Allowed values: `"viewer"` — Can view the canvas but not change it; `"editor"` — Can view and edit the canvas. (enum table)
`session_id`	`string`	yes	ID of the realtime session created for this ticket.
`aud`	`array<string>`	yes	Audiences the ticket is intended for: the canvas relay.
`iat`	`integer`	yes	Time the ticket was issued, in Unix seconds.
`exp`	`integer`	yes	Time the ticket expires, in Unix seconds.

Every field, and the methods that use this object: appendix.

Typical flow

Resolve the canvas session of a conversation with canvases.getSession.
Share a canvas with canvases.createShare and read the link with canvases.getShare; withdraw it with canvases.deleteShare.
List the saved states with canvases.listSnapshots and bring one back with canvases.restoreSnapshot.

Methods

Method	HTTP	Summary
canvases.getSession	`GET /v1/instances/{instanceId}/canvas-sessions/{conversationId}`	Resolve a conversation canvas session
canvases.getShare	`GET /v1/instances/{instanceId}/canvases/{canvasId}/share`	Get a canvas share link
canvases.createShare	`POST /v1/instances/{instanceId}/canvases/{canvasId}/share`	Create a canvas share link
canvases.deleteShare	`DELETE /v1/instances/{instanceId}/canvases/{canvasId}/share`	Revoke a canvas share link
canvases.listSnapshots	`GET /v1/instances/{instanceId}/canvases/{canvasId}/snapshots`	List canvas snapshots
canvases.restoreSnapshot	`POST /v1/instances/{instanceId}/canvases/{canvasId}/snapshots/{snapshotId}/restore`	Restore a canvas snapshot

canvases.getSession

GET /v1/instances/{instanceId}/canvas-sessions/{conversationId} · Operation ID getCanvasSession

Resolve a conversation canvas session

SDK methods

Language	Method	Signature
TypeScript	`cloud.canvases.getSession`	`getSession(instanceId: string, conversationId: string, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.GetCanvasSessionResponse>`
Python	`cloud.canvases.get_session`	`def get_session(self, instance_id: str, conversation_id: str, options: GetCanvasSessionOptions) -> GetCanvasSessionResponse`
Go	`cloud.Canvases.GetSession`	`func (r *CanvasesResource) GetSession(ctx context.Context, instanceId string, conversationId string, options GetCanvasSessionOptions) (GetCanvasSessionResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance that hosts the agent. It must belong to your app.
`conversationId`	path	`string`	yes	ID of the conversation to look up the canvas session for. It must equal the `X-BeeOS-Conversation-ID` header.
`X-BeeOS-Conversation-ID`	header	`string`	yes	ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path.
`X-BeeOS-Platform-Agent-ID`	header	`string`	yes	ID of the agent that owns the canvas. It must be an agent of `instanceId`.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	`object`	yes	Nullable.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.canvases.getSession("instance_123", "conversation_123", "conversation_123", "agent_123");
console.log(result);

canvases.getShare

GET /v1/instances/{instanceId}/canvases/{canvasId}/share · Operation ID getShareCanvas

Get a canvas share link

SDK methods

Language	Method	Signature
TypeScript	`cloud.canvases.getShare`	`getShare(instanceId: string, canvasId: string, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.GetShareCanvasResponse>`
Python	`cloud.canvases.get_share`	`def get_share(self, instance_id: str, canvas_id: str, options: GetShareCanvasOptions) -> GetShareCanvasResponse`
Go	`cloud.Canvases.GetShare`	`func (r *CanvasesResource) GetShare(ctx context.Context, instanceId string, canvasId string, options GetShareCanvasOptions) (GetShareCanvasResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance that hosts the agent. It must belong to your app.
`canvasId`	path	`string`	yes	ID of the canvas, a UUID. The canvas must belong to the conversation and agent named by the headers.
`X-BeeOS-Conversation-ID`	header	`string`	yes	ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path.
`X-BeeOS-Platform-Agent-ID`	header	`string`	yes	ID of the agent that owns the canvas. It must be an agent of `instanceId`.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	CanvasShare	yes	Nullable.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.canvases.getShare("instance_123", "canvas_123", "conversation_123", "agent_123");
console.log(result);

canvases.createShare

POST /v1/instances/{instanceId}/canvases/{canvasId}/share · Operation ID createShareCanvas

Create a canvas share link

SDK methods

Language	Method	Signature
TypeScript	`cloud.canvases.createShare`	`createShare(instanceId: string, canvasId: string, input: Models.CreateShareCanvasRequest, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.CreateShareCanvasResponse>`
Python	`cloud.canvases.create_share`	`def create_share(self, instance_id: str, canvas_id: str, input: CreateShareCanvasRequest, options: CreateShareCanvasOptions) -> CreateShareCanvasResponse`
Go	`cloud.Canvases.CreateShare`	`func (r *CanvasesResource) CreateShare(ctx context.Context, instanceId string, canvasId string, input CreateShareCanvasRequest, options CreateShareCanvasOptions) (CreateShareCanvasResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance that hosts the agent. It must belong to your app.
`canvasId`	path	`string`	yes	ID of the canvas, a UUID. The canvas must belong to the conversation and agent named by the headers.
`X-BeeOS-Conversation-ID`	header	`string`	yes	ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path.
`X-BeeOS-Platform-Agent-ID`	header	`string`	yes	ID of the agent that owns the canvas. It must be an agent of `instanceId`.

Request body

application/json · required

Field	Type	Required	Description
`mode`	`string`	yes	How visitors get access: `password` to protect the share with `password`, or any other value, for example `link`, to let anyone with the link open the canvas. Required.
`password`	`string`	no	Password visitors must enter. Used only when `mode` is `password`; without it no visitor can pass the check.
`allowInteraction`	`boolean`	no	Whether visitors can interact with the canvas. Defaults to true. Send false to make the share view-only.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	CanvasShare	yes	Nullable.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.canvases.createShare("instance_123", "canvas_123", { mode: "example_mode" }, "conversation_123", "agent_123");
console.log(result);

canvases.deleteShare

DELETE /v1/instances/{instanceId}/canvases/{canvasId}/share · Operation ID deleteShareCanvas

Revoke a canvas share link

SDK methods

Language	Method	Signature
TypeScript	`cloud.canvases.deleteShare`	`deleteShare(instanceId: string, canvasId: string, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.DeleteShareCanvasResponse>`
Python	`cloud.canvases.delete_share`	`def delete_share(self, instance_id: str, canvas_id: str, options: DeleteShareCanvasOptions) -> None`
Go	`cloud.Canvases.DeleteShare`	`func (r *CanvasesResource) DeleteShare(ctx context.Context, instanceId string, canvasId string, options DeleteShareCanvasOptions) error`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance that hosts the agent. It must belong to your app.
`canvasId`	path	`string`	yes	ID of the canvas, a UUID. The canvas must belong to the conversation and agent named by the headers.
`X-BeeOS-Conversation-ID`	header	`string`	yes	ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path.
`X-BeeOS-Platform-Agent-ID`	header	`string`	yes	ID of the agent that owns the canvas. It must be an agent of `instanceId`.

Response

204

No response body.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.canvases.deleteShare("instance_123", "canvas_123", "conversation_123", "agent_123");
console.log(result);

canvases.listSnapshots

GET /v1/instances/{instanceId}/canvases/{canvasId}/snapshots · Operation ID listCanvasSnapshots

List canvas snapshots

SDK methods

Language	Method	Signature
TypeScript	`cloud.canvases.listSnapshots`	`listSnapshots(instanceId: string, canvasId: string, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.ListCanvasSnapshotsResponse>`
Python	`cloud.canvases.list_snapshots`	`def list_snapshots(self, instance_id: str, canvas_id: str, options: ListCanvasSnapshotsOptions) -> ListCanvasSnapshotsResponse`
Go	`cloud.Canvases.ListSnapshots`	`func (r *CanvasesResource) ListSnapshots(ctx context.Context, instanceId string, canvasId string, options ListCanvasSnapshotsOptions) (ListCanvasSnapshotsResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance that hosts the agent. It must belong to your app.
`canvasId`	path	`string`	yes	ID of the canvas, a UUID. The canvas must belong to the conversation and agent named by the headers.
`X-BeeOS-Conversation-ID`	header	`string`	yes	ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path.
`X-BeeOS-Platform-Agent-ID`	header	`string`	yes	ID of the agent that owns the canvas. It must be an agent of `instanceId`.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	array<CanvasSnapshot>	yes	—

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.canvases.listSnapshots("instance_123", "canvas_123", "conversation_123", "agent_123");
console.log(result);

canvases.restoreSnapshot

POST /v1/instances/{instanceId}/canvases/{canvasId}/snapshots/{snapshotId}/restore · Operation ID restoreCanvasSnapshot

Restore a canvas snapshot

SDK methods

Language	Method	Signature
TypeScript	`cloud.canvases.restoreSnapshot`	`restoreSnapshot(instanceId: string, canvasId: string, snapshotId: string, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.RestoreCanvasSnapshotResponse>`
Python	`cloud.canvases.restore_snapshot`	`def restore_snapshot(self, instance_id: str, canvas_id: str, snapshot_id: str, options: RestoreCanvasSnapshotOptions) -> RestoreCanvasSnapshotResponse`
Go	`cloud.Canvases.RestoreSnapshot`	`func (r *CanvasesResource) RestoreSnapshot(ctx context.Context, instanceId string, canvasId string, snapshotId string, options RestoreCanvasSnapshotOptions) (RestoreCanvasSnapshotResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance that hosts the agent. It must belong to your app.
`canvasId`	path	`string`	yes	ID of the canvas, a UUID. The canvas must belong to the conversation and agent named by the headers.
`snapshotId`	path	`string`	yes	ID of the snapshot to restore, as returned by the snapshot list.
`X-BeeOS-Conversation-ID`	header	`string`	yes	ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path.
`X-BeeOS-Platform-Agent-ID`	header	`string`	yes	ID of the agent that owns the canvas. It must be an agent of `instanceId`.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	`object`	yes	—
`data.snapshotId`	`string`	yes	—
`data.canvasId`	`string`	yes	—
`data.restored`	`boolean`	yes	—
`data.version`	`integer`	yes	—

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.canvases.restoreSnapshot("instance_123", "canvas_123", "snapshot_123", "conversation_123", "agent_123");
console.log(result);

BeeOS CloudBack to documentation