BEEOS CLOUD / DEVELOPER REFERENCE

Instances

Create, read, update, start, stop, upgrade, and delete instances; open terminal and canvas sessions; run commands; get connect and stream URLs.

Overview

The instances domain manages the instances your product runs: list, create, read, update, start, stop, upgrade, and delete them. It also opens terminal and canvas sessions, runs a command in an instance, and returns connect and stream URLs.

15 operations · SDK resource: TypeScript cloud.instances · Python cloud.instances · Go cloud.Instances · API overview

Main objects

CreateServerInstanceInput: the request to create an instance.
RuntimeInstanceResult: the instance returned by create, read, start, stop, and delete; InstancePage lists InstanceSummary entries.
RuntimeInstanceStatusResult: the status of an instance.
RuntimeUpgradeJob: the state of an upgrade.
TerminalSessionDocument, CanvasSessionDocument, RuntimeExecResult, and ConnectURLResponse: the results of the session, command, and URL operations.

CreateServerInstanceInput

Field	Type	Required	Description
`name`	`string`	yes	Display name of the instance, 1 to 128 bytes, without leading or trailing whitespace.
`variant_id`	`string`	no	ID of the catalog variant to create the instance from, at most 128 characters. See the instance template catalog for available variants. An unknown ID returns 404 `variant_not_found`.
`harness`	`string`	no	Harness to run in the instance. Only `openclaw` is accepted. Allowed values: `"openclaw"` — The OpenClaw agent runtime.
`llm`	RuntimeLLM	no	Model providers and models the instance uses. Required when the variant or harness needs caller-supplied models; omit it for variants that supply their own models. Provider API keys are write-only. Nullable.

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

RuntimeInstanceResult

Field	Type	Required	Description
`data`	RuntimeInstanceSummary	yes	The instance as of this response.
`operation`	RuntimeOperationSummary	yes	Lifecycle operation that this response reports on.

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

InstancePage

Field	Type	Required	Description
`data`	array<InstanceSummary>	yes	Instances on this page, newest first.
`total`	`integer`	yes	Total number of instances that match the filters, across all pages.

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

InstanceSummary

Field	Type	Required	Description
`has_ever_run`	`boolean`	yes	Whether the instance has ever reached the running state. False means it has never delivered a running service.
`id`	`string`	yes	Unique ID of the instance.
`organization_id`	`string`	yes	ID of the organization that owns the instance.
`app_id`	`string`	yes	ID of the app the instance belongs to.
`developer_id`	`string`	yes	ID of the developer account the instance was created under.
`name`	`string`	yes	Display name of the instance.
`harness`	`string`	yes	Product harness name (for example `openclaw`), not a UHP `harness_id` (`chrn_*`).
`provider_id`	`string`	yes	ID of the provider that hosts the instance.
`region`	`string`	yes	Region the instance is deployed in.
`os_type`	`string`	yes	Operating system of the instance: `linux`, `windows`, `android` or `macos`.
`status`	`string`	yes	Lifecycle phase of the instance: `pending`, `provisioning`, `running`, `stopped` or `terminated`. Allowed values: see the table below, InstanceSummary.status values.
`desired_status`	`string`	yes	Lifecycle phase the instance is being driven toward: `running`, `stopped` or `terminated`. Allowed values: `"running"` — The instance should be running; `"stopped"` — The instance should be stopped; `"terminated"` — The instance should be deleted. (enum table)
`connectivity`	`string`	yes	Reachability of the instance's agent: `unknown`, `online` or `offline`. Allowed values: `"unknown"` — Reachability has not been determined; `"online"` — The instance's agent is connected; `"offline"` — The instance's agent is not connected. (enum table)
`ms_connection_status`	`string`	yes	Status of the instance's message-channel connection: `unknown`, `connecting`, `connected`, `reconnecting`, `disconnected` or `failed`. It is reported independently of connectivity and is `unknown` while the instance is stopped or terminated, or has not reported recently.
`created_at`	`string`	yes	Time the instance was created, as an RFC 3339 UTC timestamp.
`updated_at`	`string`	yes	Time the instance was last updated, as an RFC 3339 UTC timestamp.
`resource_version`	`integer`	yes	Version of the instance record, starting at 1. Send it in the `If-Match` header of write requests so concurrent changes are detected. Constraints: `minimum=1`, `format=int64`.
`image_slot`	`string`	no	Variant trait. Key that selects the execution image for the instance. Not a container repository name.
`worker_image_id`	`string`	no	Variant trait. AgentBay worker image. Never the platform `image_id`.
`model_catalog`	`string`	no	Variant trait. `served` when Cloud answers model-list and reasoning-level requests, `none` when it answers neither. Empty and unknown values behave as `none`.
`billing_slot`	`string`	no	Variant trait. Key into the monthly fee table that prices the instance.
`icon_key`	`string`	no	Variant trait. UI icon selector. Clients must not derive it from `harness`.
`device_control`	`boolean`	no	Variant trait. Whether the instance accepts device-control commands. False means those commands are rejected.
`runtime_profile`	`string`	no	Variant trait. Profile of the agent runtime the instance uses. Known values are `openclaw`, `hermes` and `beeos-browser`.
`free_plan`	`boolean`	no	Variant trait. Whether the free plan allows the instance's variant. False means the free plan does not allow it.
`cloud_provider`	`string`	no	`agentbay`, `beeos`, or empty when self-hosted.

InstanceSummary.status values

Value	Meaning
`"pending"`	The instance was created and is waiting to be provisioned.
`"provisioning"`	The instance is being provisioned or started.
`"running"`	The instance is running.
`"stopped"`	The instance is stopped and can be started again.
`"terminated"`	The instance was deleted and cannot be used again.

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

RuntimeInstanceStatusResult

