Live view

Watch a screen in a browser, or show it to a person.

Open the live view (WebSocket)

GET

https://api.trykubi.com/v1

/screens/{screen_id}/viewer

No key needed. Answers within 5 s.

The stream a live-view link's page opens: a WebSocket carrying VNC (RFB 3.8) frames, for noVNC or any RFB client. The link's ticket (vt_..., from the #t= part of its URL) is the credential: send Sec-WebSocket-Protocol: kubi.v1, <ticket>, never the ticket in the URL. The reply picks kubi.v1. A ticket opens one socket, within 60 s of its link being made. View-only sessions drop keyboard, mouse and clipboard; an interactive one passes them only while its person holds the screen. At most 3 live views per screen. The socket closes when the session ends, the screen stops or restarts, or the credential that made the link is revoked.

Open the live view (WebSocket) › path Parameters

screen_id

string · maxLength: 24 · pattern: ^scr_[0-9a-z]{20}$ · required

Screen id (scr_...).

Open the live view (WebSocket) › Headers

Sec-WebSocket-Protocol

string · maxLength: 64 · pattern: ^kubi\.v1, ?vt_[A-Za… · required

kubi.v1 and the link's ticket, comma separated.

Open the live view (WebSocket) › Responses

Switching protocols to the WebSocket.

No data returned

Get a live-view link

POST

https://api.trykubi.com/v1

/screens/{screen_id}/viewer

Bearer (API key)

Needs the read permission. Answers within 2 s.

A link to watch the screen live in a browser. Open it within 60 s; single use. API keys and apps get view-only links (to show a person what is happening) whose session ends after 60 minutes; a signed-in person gets an interactive one, where Take control turns on the mouse and keyboard. While a person has control, calls that look at or act on the screen get 409 CONTROL_HELD, and the person's input makes older screenshots stale. Revoking the credential that minted a link closes its session.

Get a live-view link › path Parameters

screen_id

string · maxLength: 24 · pattern: ^scr_[0-9a-z]{20}$ · required

Screen id (scr_...).

Get a live-view link › Headers

Idempotency-Key

string · minLength: 8 · maxLength: 255 · pattern: ^[ -~]+$

Any unique string, ideally a UUIDv7; the SDK and MCP always send one. A retry with the same key and body gets the stored answer instead of running twice (kept 24 h for screens and power, 10 minutes for actions and commands). Stored once execution began: 2xx, 500 and 504. Never stored when outcome is not_applied (400, 401, 403, 404, 409, 415, 422, 429), so the same key can be retried after a conflict or a rate limit. Replays of runActions keep per-action results and shot metadata only, capture a fresh screenshot and carry Idempotent-Replayed: true. Same key, different body: 422 IDEMPOTENCY_KEY_REUSED. Same key still running: 409 IDEMPOTENCY_KEY_IN_USE.

Kubi-Run

string · maxLength: 100 · pattern: ^[ -~]{1,100}$

Optional label that groups calls into one run in the screen's history. It is only a label and never locks the screen. The SDK fills it from KUBI_RUN, else Claude Code's CLAUDE_CODE_SESSION_ID, else one id per client it creates.

Get a live-view link › Request Body optional

ViewerCreate

mode

string · enum · maxLength: 12

interactive needs a person (cookie). Agents get view links.

Enum values:

view

interactive

Default: view

Get a live-view link › Responses

Created.

`expires_at`: open the link by then. `session_expires_at`: the live session ends then (60 minutes for agent-minted links). Revoking the credential that minted it closes it.

Viewer

url

string · uri · maxLength: 500 · required

Open within 60 s. Single use. The ticket rides in the URL fragment.

required

expires_at

string · date-time · maxLength: 40 · required

session_expires_at

string · date-time · maxLength: 40 · required

Clipboard History