Screens
Create, list, rename, power and delete screens.
List screens
Needs the read permission. Answers within 2 s.
Screens in your organization that this credential may see, newest first.
query Parameters
limitPage size, 1 to 100.
after^[A-Za-z0-9_-]+$Opaque cursor from the previous page's next.
label^[a-z0-9_.-]{1,40}:.…Filter by key:value.
stateFilter by power state.
kindOnly persistent or only disposable screens.
persistent: on the monthly subscription, one price per screen, running or stopped; kept until deleted, and a delete can be undone for 7 days. disposable: paid from usage credit for the time it runs, charged per billing step as each step starts; it can carry an end time, is deleted 7 days after it stops unless started again, and a delete is final.
List screens › Responses
Success.
Create a screen
Needs the power permission. Answers within 5 s.
Creates a screen and starts it, blank or from template_id. Returns 202 with an operation; the screen is listed at once as provisioning. A persistent screen (the default) goes on the monthly bill: the prorated price for the rest of the month is invoiced first and the machine is made once it is paid; a card that declines or needs 3-D Secure fails the operation with PAYMENT_REQUIRED and a pay link; while the organization is on hold for an unpaid invoice, the call itself answers 402 PAYMENT_REQUIRED. A disposable screen is paid from usage credit, its first billing step at once; with no credit: 402 CREDIT_EXHAUSTED. ends_in_s gives a disposable screen an end time. A blank screen resumes a desktop the host booted ahead and is ready in seconds; one from a template boots its disk. Over the organization's screen cap (both kinds count): 402 QUOTA_EXCEEDED. No free machine: 409 NO_CAPACITY, nothing charged.
Headers
Idempotency-Key^[ -~]+$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.
Create a screen › Request Body optional
name^[a-z0-9][a-z0-9-]{0…Unique in the organization. Default: generated.
colorThe colour of the screen's cube, shown beside its name in the dashboard. Only for people telling screens apart; nothing else reads it. A new screen is green unless its create says otherwise.
Your own key-value tags. Filter lists with label=key:value.
kindpersistent: on the monthly subscription, one price per screen, running or stopped; kept until deleted, and a delete can be undone for 7 days. disposable: paid from usage credit for the time it runs, charged per billing step as each step starts; it can carry an end time, is deleted 7 days after it stops unless started again, and a delete is final.
template_id^tpl_[0-9a-z]{20}$Start from this template. Default: blank.
size^[a-z0-9-]{1,20}$Default: standard, the one size at launch. A size not sold in the screen's kind: INVALID_ARGUMENT.
ends_in_sDisposable only: delete it this many seconds after it is created. Default: no end time.
Create a screen › Responses
Accepted. Poll the operation (or getScreen).
id^op_[0-9a-z]{20}$ · requiredreconciling: the outcome is uncertain and we are checking the host. Not a failure; do not retry.
screen_id^scr_[0-9a-z]{20}$ · requiredcreated_atupdated_atGet a screen
Needs the read permission. Answers within 2 s.
State, health per capability and resources. Cheap: call it as often as you like within the rate limit.
path Parameters
screen_id^scr_[0-9a-z]{20}$ · requiredScreen id (scr_...).
Headers
Kubi-Run^[ -~]{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 screen › Responses
Success.
id^scr_[0-9a-z]{20}$ · requiredname^[a-z0-9][a-z0-9-]{0… · requiredkindpersistent: on the monthly subscription, one price per screen, running or stopped; kept until deleted, and a delete can be undone for 7 days. disposable: paid from usage credit for the time it runs, charged per billing step as each step starts; it can carry an end time, is deleted 7 days after it stops unless started again, and a delete is final.
The cube's colour (ScreenColor). New colours may appear: show an unknown one as green.
Your own key-value tags. Filter lists with label=key:value.
Power state. failed carries a state_reason. New values may appear.
imageThe image it was created from. One desktop image at launch.
sizeThe size it was sold as (standard, the one size at launch); resources says what it has.
One size at launch. Resize comes later.
regionEach capability on its own: a running VM can have a broken display. Host unreachable means unknown.
Whether a person has control of the screen.
incarnationGoes up when the machine restarts. Old screenshots and exec ids stop applying.
created_atupdated_atviewersLive views open on the screen right now, at most 3.
Rename, recolour or relabel a screen
Needs the power permission. Answers within 2 s.
Changes name, colour, labels or a disposable screen's end time. Nothing restarts.
path Parameters
screen_id^scr_[0-9a-z]{20}$ · requiredScreen id (scr_...).
Headers
Kubi-Run^[ -~]{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.
Rename, recolour or relabel a screen › Request Body
name^[a-z0-9][a-z0-9-]{0…colorThe colour of the screen's cube, shown beside its name in the dashboard. Only for people telling screens apart; nothing else reads it. A new screen is green unless its create says otherwise.
Your own key-value tags. Filter lists with label=key:value.
Rename, recolour or relabel a screen › Responses
Success.
id^scr_[0-9a-z]{20}$ · requiredname^[a-z0-9][a-z0-9-]{0… · requiredkindpersistent: on the monthly subscription, one price per screen, running or stopped; kept until deleted, and a delete can be undone for 7 days. disposable: paid from usage credit for the time it runs, charged per billing step as each step starts; it can carry an end time, is deleted 7 days after it stops unless started again, and a delete is final.
The cube's colour (ScreenColor). New colours may appear: show an unknown one as green.
Your own key-value tags. Filter lists with label=key:value.
Power state. failed carries a state_reason. New values may appear.
imageThe image it was created from. One desktop image at launch.
sizeThe size it was sold as (standard, the one size at launch); resources says what it has.
One size at launch. Resize comes later.
regionEach capability on its own: a running VM can have a broken display. Host unreachable means unknown.
Whether a person has control of the screen.
incarnationGoes up when the machine restarts. Old screenshots and exec ids stop applying.
created_atupdated_atviewersLive views open on the screen right now, at most 3.
Delete a screen
Needs the power permission. Answers within 5 s.
Stops the screen and deletes it. A persistent screen's disk is kept 7 days so a person can undo it in the dashboard, then destroyed; that soft delete is the guard. It leaves the bill at once, and the unused days are credited to the next invoice. A disposable screen's delete is final: its disk is destroyed at once and its metering stops. API keys need power; MCP clients can never delete. A repeat while it runs returns the same operation.
path Parameters
screen_id^scr_[0-9a-z]{20}$ · requiredScreen id (scr_...).
Headers
Kubi-Run^[ -~]{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.
Delete a screen › Responses
Accepted.
id^op_[0-9a-z]{20}$ · requiredreconciling: the outcome is uncertain and we are checking the host. Not a failure; do not retry.
screen_id^scr_[0-9a-z]{20}$ · requiredcreated_atupdated_atStart a screen
Needs the power permission. Answers within 5 s.
Start a stopped screen. Its disk is as you left it. Returns 202 and an operation. Already in the target state: 202 with an operation that succeeds at once.
path Parameters
screen_id^scr_[0-9a-z]{20}$ · requiredScreen id (scr_...).
Headers
Idempotency-Key^[ -~]+$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^[ -~]{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.
Start a screen › Responses
Accepted.
id^op_[0-9a-z]{20}$ · requiredreconciling: the outcome is uncertain and we are checking the host. Not a failure; do not retry.
screen_id^scr_[0-9a-z]{20}$ · requiredcreated_atupdated_atStop a screen
Needs the power permission. Answers within 5 s.
Shut the screen down gracefully. The disk is kept, so it stays on the bill. Returns 202 and an operation. Already in the target state: 202 with an operation that succeeds at once.
path Parameters
screen_id^scr_[0-9a-z]{20}$ · requiredScreen id (scr_...).
Headers
Idempotency-Key^[ -~]+$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^[ -~]{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.
Stop a screen › Responses
Accepted.
id^op_[0-9a-z]{20}$ · requiredreconciling: the outcome is uncertain and we are checking the host. Not a failure; do not retry.
screen_id^scr_[0-9a-z]{20}$ · requiredcreated_atupdated_atRestart a screen
Needs the power permission. Answers within 5 s.
Reboot the screen. The incarnation goes up, so old screenshots and exec ids stop applying. Returns 202 and an operation. Already in the target state: 202 with an operation that succeeds at once.
path Parameters
screen_id^scr_[0-9a-z]{20}$ · requiredScreen id (scr_...).
Headers
Idempotency-Key^[ -~]+$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^[ -~]{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.
Restart a screen › Responses
Accepted.
id^op_[0-9a-z]{20}$ · requiredreconciling: the outcome is uncertain and we are checking the host. Not a failure; do not retry.
screen_id^scr_[0-9a-z]{20}$ · requiredcreated_atupdated_atSwitch a screen's kind
Needs the power permission. Answers within 5 s.
Makes a disposable screen persistent or a persistent one disposable, with no restart. To persistent: it joins the monthly subscription with the prorated price invoiced first (PAYMENT_REQUIRED if the card fails), its end time goes and metering stops. To disposable: it leaves the subscription (the unused days are credited to the next invoice) and draws on credit from now (CREDIT_EXHAUSTED with none). Already that kind: 202 with an operation that succeeds at once.
path Parameters
screen_id^scr_[0-9a-z]{20}$ · requiredScreen id (scr_...).
Headers
Idempotency-Key^[ -~]+$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^[ -~]{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.
Switch a screen's kind › Request Body
kindpersistent: on the monthly subscription, one price per screen, running or stopped; kept until deleted, and a delete can be undone for 7 days. disposable: paid from usage credit for the time it runs, charged per billing step as each step starts; it can carry an end time, is deleted 7 days after it stops unless started again, and a delete is final.
Switch a screen's kind › Responses
Accepted.
id^op_[0-9a-z]{20}$ · requiredreconciling: the outcome is uncertain and we are checking the host. Not a failure; do not retry.
screen_id^scr_[0-9a-z]{20}$ · requiredcreated_atupdated_at