Field	Type	Required	Description
`data`	`object`	yes	Current status of the instance.
`data.id`	`string`	yes	Unique ID of the instance.
`data.name`	`string`	yes	Display name of the instance.
`data.status`	`string`	yes	Lifecycle phase of the instance: `pending`, `provisioning`, `running`, `stopped` or `terminated`. Allowed values: see the table below, RuntimeInstanceStatusResult.data.status values.
`data.desired_status`	`string`	yes	Lifecycle phase the instance is being driven toward: `running`, `stopped` or `terminated`. Allowed values: `"running"` — The instance should be running; `"stopped"` — The instance should be stopped; `"terminated"` — The instance should be deleted. (enum table)
`data.connectivity`	`string`	yes	Reachability of the instance's agent: `unknown`, `online` or `offline`. Allowed values: `"unknown"` — Reachability has not been determined; `"online"` — The instance's agent is connected; `"offline"` — The instance's agent is not connected. (enum table)
`operation`	RuntimeOperationSummary	yes	Lifecycle operation that this response reports on.

RuntimeInstanceStatusResult.data.status values

Value	Meaning
`"pending"`	The instance was created and is waiting to be provisioned.
`"provisioning"`	The instance is being provisioned or started.
`"running"`	The instance is running.
`"stopped"`	The instance is stopped and can be started again.
`"terminated"`	The instance was deleted and cannot be used again.

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

RuntimeUpgradeJob

Field	Type	Required	Description
`job_id`	`string`	yes	Unique ID of the upgrade job.
`image_version_id`	`string`	no	—
`instance_id`	`string`	yes	ID of the instance being upgraded.
`status`	`string`	yes	Status of the job: `upgrade_pending`, `rollback_pending`, `failed` or `succeeded`. Allowed values: `"upgrade_pending"` — The image upgrade is being applied; `"rollback_pending"` — The image upgrade failed and the instance is being rolled back to its previous image; `"failed"` — The image upgrade failed. See `error`; `"succeeded"` — The image upgrade finished and the instance runs the target version. (enum table)
`target`	`string`	yes	Image version the instance is being upgraded to.
`created_at`	`string`	yes	Time the job was created, as an RFC 3339 UTC timestamp.
`completed_at`	`string`	no	Time the job finished, as an RFC 3339 UTC timestamp. Omitted while the job is not finished. Nullable.
`error`	`string`	no	Stable failure code. Omitted unless the job failed. Nullable.

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

TerminalSessionDocument

