Templates

Download schema

Saved screens that new screens start from, in seconds.

List templates

GET

https://api.trykubi.com/v1

/templates

Bearer (API key)

Needs the read permission. Answers within 2 s.

The organization's templates, newest first.

List templates › query Parameters

limit

integer · int32 · min: 1 · max: 100

Page size, 1 to 100.

Default: 20

after

string · maxLength: 200 · pattern: ^[A-Za-z0-9_-]+$

Opaque cursor from the previous page's next.

List templates › Responses

Success.

TemplateList

Template[] · maxItems: 100 · required

required

Save a screen as a template

POST

https://api.trykubi.com/v1

/templates

Bearer (API key)

Needs the power permission. Answers within 5 s.

Saves the screen's disk; with_memory says whether screens started from it also come back with the open windows it was saved with. A running screen pauses for a few seconds while it is saved. Returns 202 with an operation; the template is listed at once as saving. Secrets are never on the disk, so none is saved. Over the template cap: 402 QUOTA_EXCEEDED.

Save a screen as a template › 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.

Save a screen as a template › Request Body

TemplateCreate

screen_id

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

name

string · maxLength: 63 · pattern: ^[a-z0-9][a-z0-9-]{0… · required

Unique among the organization's templates.

Save a screen as a template › Responses

Accepted.

Work that takes longer than one call. Kept 30 days.

Operation

id

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

OperationKind · required

required

reconciling: the outcome is uncertain and we are checking the host. Not a failure; do not retry.

screen_id

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

created_at

string · date-time · maxLength: 40 · required

updated_at

string · date-time · maxLength: 40 · required

POST/templates

curl -X POST 'https://api.trykubi.com/v1/templates' \
  -H "Authorization: Bearer $KUBI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"screen_id": "scr_7f2kq9w3x8m4b6tzp1ac", "name": "osworld-base"}'

Example Request Body

{
  "screen_id": "scr_7f2kq9w3x8m4b6tzp1ac",
  "name": "osworld-base"
}

json

application/json

Example Responses

{
  "id": "op_01jb7q0x9v2k8m4n6p3r",
  "kind": "template.create",
  "status": "running",
  "screen_id": "scr_7f2kq9w3x8m4b6tzp1ac",
  "template_id": "tpl_01jb9a2m5k8q3w9x4z6t",
  "snapshot_id": null,
  "error": null,
  "progress": "saving the disk",
  "created_at": "2026-10-22T09:14:07Z",
  "updated_at": "2026-10-22T09:14:07Z",
  "done_at": null
}

json

application/json

Get a template

GET

https://api.trykubi.com/v1

/templates/{template_id}

Bearer (API key)

Needs the read permission. Answers within 2 s.

One template.

Get a template › path Parameters

template_id

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

Template id (tpl_...).

Get a template › Responses

Success.

A saved screen to start new screens from: its disk, which holds what was installed on it, browser logins done by hand included. It never holds a secret: secrets are kept in the screen's memory and never written to its disk, so no template can carry one.

Template

id

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

name

string · maxLength: 63 · pattern: ^[a-z0-9][a-z0-9-]{0… · required

required

saving: being made from its screen.

Resources · required

One size at launch. Resize comes later.

with_memory

boolean · required

true: a screen started from it comes back with the open windows it was saved with. false: it boots from the saved disk.

screens_started

integer · int32 · min: 0 · max: 2147483647 · required

Screens started from it so far.

created_at

string · date-time · maxLength: 40 · required

Delete a template

DELETE

https://api.trykubi.com/v1

/templates/{template_id}

Bearer (API key)

Needs the power permission. Answers within 5 s.

Deletes it at once, with no undo. Screens started from it keep running.

Delete a template › path Parameters

template_id

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

Template id (tpl_...).

Delete a template › Responses

Deleted.

No data returned

Operations Snapshots