Snapshots
Saved states of a screen's disk, and reset to one of them or to how the screen started.
List snapshots
Needs the read permission. Answers within 2 s.
The screen's snapshots, newest first; at most 3.
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.
List snapshots › Responses
Success.
Snapshot a screen
Needs the power permission. Answers within 5 s.
Saves the screen's disk as it is now, as a point to reset to. A running screen keeps running: its writes are flushed first, and the snapshot holds what a sudden power cut would leave, never the screen's memory or its secrets. Returns 202 with an operation; the snapshot is listed at once as creating. Up to 3 per screen, included in the price; over that, or once the screen's snapshots hold 50 GB of changed data: 402 QUOTA_EXCEEDED, delete one first. Snapshots stay on the screen's host: backups and exports carry only the current disk, so a snapshot is an undo point, not a backup. They go with the screen when it is deleted.
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.
Snapshot 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_atDelete a snapshot
Needs the power permission. Answers within 5 s.
Deletes it at once, with no undo, and frees the space it held. The screen is not touched.
path Parameters
screen_id^scr_[0-9a-z]{20}$ · requiredScreen id (scr_...).
snapshot_id^snap_[0-9a-z]{20}$ · requiredSnapshot id (snap_...).
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 snapshot › Responses
Deleted.
Reset a screen
Needs the power permission. Answers within 5 s.
Puts the screen's disk back to a snapshot or, with snapshot_id null, to how the screen started (the clean image, or its template's disk), then starts it. Everything written since is lost, and so are the snapshots taken after the one gone back to (all of them for a reset to the start), since the disk rolls back along one line. The id, name, kind, bill, proxy and secrets stay; the incarnation goes up, so old screenshots and exec ids stop applying. Returns 202 with an operation. API keys need power; MCP clients can never reset.
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.
Reset 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_at