Field	Type	Required	Description
`transport`	`string`	yes	How the ticket connects: always `service-websocket`.
`protocolVersion`	`integer`	yes	Version of the ticket protocol. Currently 1.
`header`	RealtimeTicketHeader	yes	Header of the signed ticket.
`websocketUrl`	`string`	yes	WebSocket URL to open the terminal connection on. It already carries the ticket as a query parameter.
`ticket`	`string`	yes	Signed single-use ticket (a JWT) that authorizes one terminal 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`	TerminalTicketClaims	yes	Claims contained in the signed ticket.

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.

RuntimeExecResult

Field	Type	Required	Description
`exit_code`	`integer`	yes	Exit code of the command.
`stdout`	`string`	yes	Standard output of the command, at most 64 KiB.
`stderr`	`string`	yes	Standard error of the command, at most 64 KiB.
`truncated`	`boolean`	yes	Whether the output was truncated.

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

ConnectURLResponse

Field	Type	Required	Description
`data`	`object`	yes	Connection details for the requested service.
`data.url`	`string`	yes	URL to connect to. For `browser` it is the browser viewer URL; for `acp` it is a WebSocket URL that already carries the access ticket as a query parameter.
`data.mode`	`string`	yes	Connection mode: `browser-runtime` for `browser`, `service-websocket` for `acp`. Allowed values: `"browser-runtime"` — A browser viewer session; connect with `url` and `token`; `"service-websocket"` — A WebSocket connection to an agent service; `url` already carries the access ticket. (enum table)
`data.token`	`string`	yes	Short-lived access token for the browser viewer. Not returned for `acp`.
`data.service`	`string`	yes	Service the URL connects to: `browser` or `acp`. Allowed values: `"browser"` — The browser viewer; `"acp"` — The agent connection over WebSocket. (enum table)
`data.connectivity`	`string`	yes	Reachability of the instance's agent: `unknown`, `online` or `offline`. Allowed values: `"unknown"` — Reachability has not been determined; `"online"` — The instance's agent is connected; `"offline"` — The instance's agent is not connected. (enum table)
`data.stream_session_id`	`string`	yes	ID of the viewing client session, the `client_id` sent in the request. Not returned for `acp`.
`data.browser`	`object`	no	Browser access grant. Returned only for `browser`.
`data.browser.grant_id`	`string`	yes	ID of the browser access grant.
`data.browser.generation`	`string`	yes	Generation of the browser the grant is bound to. When `generation` was sent in the request, it equals that value.
`data.browser.expires_at`	`string`	yes	Time the access grant expires, in Unix milliseconds.
`data.browser.role`	`string`	yes	Access role of the grant: `viewer` or `controller`. Allowed values: `"viewer"` — Can watch the browser but not control it; `"controller"` — Can watch and control the browser. (enum table)

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

RuntimeInstanceSummary

Field	Type	Required	Description
`id`	`string`	yes	Unique ID of the instance.
`organization_id`	`string`	yes	ID of the organization that owns the instance.
`app_id`	`string`	yes	ID of the app the instance belongs to.
`developer_id`	`string`	yes	ID of the developer account the instance was created under.
`name`	`string`	yes	Display name of the instance.
`harness`	`string`	yes	Product harness name (for example `openclaw`), not a UHP `harness_id` (`chrn_*`).
`provider_id`	`string`	yes	ID of the provider that hosts the instance.
`region`	`string`	yes	Region the instance is deployed in.
`os_type`	`string`	yes	Operating system of the instance: `linux`, `windows`, `android` or `macos`.
`status`	`string`	yes	Lifecycle phase of the instance: `pending`, `provisioning`, `running`, `stopped` or `terminated`. Allowed values: see the table below, RuntimeInstanceSummary.status values.
`desired_status`	`string`	yes	Lifecycle phase the instance is being driven toward: `running`, `stopped` or `terminated`. Allowed values: `"running"` — The instance should be running; `"stopped"` — The instance should be stopped; `"terminated"` — The instance should be deleted. (enum table)
`connectivity`	`string`	yes	Reachability of the instance's agent: `unknown`, `online` or `offline`. Allowed values: `"unknown"` — Reachability has not been determined; `"online"` — The instance's agent is connected; `"offline"` — The instance's agent is not connected. (enum table)
`error_code`	`string`	no	Stable code describing a failure or degraded state reported with a lifecycle result, for example `quota_exceeded`, `capacity_pending`, `provision_failed` or `stop_failed`. Raw provider errors are never exported.
`ms_connection_status`	`string`	yes	Status of the instance's message-channel connection: `unknown`, `connecting`, `connected`, `reconnecting`, `disconnected` or `failed`. It is reported independently of connectivity and is `unknown` while the instance is stopped or terminated, or has not reported recently.
`image_id`	`string`	no	ID of the platform image the instance runs.
`image_version_id`	`string`	no	ID of the platform image version the instance runs.
`image_version`	`string`	no	Version label of the platform image the instance runs.
`image_ref`	`string`	no	Pinned public image reference. Provider configuration is never included.
`model_primary`	`string`	no	Primary model configured for the instance.
`models`	`array<string>`	no	Models configured for the instance.
`llm`	RuntimeLLMView	no	Model providers and models supplied for the instance, with API keys removed. Nullable.
`hosting_type`	`string`	no	Where the instance is hosted: `cloud` or `selfhosted`.
`cloud_provider`	`string`	no	`agentbay`, `beeos`, or empty when self-hosted.
`image_slot`	`string`	no	Variant trait. Key that selects the execution image for the instance. Not a container repository name.
`worker_image_id`	`string`	no	Variant trait. AgentBay worker image. Never the platform `image_id`.
`model_catalog`	`string`	no	Variant trait. `served` when Cloud answers model-list and reasoning-level requests, `none` when it answers neither. Empty and unknown values behave as `none`.
`billing_slot`	`string`	no	Variant trait. Key into the monthly fee table that prices the instance.
`icon_key`	`string`	no	Variant trait. UI icon selector. Clients must not derive it from `harness`.
`device_control`	`boolean`	yes	Variant trait. Whether the instance accepts device-control commands. False means those commands are rejected.
`runtime_profile`	`string`	no	Variant trait. Profile of the agent runtime the instance uses. Known values are `openclaw`, `hermes` and `beeos-browser`.
`free_plan`	`boolean`	yes	Variant trait. Whether the free plan allows the instance's variant. False means the free plan does not allow it.
`resource_version`	`integer`	yes	Version of the instance record, starting at 1. Send it in the `If-Match` header of write requests so concurrent changes are detected.
`has_ever_run`	`boolean`	yes	Whether the instance has ever reached the running state. False means it has never delivered a running service.
`created_at`	`string`	yes	Time the instance was created, as an RFC 3339 UTC timestamp.
`updated_at`	`string`	yes	Time the instance was last updated, as an RFC 3339 UTC timestamp.
`capabilities`	`object`	yes	Capabilities declared for the instance when it was provisioned, as flags such as `computer`, `mobile`, `device` and `terminal`. An empty object means none were declared.
`capabilities.computer`	`boolean`	no	—
`capabilities.mobile`	`boolean`	no	—
`capabilities.device`	`boolean`	no	—
`capabilities.terminal`	`boolean`	no	—

RuntimeInstanceSummary.status values

Value	Meaning
`"pending"`	The instance was created and is waiting to be provisioned.
`"provisioning"`	The instance is being provisioned or started.
`"running"`	The instance is running.
`"stopped"`	The instance is stopped and can be started again.
`"terminated"`	The instance was deleted and cannot be used again.

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

RuntimeOperationSummary

Field	Type	Required	Description
`id`	`string`	yes	Unique ID of the operation.
`kind`	`string`	yes	Kind of operation: `create`, `start`, `stop`, `delete` or `image_upgrade`. Allowed values: see the table below, RuntimeOperationSummary.kind values.
`phase`	`string`	yes	Phase of the operation: `intent`, `reserved`, `admitted`, `provisioning`, `running`, `cleanup_pending`, `failed`, `stop_pending`, `stopped`, `delete_pending`, `deleted`, `upgrade_pending` or `rollback_pending`. It describes durable work, not observed instance health. Allowed values: see the table below, RuntimeOperationSummary.phase values.
`error_code`	`string`	no	Stable failure code, the same value as the instance `error_code`. Raw provider errors are never exported.

RuntimeOperationSummary.kind values

Value	Meaning
`"create"`	Create the instance.
`"start"`	Start a stopped instance.
`"stop"`	Stop the instance.
`"delete"`	Delete the instance.
`"image_upgrade"`	Upgrade the instance to another platform image.

RuntimeOperationSummary.phase values

Value	Meaning
`"intent"`	The create request was recorded and nothing is reserved yet.
`"reserved"`	The create request was accepted and its resources are reserved.
`"admitted"`	The create request was admitted and is waiting to be provisioned.
`"provisioning"`	The instance is being provisioned or started.
`"running"`	Final phase of a successful create, start or image upgrade.
`"cleanup_pending"`	A create failed and the resources it reserved are being cleaned up.
`"failed"`	Final phase of a failed operation. See `error_code`.
`"stop_pending"`	The instance is being stopped.
`"stopped"`	Final phase of a successful stop.
`"delete_pending"`	The instance is being deleted.
`"deleted"`	Final phase of a successful delete.
`"upgrade_pending"`	The image upgrade is being applied.
`"rollback_pending"`	The image upgrade failed and the instance is being rolled back to its previous image.

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.

TerminalTicketClaims

Field	Type	Required	Description
`iss`	`string`	yes	Issuer of the ticket.
`aud`	`string`	yes	Audience the ticket is intended for: the terminal service.
`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.
`instance_id`	`string`	yes	ID of the instance the terminal belongs to.
`platform_agent_id`	`string`	yes	ID of the agent the terminal session is for, the `platformAgentId` of the request.
`client_id`	`string`	yes	ID generated for this terminal client connection.
`conversation_id`	`string`	no	ID of the conversation the terminal is attached to. Present only when the request sent `conversationId`.
`resume_terminal_id`	`string`	no	ID of the terminal to resume. Present only when the request sent `resumeTerminalId`.
`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.

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

Create an instance with instances.create. The response is 202: creation has started, the instance is not ready yet.
Poll instances.getStatus until the instance is running.
Use the instance: instances.exec runs a command, instances.createTerminalSession and instances.createCanvasSession open sessions, and instances.getConnectURL and instances.getStreamURL return URLs.
Change it with instances.update (send the current version in If-Match), stop and start it with instances.stop and instances.start, or upgrade it with instances.upgrade and follow the job with instances.getUpgrade.
Remove it with instances.delete.

Methods

Method	HTTP	Summary
instances.list	`GET /v1/instances`	List instances
instances.create	`POST /v1/instances`	Create an instance
instances.get	`GET /v1/instances/{instanceId}`	Get an instance
instances.update	`PATCH /v1/instances/{instanceId}`	Update an instance
instances.delete	`DELETE /v1/instances/{instanceId}`	Delete an instance
instances.createCanvasSession	`POST /v1/instances/{instanceId}/canvas-sessions`	Create a canvas session
instances.getConnectURL	`GET /v1/instances/{instanceId}/connect-url`	Get an instance connect URL
instances.exec	`POST /v1/instances/{instanceId}/exec`	Run a command in an instance
instances.start	`POST /v1/instances/{instanceId}/start`	Start an instance
instances.getStatus	`GET /v1/instances/{instanceId}/status`	Get instance status
instances.stop	`POST /v1/instances/{instanceId}/stop`	Stop an instance
instances.getStreamURL	`GET /v1/instances/{instanceId}/stream-url`	Get an instance stream URL
instances.createTerminalSession	`POST /v1/instances/{instanceId}/terminal-sessions`	Create a terminal session
instances.upgrade	`POST /v1/instances/{instanceId}/upgrade`	Start an instance upgrade
instances.getUpgrade	`GET /v1/instances/{instanceId}/upgrades/{jobId}`	Get an instance upgrade

instances.list

GET /v1/instances · Operation ID listInstances

List instances

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.list`	`list(query?: Models.ListInstancesQuery): Promise<Models.ListInstancesResponse>`
Python	`cloud.instances.list`	`def list(self, options: ListInstancesOptions \| None = None) -> InstancePage`
Go	`cloud.Instances.List`	`func (r *InstancesResource) List(ctx context.Context, options ListInstancesOptions) (InstancePage, error)`

