> Documentation index: https://docs.kiste.run/llms.txt, a list of every page in this documentation.

# Schemas

> Every object the documented API endpoints send and receive, with its fields.

The objects of the API, generated from the published specification at [kiste.run/openapi.json](https://kiste.run/openapi.json). Fields marked as required are always present in answers and must be sent in requests.

## AccountDeletion

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | string or null | yes |  |
| `attempts` | integer | yes |  |
| `completed_at` | string (date-time) or null | yes |  |
| `id` | string | yes | Unique ID. |
| `last_error` | string or null | yes |  |
| `message` | string | no |  |
| `next_attempt_at` | string (date-time) or null | no |  |
| `object` | `"account_deletion"` | yes | The kind of object, such as `instance` or `list`. |
| `requested_at` | string (date-time) | yes |  |
| `state` | `"pending"`, `"completed"` | yes |  |
| `step` | `"workers"`, `"billing"`, `"records"`, `"done"` | yes |  |
| `updated_at` | string (date-time) | yes | When it last changed. |

## AccountExportFile

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | string | yes |  |
| `compute` | object or null | yes |  |
| `control_plane` | object | yes |  |
| `generated_at` | string (date-time) | yes |  |
| `object` | `"account_export"` | yes | The kind of object, such as `instance` or `list`. |

## AccountExportLink

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_at` | string (date-time) | yes |  |
| `message` | string | yes |  |
| `object` | `"account_export_link"` | yes | The kind of object, such as `instance` or `list`. |
| `url` | string | yes |  |

## AlertPreferenceResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | yes |  |
| `enabled` | boolean | yes |  |
| `kind` | string | yes |  |
| `title` | string | yes |  |

## AlertPreferencesResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of [AlertPreferenceResponse](https://docs.kiste.run/api/schemas.md#alertpreferenceresponse) | yes |  |
| `email` | string | yes |  |
| `email_delivery` | string | yes | `configured` when the origin has an SMTP relay, else `unconfigured`. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |

## AlertResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `acknowledged_at` | string (date-time) or null | no | When it was acknowledged, or null while open. |
| `created_at` | string (date-time) | yes | When it was created. |
| `detail` | string | yes | What happened and what to do. |
| `emailed_at` | string (date-time) or null | no | When it was e-mailed, or null. |
| `id` | string (uuid) | yes | Unique ID. |
| `kind` | string | yes | Alert kind, such as `instance_error` or `disk_almost_full`. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `resource_id` | string or null | no | ID of that object. |
| `resource_type` | string or null | no | Kind of object the alert is about. |
| `title` | string | yes | Short text for people. |

## ApiTokenResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string (date-time) | yes | When it was created. |
| `expires_at` | string (date-time) | yes | When the key stops working. |
| `id` | string (uuid) | yes | Unique ID. |
| `label` | string | yes | The key's label, unique among your active keys. |
| `last_used_at` | string (date-time) or null | no | When the key was last used, or null. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `revoked_at` | string (date-time) or null | no | When the key was revoked, or null. |
| `token_hint` | string | yes | A short, non-secret part of the key to recognise it. |

## CapacityMetrics

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `available_mib` | integer (int64) | yes |  |
| `total_mib` | integer (int64) | yes |  |
| `used_mib` | integer (int64) | yes |  |

## CommandResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cancel_requested_at` | string (date-time) or null | no | When a cancel or interrupt was requested. |
| `completion_status` | string or null | no | How it ended, once it ended. |
| `duration_ms` | integer (int64) or null | no | How long it ran, in milliseconds. |
| `error_message` | string or null | no | Why it couldn't run or finish, if so. |
| `exit_code` | integer (int32) or null | no | Exit code, once it exited. |
| `finished_at` | string (date-time) or null | no | When it ended. |
| `id` | string (uuid) | yes | Unique ID. |
| `instance_id` | string (uuid) | yes | ID of the Kiste the command ran in. |
| `instance_name` | string | yes | Name of the Kiste the command ran in. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `signal` | integer (int32) or null | no | Signal that ended it, if one did. |
| `started_at` | string (date-time) | yes | When it started. |
| `status` | string | yes | State of the command, such as `running`, `completed` or `failed`. |
| `stderr_bytes` | integer (int64) or null | no | Bytes written to standard error. |
| `stdout_bytes` | integer (int64) or null | no | Bytes written to standard output. |
| `updated_at` | string (date-time) | yes | When it last changed. |

## ControlEventResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string (date-time) | yes | When it was created. |
| `data` | any | yes | Details of the event, depending on its type. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `resource_id` | string | yes | ID of that object. |
| `resource_type` | string | yes | Kind of object the event is about, such as `instance`. |
| `sequence` | integer (int64) | yes | Position in your account's event stream; increases with every event. |
| `type` | string | yes | Event type, such as `instance.running`. |

## ControlHealth

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `region` | string or null | yes |  |
| `service` | string | yes |  |
| `status` | string | yes |  |

## ControlPlaneStatusResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `features` | [FeatureStatusResponse](https://docs.kiste.run/api/schemas.md#featurestatusresponse) | yes |  |
| `limits` | [ResourceLimitsResponse](https://docs.kiste.run/api/schemas.md#resourcelimitsresponse) | yes |  |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `status` | string | yes |  |
| `usage` | [ResourceUsageResponse](https://docs.kiste.run/api/schemas.md#resourceusageresponse) | yes |  |
| `version` | string | yes |  |

## CpuMetrics

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cores` | integer (int32) | yes |  |
| `load_1` | number (double) | yes |  |
| `load_15` | number (double) | yes |  |
| `load_5` | number (double) | yes |  |
| `percent` | number (double) or null | no | Whole-guest utilisation over the sampling window; `None` when the second sample could not be read. |

## CreateApiTokenRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_in_seconds` | integer (int32) | yes |  |
| `label` | string | yes |  |

## CreateDesktopLinkRequest

Mints a reusable desktop link for one machine. `ttl_seconds` defaults to `DESKTOP_LINK_DEFAULT_TTL_SECONDS` and must lie within `DESKTOP_LINK_MIN_TTL_SECONDS`..=`DESKTOP_LINK_MAX_TTL_SECONDS`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ttl_seconds` | integer (int32) or null | no |  |

## CreateEnvironmentRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `repositories` | array of [RepositorySpec](https://docs.kiste.run/api/schemas.md#repositoryspec) | no |  |
| `secret_files` | array of [SecretFileInput](https://docs.kiste.run/api/schemas.md#secretfileinput) | no |  |
| `setup_script` | string | no |  |
| `variables` | map of string | no |  |

## CreateImageRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `components` | array of [ImageComponentSelection](https://docs.kiste.run/api/schemas.md#imagecomponentselection) | no |  |
| `from` | string | no |  |
| `name` | string | yes |  |
| `resources` | null or [ImageResources](https://docs.kiste.run/api/schemas.md#imageresources) | no |  |

## CreateInstanceRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `auto_snapshot_seconds` | integer (int32) or null | no | How often a changed disk is checkpointed, 60–86400 seconds (default 300). Automatic checkpoints are always on; only the interval is configurable. |
| `disk_mib` | integer (int32) | yes | Disk size in MiB (default shape: 81920). |
| `environment` | string or null | no | An environment by name; its current version is applied. |
| `image` | string or null | no | A custom image by ID, slug or name; the universal image when omitted. |
| `memory_mib` | integer (int32) | yes | Memory in MiB (default shape: 8192). |
| `name` | string or null | no | Name of the new Kiste; generated when omitted. |
| `profile` | [InstanceProfile](https://docs.kiste.run/api/schemas.md#instanceprofile) | yes | Machine profile; `desktop`. |
| `ssh_public_key` | string | yes | An SSH public key the Kiste trusts, in addition to your account's device keys. |
| `ttl_seconds` | integer (int32) or null | no | Lifetime in seconds; when it ends the Kiste stops cleanly (its disk stays). Without it the Kiste runs until it is stopped. |
| `vcpu` | integer (int32) | yes | Number of vCPUs, within your account's limits (default shape: 4). |

## CreateServiceRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | no |  |
| `name` | string | yes |  |
| `port` | integer (int32) | yes |  |

## CreateSnapshotRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |

## CreateTerminalSessionRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cols` | integer (int32) | no |  |
| `rows` | integer (int32) | no |  |

## CreateWebhookRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | array of string | yes |  |
| `name` | string | yes |  |
| `url` | string | yes |  |

## CreatedApiTokenResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | [ApiTokenResponse](https://docs.kiste.run/api/schemas.md#apitokenresponse) | yes |  |
| `token` | string | yes |  |

## CreatedWebhookResponse

The plaintext signing secret is returned exactly once, alongside the endpoint it belongs to, mirroring `CreatedApiTokenResponse`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | [WebhookEndpointResponse](https://docs.kiste.run/api/schemas.md#webhookendpointresponse) | yes |  |
| `secret` | string | yes |  |

## DeleteAccountRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `confirm` | string | yes | The account's e-mail address, typed as confirmation. |
| `password` | string | yes |  |

## DeletedApiTokenResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | yes |  |
| `id` | string (uuid) | yes | Unique ID. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |

## DeletedDeviceKey

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | yes |  |
| `id` | string | yes | Unique ID. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |

## DeletedImage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | yes |  |
| `id` | string | yes | Unique ID. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |

## DeletedSession

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | yes |  |
| `id` | string | yes | Unique ID. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |

## DeletedWebhookResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | yes |  |
| `id` | string (uuid) | yes | Unique ID. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |

## DesktopBootstrapPreflightRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine` | string | yes |  |
| `protocol` | string | yes |  |

## DesktopBootstrapRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine` | string | yes |  |
| `protocol` | string | yes |  |

## DesktopBootstrapResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_at` | string (date-time) | yes |  |
| `offer_url` | string | yes | Where the viewer posts its SDP offer for the native transport. |
| `protocol` | string | yes |  |
| `recovery` | [RecoveryCapability](https://docs.kiste.run/api/schemas.md#recoverycapability) | yes |  |
| `revoke_url` | string | yes |  |
| `transport` | string | yes |  |

## DesktopLinkResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_at` | string (date-time) | yes |  |
| `url` | string | yes |  |

## DesktopSessionResponse

Type: [DesktopBootstrapResponse](https://docs.kiste.run/api/schemas.md#desktopbootstrapresponse) and object.

## DeviceKey

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string (date-time) | yes | When it was created. |
| `id` | string | yes | Unique ID. |
| `last_used_at` | string (date-time) or null | yes |  |
| `name` | string | yes |  |
| `object` | `"device_key"` | yes | The kind of object, such as `instance` or `list`. |
| `public_key` | string | yes |  |

## DeviceKeyList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of [DeviceKey](https://docs.kiste.run/api/schemas.md#devicekey) | yes |  |
| `first_id` | string or null | yes |  |
| `has_more` | boolean | yes |  |
| `last_id` | string or null | yes |  |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |

## EnvironmentResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string (date-time) | yes | When it was created. |
| `current_version` | integer (int32) | yes |  |
| `id` | string (uuid) | yes | Unique ID. |
| `name` | string | yes |  |
| `updated_at` | string (date-time) | yes | When it last changed. |

## EnvironmentVersionResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string (date-time) | yes | When it was created. |
| `environment_id` | string (uuid) | yes | ID of the environment. |
| `environment_name` | string | yes | Name of the environment. |
| `id` | string (uuid) | yes | Unique ID. |
| `repositories` | array of [RepositorySpec](https://docs.kiste.run/api/schemas.md#repositoryspec) | yes | Repositories cloned into `/workspace`. |
| `secret_paths` | array of string | yes | Paths of the secret files; their contents are never returned. |
| `setup_script` | string | yes | Script run in `/workspace` after cloning. |
| `variables` | map of string | yes | Variables set for the setup script. |
| `version` | integer (int32) | yes | Version number; every change adds one. |

## ExecCompletion

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `duration_ms` | integer (int64) | yes |  |
| `exit_code` | integer (int32) | yes |  |
| `id` | string (uuid) | yes | Unique ID. |
| `instance` | string | yes |  |
| `signal` | integer (int32) or null | no |  |
| `status` | [ExecCompletionStatus](https://docs.kiste.run/api/schemas.md#execcompletionstatus) | yes |  |
| `stderr_bytes` | integer (int64) | yes |  |
| `stdout_bytes` | integer (int64) | yes |  |

## ExecCompletionStatus

One of `"exited"`, `"signaled"`, `"timed_out"`, `"cancelled"`, `"output_limit_exceeded"`.

## ExecEvent

The stable native-execution stream contract. Each event is encoded as one newline-delimited JSON object by the HTTP API. Output bytes are base64 so arbitrary compiler output remains lossless and frame boundaries never depend on UTF-8 character boundaries.

Type: object or object or [ExecCompletion](https://docs.kiste.run/api/schemas.md#execcompletion) and object or object.

## ExecOutputStream

One of `"stdout"`, `"stderr"`.

## ExecRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `argv` | array of string | yes | The program and its arguments, passed exactly, without a shell. |
| `cwd` | string or null | no | Working directory inside the Kiste. |
| `env` | map of string | no | Environment variables for the command. |
| `id` | string (uuid) or null | no | Your own UUID for the command, to cancel it or find its record. |
| `timeout_ms` | integer (int64) | no | Longest run time in milliseconds. |

## ExtendInstanceRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ttl_seconds` | integer (int32) | yes | Seconds added to the Kiste's deadline (or from now when it has none); at the deadline it stops cleanly. |

## FeatureStatusResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `command_interrupt` | boolean | yes |  |
| `event_watch` | boolean | yes |  |
| `hosted_http` | boolean | yes |  |
| `hosted_websocket` | boolean | yes |  |
| `native_exec_stream` | boolean | yes |  |
| `remote_snapshot_pull` | boolean | yes |  |
| `snapshot_storage_mode` | string | yes |  |
| `snapshots` | boolean | yes |  |

## ForkInstanceRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `ttl_seconds` | integer (int32) or null | no | The copy's lifetime in seconds (60 to 2592000); without it the copy has no automatic stop (it never inherits the source's deadline). |

## HostedServiceResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string (date-time) | yes | When it was created. |
| `description` | string | yes | What runs on the port. |
| `id` | string (uuid) | yes | Unique ID. |
| `instance_id` | string (uuid) | yes | ID of the Kiste. |
| `instance_name` | string | yes | Name of the Kiste. |
| `name` | string | yes | The published port's name. |
| `path_prefix` | string | yes | The path the app is served from. |
| `port` | integer (int32) | yes | The port inside the Kiste. |
| `protocol` | string | yes | The protocol passed on to the app. |
| `public_url` | string | yes | The public address, `https://<label>.kiste.stream/`. |
| `status` | string | yes | State of the published port. |
| `updated_at` | string (date-time) | yes | When it last changed. |
| `websocket` | boolean | yes | Whether WebSocket upgrades are passed on. |

## IceServer

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credential` | string | no |  |
| `urls` | array of string | yes |  |
| `username` | string | no |  |

## ImageComponent

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | string | yes |  |
| `default_version` | string | yes |  |
| `description` | string | yes |  |
| `estimated_size_mib` | integer (int32) | yes |  |
| `id` | string | yes | Unique ID. |
| `name` | string | yes |  |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `requires` | array of string | yes |  |
| `versions` | array of string | yes |  |

## ImageComponentSelection

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Unique ID. |
| `version` | string | yes |  |

## ImageOs

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `architecture` | string | yes |  |
| `distribution` | string | yes |  |
| `libc` | string | yes |  |
| `version` | string | yes |  |

## ImageResources

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `disk_mib` | integer (int32) | yes |  |
| `memory_mib` | integer (int32) | yes |  |
| `vcpu` | integer (int32) | yes |  |

## InstanceMetricsResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cpu` | [CpuMetrics](https://docs.kiste.run/api/schemas.md#cpumetrics) | yes |  |
| `disk` | [CapacityMetrics](https://docs.kiste.run/api/schemas.md#capacitymetrics) | yes |  |
| `instance` | string | yes |  |
| `memory` | [CapacityMetrics](https://docs.kiste.run/api/schemas.md#capacitymetrics) | yes |  |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `processes` | array of [ProcessMetrics](https://docs.kiste.run/api/schemas.md#processmetrics) | yes |  |
| `sampled_at` | string (date-time) | yes |  |
| `uptime_seconds` | integer (int64) | yes |  |

## InstanceProfile

Intentional extension seam: exactly one profile ships today, and the type is threaded through the node so a second machine profile lands as data, not surgery. Signatures that discard it do so deliberately.

One of `"desktop"`.

## InstanceResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `artifact_key` | string | yes | Content hash of the image's disk the Kiste was cloned from. |
| `auto_snapshot_seconds` | integer (int32) | yes | Seconds between automatic checkpoints, taken only when the disk changed. Automatic checkpoints are always on. |
| `components` | array of [ImageComponentSelection](https://docs.kiste.run/api/schemas.md#imagecomponentselection) | yes | The image components and versions copied into this Kiste. |
| `created` | integer (int64) | yes | When it was created, in Unix seconds. |
| `created_at` | string (date-time) | yes | When it was created. |
| `desired_state` | string | yes | The state the Kiste is moving to, `running` or `stopped`; differs from `status` while a change is in progress. |
| `disk_mib` | integer (int32) | yes | Disk size in MiB. |
| `environment_version_id` | string (uuid) or null | no | The environment version the Kiste was created with, or null. |
| `expires_at` | string (date-time) or null | no | When the Kiste stops by itself (its lifetime), or null for no automatic stop. |
| `id` | string (uuid) | yes | Unique ID. |
| `image` | string | yes | The image the Kiste was created from. |
| `image_version` | string or null | no | Kiste image version this instance's disk last received vendor content from (vYYYY.MM.DD-hash8), if the host has a record. |
| `last_checkpoint_at` | string (date-time) or null | no | When the newest checkpoint of this machine became ready. |
| `last_offsite_at` | string (date-time) or null | no | When the newest checkpoint of this machine was held in every off-site location. |
| `latest_image_version` | string or null | no | The image version the node currently serves. |
| `memory_mib` | integer (int32) | yes | Memory in MiB. |
| `name` | string | yes | The Kiste's name, unique in your account. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `profile` | [InstanceProfile](https://docs.kiste.run/api/schemas.md#instanceprofile) | yes | The machine profile; `desktop` for every Kiste today. |
| `session_saved` | boolean | no | A stopped instance whose memory session is saved: its next start resumes that session, on the image it was running. False in every other state. |
| `setup_error` | string or null | no | Why the setup failed, when it did. Visible only to you. |
| `setup_status` | string | yes | State of the environment's setup job. |
| `ssh_host` | string or null | no | SSH host alias of the Kiste, used by the CLI. |
| `ssh_port` | integer (int32) or null | no | SSH port inside the tunnel. |
| `status` | string | yes | The current state: `starting`, `running`, `stopping`, `stopped` or `error`. |
| `update_available` | boolean or null | no | True while a newer image version is available for this Kiste. Only a cold boot applies it: `kiste update` reboots a running Kiste; a stopped one gets it at its next start, unless a session is saved, which `kiste update` discards without starting the Kiste. |
| `updated_at` | string (date-time) | yes | When it last changed. |
| `vcpu` | integer (int32) | yes | Number of vCPUs. |

## InterruptCommandRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string or null | no |  |

## InterruptCommandResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accepted` | boolean | yes |  |
| `command` | [CommandResponse](https://docs.kiste.run/api/schemas.md#commandresponse) | yes |  |

## LogoutResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `authenticated` | boolean | no |  |
| `message` | string | no |  |
| `origin_revoked` | boolean | yes |  |

## LogsResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `logs` | string | yes |  |
| `name` | string | yes |  |

## MachineImage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `artifact_key` | string | yes | Content hash of the disk Kisten boot from. |
| `base_image` | string or null | no | The image it builds on. |
| `build_strategy` | string | yes | How the image's disk is produced. |
| `components` | array of [ImageComponentSelection](https://docs.kiste.run/api/schemas.md#imagecomponentselection) | yes | Components and versions the image guarantees. |
| `created` | integer (int64) | yes | When it was created, in Unix seconds. |
| `description` | string | yes | What the image is for. |
| `estimated_size_mib` | integer (int32) | yes | Estimated disk size in MiB. |
| `id` | string | yes | Unique ID. |
| `launchable` | boolean | yes | Whether Kisten can be created from it now. |
| `name` | string | yes | The image's name. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `os` | [ImageOs](https://docs.kiste.run/api/schemas.md#imageos) | yes | Operating system of the image. |
| `owned_by` | string | yes | Who owns the image. |
| `profile` | [InstanceProfile](https://docs.kiste.run/api/schemas.md#instanceprofile) | yes | Machine profile Kisten from this image get. |
| `resources` | [ImageResources](https://docs.kiste.run/api/schemas.md#imageresources) | yes | Default size of Kisten created from it. |
| `slug` | string | yes | Short name to refer to the image. |
| `status` | string | yes | `ready` when Kisten can be created from it. |
| `visibility` | string | yes | Who can see the image: built-in images everyone, private ones only you. |

## MessageResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | yes |  |

## NativeOfferRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sdp` | string | yes |  |

## NativeOfferResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sdp` | string | yes |  |

## NoticeRef

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `args` | map of string or number | yes |  |
| `id` | string | yes | A registered notice id ([https://kiste.run/errors.json](https://kiste.run/errors.json), notices). |

## OAuthTokenRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | yes |  |
| `code` | string | yes |  |
| `code_verifier` | string | yes |  |
| `grant_type` | `"authorization_code"` | yes |  |
| `redirect_uri` | string | yes |  |

## OAuthTokenResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `access_token` | string | yes |  |
| `expires_in` | integer | yes |  |
| `token_type` | `"Bearer"` | yes |  |
| `user` | [UserResponse](https://docs.kiste.run/api/schemas.md#userresponse) | yes |  |

## PlatformStatus

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `components` | array of object | yes |  |
| `errors_24h` | array of object | yes |  |
| `incidents` | array of object | yes |  |
| `maintenance` | array of object | yes | Planned maintenance windows: open, upcoming and of the last 90 days. component is a component id; closed_at null while the window is open. |
| `state` | `"operational"`, `"degraded"`, `"outage"`, `"maintenance"`, `"unknown"` | yes |  |
| `updated_at` | string (date-time) | yes | When it last changed. |

## ProcessMetrics

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `command` | string | yes |  |
| `cpu_percent` | number (double) | yes |  |
| `pid` | integer (int32) | yes |  |
| `rss_mib` | number (double) | yes |  |

## RecoveryCapability

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes |  |
| `websocket_url` | string | yes |  |

## RegisterDeviceKeyRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `public_key` | string | yes |  |

## RenameInstanceRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The new Kiste name; same rules as at creation. |

## RepositorySpec

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `destination` | string or null | no |  |
| `revision` | string or null | no |  |
| `url` | string | yes |  |

## ResolveImageRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `components` | array of [ImageComponentSelection](https://docs.kiste.run/api/schemas.md#imagecomponentselection) | no |  |
| `from` | string | no |  |
| `resources` | null or [ImageResources](https://docs.kiste.run/api/schemas.md#imageresources) | no |  |

## ResolvedImagePlan

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `added_dependencies` | array of string | yes |  |
| `artifact_key` | string | yes |  |
| `build_strategy` | string | yes |  |
| `cache_hit` | boolean | yes |  |
| `cache_key` | string | yes |  |
| `components` | array of [ImageComponentSelection](https://docs.kiste.run/api/schemas.md#imagecomponentselection) | yes |  |
| `estimated_size_mib` | integer (int32) | yes |  |
| `from` | string | yes |  |
| `id` | string | yes | Unique ID. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `resources` | [ImageResources](https://docs.kiste.run/api/schemas.md#imageresources) | yes |  |
| `warnings` | array of string | yes |  |

## ResourceLimitsResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `max_disk_mib` | integer (int64) | yes |  |
| `max_images` | integer (int64) | yes |  |
| `max_instance_disk_mib` | integer (int64) | yes |  |
| `max_instances` | integer (int64) | yes |  |
| `max_memory_mib` | integer (int64) | yes |  |
| `max_running_instances` | integer (int64) | no | Running at once (the operator's own account is exempt). |
| `max_running_memory_mib` | integer (int64) | no |  |
| `max_running_vcpu` | integer (int64) | no |  |
| `max_vcpu` | integer (int64) | yes |  |
| `min_disk_mib` | integer (int64) | yes |  |
| `min_memory_mib` | integer (int64) | yes |  |
| `min_vcpu` | integer (int64) | yes |  |

## ResourceUsageResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `active_api_tokens` | integer (int64) | yes |  |
| `disk_mib` | integer (int64) | yes |  |
| `images` | integer (int64) | yes |  |
| `instances` | integer (int64) | yes |  |
| `memory_mib` | integer (int64) | yes |  |
| `running_instances` | integer (int64) | yes |  |
| `snapshot_disk_mib` | integer (int64) | yes |  |
| `snapshots` | integer (int64) | yes |  |
| `vcpu` | integer (int64) | yes |  |

## RestoreSnapshotRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from_offsite` | boolean | no | Restore from the off-site copy even where the local copy exists: proves the off-site copy restores (it boots lazily from it). |
| `name` | string | yes |  |

## RevokeDesktopLinksResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `revoked` | integer (int64) | yes |  |

## RuntimeImageResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `latest_version` | string | yes | The image version the node currently serves. |
| `notes` | string | yes | Human-readable notes for the most recent image round, shown before an update. Lines starting with `BREAKING:` deserve attention. |

## SecretFileInput

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contents_base64` | string | yes |  |
| `mode` | integer (int32) | no |  |
| `path` | string | yes |  |

## SessionRevocation

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `origin_revoked` | boolean | yes |  |
| `revoked` | integer | yes |  |

## SignIn

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string (date-time) | yes | When it was created. |
| `current` | boolean | yes |  |
| `expires_at` | string (date-time) | yes |  |
| `id` | string | yes | Unique ID. |
| `kind` | `"browser"`, `"cli"` | yes |  |
| `last_used_at` | string (date-time) | yes |  |
| `name` | string | yes |  |
| `object` | `"session"` | yes | The kind of object, such as `instance` or `list`. |

## SignInList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of [SignIn](https://docs.kiste.run/api/schemas.md#signin) | yes |  |
| `has_more` | boolean | yes |  |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |

## SnapshotPullResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `available` | boolean | yes |  |
| `chunk_bytes` | integer (int32) or null | no |  |
| `chunk_count` | integer (int32) or null | no |  |
| `encryption_key_id` | string or null | no |  |
| `logical_bytes` | integer (int64) or null | no |  |
| `manifest_digest` | string or null | no |  |
| `manifest_key` | string or null | no |  |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `reason` | string | yes |  |
| `remote_status` | string or null | no |  |
| `snapshot` | [SnapshotResponse](https://docs.kiste.run/api/schemas.md#snapshotresponse) | yes |  |
| `transport` | string | yes |  |

## SnapshotRemote

A snapshot's off-site copy.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `copies` | integer (int32) | yes | Independent locations holding every object once uploaded. |
| `new_bytes` | integer (int64) | yes | Bytes this snapshot added to the store (its changes since the last). |
| `state` | string | yes | pending, uploading, uploaded or failed. |
| `stored_bytes` | integer (int64) | yes | Stored (compressed, encrypted) bytes of every object the snapshot needs, shared ones included. |
| `uploaded_at` | string (date-time) or null | no |  |

## SnapshotResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `artifact_key` | string | yes | Content hash of the image the source Kiste was cloned from. |
| `components` | array of [ImageComponentSelection](https://docs.kiste.run/api/schemas.md#imagecomponentselection) | yes | Image components of the source Kiste. |
| `consistency` | string or null | no | `frozen` (taken with the guest's file system frozen: clean) or `crash` (taken while the guest wrote heavily, like a power cut: every fsynced write is in it); null for snapshots taken before this was recorded. |
| `created_at` | string (date-time) | yes | When it was created. |
| `disk_mib` | integer (int32) | yes | Disk size of the Kiste it was taken from, in MiB. |
| `generation` | integer (int32) | yes | Position in its lineage. |
| `id` | string (uuid) | yes | Unique ID. |
| `image` | string | yes | Image of the source Kiste. |
| `kind` | string | yes | `manual` for a named snapshot, `automatic` for a checkpoint. |
| `lineage_id` | string (uuid) | yes | Groups snapshots that share an origin. |
| `local` | boolean | yes | The reflink is still on its worker (restores instantly there). |
| `memory_mib` | integer (int32) | yes | Memory of the Kiste it was taken from, in MiB. |
| `metadata_digest` | string | yes | Hash of the snapshot's metadata. |
| `name` | string | yes | The snapshot's name. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `parent_snapshot_id` | string (uuid) or null | no | The snapshot this one's Kiste was restored from, if any. |
| `profile` | [InstanceProfile](https://docs.kiste.run/api/schemas.md#instanceprofile) | yes | Machine profile of the source Kiste. |
| `ready_at` | string (date-time) or null | no | When it became ready. |
| `remote` | null or [SnapshotRemote](https://docs.kiste.run/api/schemas.md#snapshotremote) | no | The off-site copy. |
| `size_mib` | integer (int64) | yes | Space the snapshot occupies, in MiB. |
| `source_instance_id` | string (uuid) or null | no | ID of the Kiste it was taken from; null once that Kiste is deleted. |
| `source_name` | string | yes | Name of the Kiste it was taken from. |
| `status` | string | yes | State of the snapshot, `ready` once it can be restored. |
| `storage_mode` | string | yes | How the snapshot is stored. |
| `trigger` | string | yes | Why the checkpoint exists: manual, interval, stop, restart, delete or fork. |
| `updated_at` | string (date-time) | yes | When it last changed. |
| `vcpu` | integer (int32) | yes | vCPUs of the Kiste it was taken from; a restore gets the same. |

## SnapshotTreeResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of [SnapshotResponse](https://docs.kiste.run/api/schemas.md#snapshotresponse) | yes |  |
| `latest_snapshot_id` | string (uuid) or null | no |  |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |

## SshHostKeyResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `host_key_alias` | string | yes |  |
| `known_hosts` | string | yes |  |
| `name` | string | yes |  |
| `public_keys` | array of string | yes |  |

## StopInstanceRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `snapshot` | boolean | no | Preserve the running session: writes the memory snapshot so the next start resumes in about a second. Slower to stop. Without it the stop is a clean shutdown and the next start is a fresh boot. |

## TerminalSessionEnvelope

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | [TerminalSessionResponse](https://docs.kiste.run/api/schemas.md#terminalsessionresponse) | yes |  |

## TerminalSessionResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expires_at` | string (date-time) | yes |  |
| `id` | string (uuid) | yes | Unique ID. |
| `token` | string | yes |  |
| `websocket_url` | string | yes |  |

## UnlockResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `unlocked` | boolean | yes |  |

## UpdateEnvironmentRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `repositories` | array of [RepositorySpec](https://docs.kiste.run/api/schemas.md#repositoryspec) | no |  |
| `secret_files` | array of [SecretFileInput](https://docs.kiste.run/api/schemas.md#secretfileinput) | no |  |
| `setup_script` | string | no |  |
| `variables` | map of string | no |  |

## UpdateWebhookRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean or null | no |  |
| `events` | array of string or null | no |  |
| `name` | string or null | no |  |
| `url` | string or null | no |  |

## UserResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string (date-time) | yes | When it was created. |
| `email` | string | yes |  |
| `id` | string (uuid) | yes | Unique ID. |

## WatchEventsResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of [ControlEventResponse](https://docs.kiste.run/api/schemas.md#controleventresponse) | yes |  |
| `has_more` | boolean | yes |  |
| `next_cursor` | integer (int64) | yes |  |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |

## WebhookDeliveryResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attempt` | integer (int32) | yes |  |
| `created_at` | string (date-time) | yes | When it was created. |
| `delivered_at` | string (date-time) or null | no |  |
| `endpoint_id` | string (uuid) | yes |  |
| `error` | string or null | no |  |
| `event_sequence` | integer (int64) | yes |  |
| `event_type` | string | yes |  |
| `id` | string (uuid) | yes | Unique ID. |
| `next_attempt_at` | string (date-time) or null | no |  |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `state` | string | yes |  |
| `status_code` | integer (int32) or null | no |  |

## WebhookEndpointResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string (date-time) | yes | When it was created. |
| `enabled` | boolean | yes | Whether deliveries are made. |
| `events` | array of string | yes | The event types delivered. |
| `failing_since` | string (date-time) or null | no | Since when deliveries keep failing, or null. |
| `id` | string (uuid) | yes | Unique ID. |
| `last_delivery_at` | string (date-time) or null | no | When the last delivery was attempted. |
| `last_delivery_status` | integer (int32) or null | no | HTTP status of the last delivery. |
| `name` | string | yes | The endpoint's name. |
| `object` | string | yes | The kind of object, such as `instance` or `list`. |
| `secret_hint` | string | yes | A short, non-secret part of the signing secret. |
| `updated_at` | string (date-time) | yes | When it last changed. |
| `url` | string | yes | Where deliveries go (HTTPS, port 443). |

## Related topics

- [Overview](https://docs.kiste.run/api.md)
- [Conventions](https://docs.kiste.run/api/conventions.md)
- [Kisten](https://docs.kiste.run/api/instances.md)
- [Commands](https://docs.kiste.run/api/commands.md)
- [Snapshots](https://docs.kiste.run/api/snapshots.md)
- [SSH and terminal](https://docs.kiste.run/api/ssh-and-terminal.md)
- [Desktop](https://docs.kiste.run/api/desktop.md)
- [Kiste Stream](https://docs.kiste.run/api/stream.md)
- [Images and environments](https://docs.kiste.run/api/images.md)
- [Events, webhooks and alerts](https://docs.kiste.run/api/events.md)
- [Account and access](https://docs.kiste.run/api/account.md)
- [Sign-in and platform](https://docs.kiste.run/api/platform.md)
- Previous: [Sign-in and platform](https://docs.kiste.run/api/platform.md)
- Next: [Overview](https://docs.kiste.run/errors.md)