Parameters

Parameter	In	Type	Required	Description
`page`	query	`integer`	no	1-based page number, from 1 to 1000000. Defaults to 1. Constraints: `minimum=1`, `maximum=1000000`.
`page_size`	query	`integer`	no	Number of instances per page, from 1 to 100. Defaults to 20. Constraints: `minimum=1`, `maximum=100`.
`status`	query	`string`	no	Return only instances in this lifecycle phase: `pending`, `provisioning`, `running`, `stopped` or `terminated`. When omitted, terminated instances are not returned.
`provider_id`	query	`string`	no	Return only instances hosted by this provider, at most 128 characters.
`harness`	query	`string`	no	Return only instances that run this product harness (for example `openclaw`), at most 128 characters.
`cluster_id`	query	`string`	no	Return only instances deployed to this cluster, at most 128 characters.
`search`	query	`string`	no	Case-insensitive substring match on the instance name or ID, at most 200 characters.

Response

200 Tenant-scoped result · application/json · Schema: InstancePage

Field	Type	Required	Description
`data`	array<InstanceSummary>	yes	Instances on this page, newest first.
`total`	`integer`	yes	Total number of instances that match the filters, across all pages.

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.instances.list();
console.log(result);

instances.create

POST /v1/instances · Operation ID instanceCreate

Create an instance

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.create`	`create(input: Models.CreateServerInstanceInput, idempotencyKey: string): Promise<Models.InstanceCreateResponse>`
Python	`cloud.instances.create`	`def create(self, input: CreateServerInstanceInput, options: InstanceCreateOptions) -> RuntimeInstanceResult`
Go	`cloud.Instances.Create`	`func (r *InstancesResource) Create(ctx context.Context, input CreateServerInstanceInput, options InstanceCreateOptions) (RuntimeInstanceResult, error)`

Parameters

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	`string`	yes	Key that makes the request safe to retry, 1 to 256 bytes without leading or trailing whitespace. Repeating a request with the same key and body replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`.

Request body

application/json · required · Schema: CreateServerInstanceInput

Field	Type	Required	Description
`name`	`string`	yes	Display name of the instance, 1 to 128 bytes, without leading or trailing whitespace.
`variant_id`	`string`	no	ID of the catalog variant to create the instance from, at most 128 characters. See the instance template catalog for available variants. An unknown ID returns 404 `variant_not_found`.
`harness`	`string`	no	Harness to run in the instance. Only `openclaw` is accepted. Allowed values: `"openclaw"` — The OpenClaw agent runtime.
`llm`	RuntimeLLM	no	Model providers and models the instance uses. Required when the variant or harness needs caller-supplied models; omit it for variants that supply their own models. Provider API keys are write-only. Nullable.

Response

202 · application/json · Schema: RuntimeInstanceResult

Field	Type	Required	Description
`data`	RuntimeInstanceSummary	yes	The instance as of this response.
`operation`	RuntimeOperationSummary	yes	Lifecycle operation that this response reports on.

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.instances.create({ name: "example" }, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

instances.get

GET /v1/instances/{instanceId} · Operation ID getInstance

Get an instance

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.get`	`get(id: string): Promise<Models.GetInstanceResponse>`
Python	`cloud.instances.get`	`def get(self, instance_id: str) -> RuntimeInstanceResult`
Go	`cloud.Instances.Get`	`func (r *InstancesResource) Get(ctx context.Context, instanceId string) (RuntimeInstanceResult, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.

Response

200 · application/json · Schema: RuntimeInstanceResult

Field	Type	Required	Description
`data`	RuntimeInstanceSummary	yes	The instance as of this response.
`operation`	RuntimeOperationSummary	yes	Lifecycle operation that this response reports on.

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.instances.get("instance_123");
console.log(result);

instances.update

PATCH /v1/instances/{instanceId} · Operation ID updateInstanceMetadata

Update an instance

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.update`	`update(instanceId: string, input: Models.UpdateServerInstanceInput, version: number): Promise<Models.UpdateInstanceMetadataResponse>`
Python	`cloud.instances.update`	`def update(self, instance_id: str, input: UpdateServerInstanceInput, options: UpdateInstanceMetadataOptions) -> UpdateInstanceMetadataResponse`
Go	`cloud.Instances.Update`	`func (r *InstancesResource) Update(ctx context.Context, instanceId string, input UpdateServerInstanceInput, options UpdateInstanceMetadataOptions) (UpdateInstanceMetadataResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.
`If-Match`	header	`string`	yes	Version of the instance the request applies to: the `resource_version` of the representation you last read, optionally in quotes. A stale version returns 412 `version_mismatch`; a missing or invalid one returns 428 `precondition_required`.

Request body

application/json · required · Schema: UpdateServerInstanceInput

Field	Type	Required	Description
`name`	`string`	no	New display name, 1 to 128 characters, without leading or trailing whitespace. Send `name`, `llm` or both.
`llm`	RuntimeLLM	no	Replacement model providers and models. It replaces the whole existing llm block. Provider API keys are write-only. When `name` is also sent, the llm block is replaced first.

Response

200 · application/json

Field	Type	Required	Description
`data`	RuntimeInstanceSummary	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.instances.update("instance_123", {}, 1);
console.log(result);

instances.delete

DELETE /v1/instances/{instanceId} · Operation ID deleteInstance

Delete an instance

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.delete`	`delete(id: string, idempotencyKey: string, version: number): Promise<Models.DeleteInstanceResponse>`
Python	`cloud.instances.delete`	`def delete(self, instance_id: str, options: DeleteInstanceOptions) -> RuntimeInstanceResult`
Go	`cloud.Instances.Delete`	`func (r *InstancesResource) Delete(ctx context.Context, instanceId string, options DeleteInstanceOptions) (RuntimeInstanceResult, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.
`Idempotency-Key`	header	`string`	yes	Key that makes the request safe to retry, 1 to 256 bytes without leading or trailing whitespace. Repeating a request with the same key and body replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`.
`If-Match`	header	`string`	yes	Version of the instance the request applies to: the `resource_version` of the representation you last read, optionally in quotes. A stale version returns 412 `version_mismatch`; a missing or invalid one returns 428 `precondition_required`.

Response

202 · application/json · Schema: RuntimeInstanceResult

Field	Type	Required	Description
`data`	RuntimeInstanceSummary	yes	The instance as of this response.
`operation`	RuntimeOperationSummary	yes	Lifecycle operation that this response reports on.

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.instances.delete("instance_123", "YOUR_IDEMPOTENCY_KEY", 1);
console.log(result);

instances.createCanvasSession

POST /v1/instances/{instanceId}/canvas-sessions · Operation ID createCanvasSession

Create a canvas session

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.createCanvasSession`	`createCanvasSession(instanceId: string, input: Models.CreateCanvasSessionRequest): Promise<Models.CreateCanvasSessionResponse>`
Python	`cloud.instances.create_canvas_session`	`def create_canvas_session(self, instance_id: str, input: CreateCanvasSessionRequest) -> CanvasSessionDocument`
Go	`cloud.Instances.CreateCanvasSession`	`func (r *InstancesResource) CreateCanvasSession(ctx context.Context, instanceId string, input CreateCanvasSessionRequest) (CanvasSessionDocument, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.

Request body

application/json · required

Field	Type	Required	Description
`platformAgentId`	`string`	yes	ID of the agent the canvas session is for, as a UUID. Constraints: `format=uuid`.
`conversationId`	`string`	yes	ID of the conversation the canvas belongs to, as a UUID. Constraints: `format=uuid`.
`canvasId`	`string`	no	Opaque Canvas/A2UI surface identifier; not a UUID. Constraints: `minLength=1`, `maxLength=128`, `pattern=^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`.

Response

201 Single-use RS256 canvas relay ticket · application/json · Schema: 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.

Errors

Status	Schema	Description
400	ErrorResponse	Cloud Server error
401	ErrorResponse	Cloud Server error
404	ErrorResponse	Cloud Server error
429	ErrorResponse	Cloud Server error
5XX	ErrorResponse	Cloud Server error
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.instances.createCanvasSession("instance_123", {
  platformAgentId: "00000000-0000-4000-8000-000000000000",
  conversationId: "00000000-0000-4000-8000-000000000000"
});
console.log(result);

instances.getConnectURL

GET /v1/instances/{instanceId}/connect-url · Operation ID getInstanceConnectURL

Get an instance connect URL

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.getConnectURL`	`getConnectURL(instanceId: string, query?: Models.GetInstanceConnectURLQuery): Promise<Models.GetInstanceConnectURLResponse>`
Python	`cloud.instances.get_connect_url`	`def get_connect_url(self, instance_id: str, options: GetInstanceConnectURLOptions \| None = None) -> ConnectURLResponse`
Go	`cloud.Instances.GetConnectURL`	`func (r *InstancesResource) GetConnectURL(ctx context.Context, instanceId string, options GetInstanceConnectURLOptions) (ConnectURLResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.
`service`	query	`string`	no	Service to connect to: `browser` for a browser viewer or `acp` for an agent connection. Required.
`client_id`	query	`string`	no	ID you choose for the viewing client session, 1 to 128 characters (letters, digits, `_`, `.`, `:` and `-`, starting with a letter or digit). Required when `service` is `browser`; not accepted for `acp`.
`role`	query	`string`	no	Access role to request: `viewer` or `controller`. Required when `service` is `browser`; not accepted for `acp`.
`generation`	query	`string`	no	Browser generation the access grant must be bound to, in the same format as `client_id`. The request fails when the browser's current generation differs. Only for `browser`.

Response

200 · application/json · Schema: ConnectURLResponse

Field	Type	Required	Description
`data`	`object`	yes	Connection details for the requested service.
`data.url`	`string`	yes	URL to connect to. For `browser` it is the browser viewer URL; for `acp` it is a WebSocket URL that already carries the access ticket as a query parameter.
`data.mode`	`string`	yes	Connection mode: `browser-runtime` for `browser`, `service-websocket` for `acp`. Allowed values: `"browser-runtime"` — A browser viewer session; connect with `url` and `token`; `"service-websocket"` — A WebSocket connection to an agent service; `url` already carries the access ticket. (enum table)
`data.token`	`string`	yes	Short-lived access token for the browser viewer. Not returned for `acp`.
`data.service`	`string`	yes	Service the URL connects to: `browser` or `acp`. Allowed values: `"browser"` — The browser viewer; `"acp"` — The agent connection over WebSocket. (enum table)
`data.connectivity`	`string`	yes	Reachability of the instance's agent: `unknown`, `online` or `offline`. Allowed values: `"unknown"` — Reachability has not been determined; `"online"` — The instance's agent is connected; `"offline"` — The instance's agent is not connected. (enum table)
`data.stream_session_id`	`string`	yes	ID of the viewing client session, the `client_id` sent in the request. Not returned for `acp`.
`data.browser`	`object`	no	Browser access grant. Returned only for `browser`.
`data.browser.grant_id`	`string`	yes	ID of the browser access grant.
`data.browser.generation`	`string`	yes	Generation of the browser the grant is bound to. When `generation` was sent in the request, it equals that value.
`data.browser.expires_at`	`string`	yes	Time the access grant expires, in Unix milliseconds.
`data.browser.role`	`string`	yes	Access role of the grant: `viewer` or `controller`. Allowed values: `"viewer"` — Can watch the browser but not control it; `"controller"` — Can watch and control the browser. (enum table)

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.instances.getConnectURL("instance_123");
console.log(result);

instances.exec

POST /v1/instances/{instanceId}/exec · Operation ID execInstance

Run a command in an instance

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.exec`	`exec(instanceId: string, input: Models.ExecInstanceRequest): Promise<Models.ExecInstanceResponse>`
Python	`cloud.instances.exec`	`def exec(self, instance_id: str, input: ExecInstanceRequest) -> RuntimeExecResult`
Go	`cloud.Instances.Exec`	`func (r *InstancesResource) Exec(ctx context.Context, instanceId string, input ExecInstanceRequest) (RuntimeExecResult, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.

Request body

application/json · required

Field	Type	Required	Description
`argv`	`array<string>`	yes	Program and arguments as an argument vector; it is never passed through a shell. 1 to 64 entries of at most 4096 bytes each and 16 KiB in total. The first entry must not be blank.
`timeout_seconds`	`integer`	no	Maximum run time in seconds, from 1 to 30.

Response

200 · application/json · Schema: RuntimeExecResult

Field	Type	Required	Description
`exit_code`	`integer`	yes	Exit code of the command.
`stdout`	`string`	yes	Standard output of the command, at most 64 KiB.
`stderr`	`string`	yes	Standard error of the command, at most 64 KiB.
`truncated`	`boolean`	yes	Whether the output was truncated.

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.instances.exec("instance_123", { argv: ["example_argv"] });
console.log(result);

instances.start

POST /v1/instances/{instanceId}/start · Operation ID startInstance

Start an instance

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.start`	`start(instanceId: string, idempotencyKey: string, version: number): Promise<Models.StartInstanceResponse>`
Python	`cloud.instances.start`	`def start(self, instance_id: str, options: StartInstanceOptions) -> RuntimeInstanceResult`
Go	`cloud.Instances.Start`	`func (r *InstancesResource) Start(ctx context.Context, instanceId string, options StartInstanceOptions) (RuntimeInstanceResult, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.
`Idempotency-Key`	header	`string`	yes	Key that makes the request safe to retry, 1 to 256 bytes without leading or trailing whitespace. Repeating a request with the same key and body replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`.
`If-Match`	header	`string`	yes	Version of the instance the request applies to: the `resource_version` of the representation you last read, optionally in quotes. A stale version returns 412 `version_mismatch`; a missing or invalid one returns 428 `precondition_required`.

Response

202 · application/json · Schema: RuntimeInstanceResult

Field	Type	Required	Description
`data`	RuntimeInstanceSummary	yes	The instance as of this response.
`operation`	RuntimeOperationSummary	yes	Lifecycle operation that this response reports on.

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.instances.start("instance_123", "YOUR_IDEMPOTENCY_KEY", 1);
console.log(result);

instances.getStatus

GET /v1/instances/{instanceId}/status · Operation ID getInstanceStatus

Get instance status

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.getStatus`	`getStatus(id: string): Promise<Models.GetInstanceStatusResponse>`
Python	`cloud.instances.get_status`	`def get_status(self, instance_id: str) -> RuntimeInstanceStatusResult`
Go	`cloud.Instances.GetStatus`	`func (r *InstancesResource) GetStatus(ctx context.Context, instanceId string) (RuntimeInstanceStatusResult, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.

Response

200 · application/json · Schema: RuntimeInstanceStatusResult

Field	Type	Required	Description
`data`	`object`	yes	Current status of the instance.
`data.id`	`string`	yes	Unique ID of the instance.
`data.name`	`string`	yes	Display name of the instance.
`data.status`	`string`	yes	Lifecycle phase of the instance: `pending`, `provisioning`, `running`, `stopped` or `terminated`. Allowed values: see RuntimeInstanceStatusResult.data.status values.
`data.desired_status`	`string`	yes	Lifecycle phase the instance is being driven toward: `running`, `stopped` or `terminated`. Allowed values: `"running"` — The instance should be running; `"stopped"` — The instance should be stopped; `"terminated"` — The instance should be deleted. (enum table)
`data.connectivity`	`string`	yes	Reachability of the instance's agent: `unknown`, `online` or `offline`. Allowed values: `"unknown"` — Reachability has not been determined; `"online"` — The instance's agent is connected; `"offline"` — The instance's agent is not connected. (enum table)
`operation`	RuntimeOperationSummary	yes	Lifecycle operation that this response reports on.

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.instances.getStatus("instance_123");
console.log(result);

instances.stop

POST /v1/instances/{instanceId}/stop · Operation ID stopInstance

Stop an instance

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.stop`	`stop(id: string, idempotencyKey: string, version: number): Promise<Models.StopInstanceResponse>`
Python	`cloud.instances.stop`	`def stop(self, instance_id: str, options: StopInstanceOptions) -> RuntimeInstanceResult`
Go	`cloud.Instances.Stop`	`func (r *InstancesResource) Stop(ctx context.Context, instanceId string, options StopInstanceOptions) (RuntimeInstanceResult, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.
`Idempotency-Key`	header	`string`	yes	Key that makes the request safe to retry, 1 to 256 bytes without leading or trailing whitespace. Repeating a request with the same key and body replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`.
`If-Match`	header	`string`	yes	Version of the instance the request applies to: the `resource_version` of the representation you last read, optionally in quotes. A stale version returns 412 `version_mismatch`; a missing or invalid one returns 428 `precondition_required`.

Response

202 · application/json · Schema: RuntimeInstanceResult

Field	Type	Required	Description
`data`	RuntimeInstanceSummary	yes	The instance as of this response.
`operation`	RuntimeOperationSummary	yes	Lifecycle operation that this response reports on.

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.instances.stop("instance_123", "YOUR_IDEMPOTENCY_KEY", 1);
console.log(result);

instances.getStreamURL

GET /v1/instances/{instanceId}/stream-url · Operation ID getInstanceStreamURL

Get an instance stream URL

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.getStreamURL`	`getStreamURL(instanceId: string, query?: Models.GetInstanceStreamURLQuery): Promise<Models.GetInstanceStreamURLResponse>`
Python	`cloud.instances.get_stream_url`	`def get_stream_url(self, instance_id: str, options: GetInstanceStreamURLOptions \| None = None) -> GetInstanceStreamURLResponse`
Go	`cloud.Instances.GetStreamURL`	`func (r *InstancesResource) GetStreamURL(ctx context.Context, instanceId string, options GetInstanceStreamURLOptions) (GetInstanceStreamURLResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.
`viewportWidth`	query	`integer`	no	Viewport width in pixels, greater than 0 and below 100000.
`viewportHeight`	query	`integer`	no	Viewport height in pixels, greater than 0 and below 100000.
`dpr`	query	`number`	no	Device pixel ratio, greater than 0 and below 16.

Response

200 · application/json

Field	Type	Required	Description
`data`	JSONValue	yes	A genuinely open JSON value (provider/plugin parameters or arbitrary metadata). 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.instances.getStreamURL("instance_123");
console.log(result);

instances.createTerminalSession

POST /v1/instances/{instanceId}/terminal-sessions · Operation ID createTerminalSession

Create a terminal session

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.createTerminalSession`	`createTerminalSession(instanceId: string, input: Models.CreateTerminalSessionRequest): Promise<Models.CreateTerminalSessionResponse>`
Python	`cloud.instances.create_terminal_session`	`def create_terminal_session(self, instance_id: str, input: CreateTerminalSessionRequest) -> TerminalSessionDocument`
Go	`cloud.Instances.CreateTerminalSession`	`func (r *InstancesResource) CreateTerminalSession(ctx context.Context, instanceId string, input CreateTerminalSessionRequest) (TerminalSessionDocument, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.

Request body

application/json · required

Field	Type	Required	Description
`platformAgentId`	`string`	yes	ID of the agent the terminal session is for, as a UUID. Constraints: `format=uuid`.
`conversationId`	`string`	no	ID of the conversation to attach the terminal to, as a UUID. Optional. Constraints: `format=uuid`.
`resumeTerminalId`	`string`	no	ID of an existing terminal to resume, as a UUID. Optional. Constraints: `format=uuid`.

Response

201 Single-use RS256 terminal ticket · application/json · Schema: TerminalSessionDocument

Field	Type	Required	Description
`transport`	`string`	yes	How the ticket connects: always `service-websocket`.
`protocolVersion`	`integer`	yes	Version of the ticket protocol. Currently 1.
`header`	RealtimeTicketHeader	yes	Header of the signed ticket.
`websocketUrl`	`string`	yes	WebSocket URL to open the terminal connection on. It already carries the ticket as a query parameter.
`ticket`	`string`	yes	Signed single-use ticket (a JWT) that authorizes one terminal 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`	TerminalTicketClaims	yes	Claims contained in the signed ticket.

Errors

Status	Schema	Description
400	ErrorResponse	Cloud Server error
401	ErrorResponse	Cloud Server error
404	ErrorResponse	Cloud Server error
429	ErrorResponse	Cloud Server error
5XX	ErrorResponse	Cloud Server error
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.instances.createTerminalSession("instance_123", { platformAgentId: "00000000-0000-4000-8000-000000000000" });
console.log(result);

instances.upgrade

POST /v1/instances/{instanceId}/upgrade · Operation ID upgradeInstance

Start an instance upgrade

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.upgrade`	`upgrade(instanceId: string, input: Models.UpgradeInstanceRequest, idempotencyKey: string): Promise<Models.UpgradeInstanceResponse>`
Python	`cloud.instances.upgrade`	`def upgrade(self, instance_id: str, input: UpgradeInstanceRequest, options: UpgradeInstanceOptions) -> RuntimeUpgradeJob`
Go	`cloud.Instances.Upgrade`	`func (r *InstancesResource) Upgrade(ctx context.Context, instanceId string, input UpgradeInstanceRequest, options UpgradeInstanceOptions) (RuntimeUpgradeJob, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.
`Idempotency-Key`	header	`string`	yes	Key that makes the request safe to retry, 1 to 256 bytes without leading or trailing whitespace. Repeating a request with the same key and body replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`.

Request body

application/json · required

Field	Type	Required	Description
`image_id`	`string`	no	ID of the published platform image to upgrade to. Send at least one of `image_id`, `image_ref` and `target_version`; they select among published platform images only.
`image_ref`	`string`	no	Pinned public reference of the published platform image to upgrade to.
`target_version`	`string`	no	Version of the published platform image to upgrade to.

Response

202 · application/json · Schema: RuntimeUpgradeJob

Field	Type	Required	Description
`job_id`	`string`	yes	Unique ID of the upgrade job.
`image_version_id`	`string`	no	—
`instance_id`	`string`	yes	ID of the instance being upgraded.
`status`	`string`	yes	Status of the job: `upgrade_pending`, `rollback_pending`, `failed` or `succeeded`. Allowed values: `"upgrade_pending"` — The image upgrade is being applied; `"rollback_pending"` — The image upgrade failed and the instance is being rolled back to its previous image; `"failed"` — The image upgrade failed. See `error`; `"succeeded"` — The image upgrade finished and the instance runs the target version. (enum table)
`target`	`string`	yes	Image version the instance is being upgraded to.
`created_at`	`string`	yes	Time the job was created, as an RFC 3339 UTC timestamp.
`completed_at`	`string`	no	Time the job finished, as an RFC 3339 UTC timestamp. Omitted while the job is not finished. Nullable.
`error`	`string`	no	Stable failure code. Omitted unless the job failed. 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.instances.upgrade("instance_123", {}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

instances.getUpgrade

GET /v1/instances/{instanceId}/upgrades/{jobId} · Operation ID getInstanceUpgrade

Get an instance upgrade

SDK methods

Language	Method	Signature
TypeScript	`cloud.instances.getUpgrade`	`getUpgrade(instanceId: string, jobId: string): Promise<Models.GetInstanceUpgradeResponse>`
Python	`cloud.instances.get_upgrade`	`def get_upgrade(self, instance_id: str, job_id: str) -> RuntimeUpgradeJob`
Go	`cloud.Instances.GetUpgrade`	`func (r *InstancesResource) GetUpgrade(ctx context.Context, instanceId string, jobId string) (RuntimeUpgradeJob, error)`

Parameters

Parameter	In	Type	Required	Description
`instanceId`	path	`string`	yes	ID of the instance.
`jobId`	path	`string`	yes	ID of the upgrade job, the `job_id` returned when the upgrade was started.

Response

200 · application/json · Schema: RuntimeUpgradeJob

Field	Type	Required	Description
`job_id`	`string`	yes	Unique ID of the upgrade job.
`image_version_id`	`string`	no	—
`instance_id`	`string`	yes	ID of the instance being upgraded.
`status`	`string`	yes	Status of the job: `upgrade_pending`, `rollback_pending`, `failed` or `succeeded`. Allowed values: `"upgrade_pending"` — The image upgrade is being applied; `"rollback_pending"` — The image upgrade failed and the instance is being rolled back to its previous image; `"failed"` — The image upgrade failed. See `error`; `"succeeded"` — The image upgrade finished and the instance runs the target version. (enum table)
`target`	`string`	yes	Image version the instance is being upgraded to.
`created_at`	`string`	yes	Time the job was created, as an RFC 3339 UTC timestamp.
`completed_at`	`string`	no	Time the job finished, as an RFC 3339 UTC timestamp. Omitted while the job is not finished. Nullable.
`error`	`string`	no	Stable failure code. Omitted unless the job failed. 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.instances.getUpgrade("instance_123", "job_123");
console.log(result);

BeeOS CloudBack to documentation