Conventions

Base URL, authentication, JSON, lists, long-running operations, request IDs, errors, rate limits and body limits of the Kiste API.

Base URL and format

Base URL: https://kiste.run. Every endpoint is HTTPS only.
Requests and answers are JSON (Content-Type: application/json), except POST /v1/instances/{name}/exec, which streams newline-delimited JSON (application/x-ndjson), and the WebSocket endpoints (SSH tunnel, terminal, recovery console), which answer 101 Switching Protocols.
Times are RFC 3339 in UTC, such as 2026-10-06T14:25:30Z. Sizes are MiB (memory_mib, disk_mib) unless the field name says otherwise.
Kisten are addressed by name (/v1/instances/review-42), most other objects by ID.

Lists

Collections use one shape:

{ "object": "list", "data": [ … ], "first_id": "…", "last_id": "…", "has_more": false }

Stop, restart, resume, update and delete wait up to 20 seconds for the operation. When it finishes in time, the answer is 200 with the final state. When it is still running, the answer is 202 Accepted with the Kiste as it is now (stopping, starting), and the operation continues. Follow it with GET /v1/instances/{name} or the event stream (instance.stopped, instance.running, instance.error, instance.deleted). A second lifecycle request meanwhile answers 409 with K05 machine_busy.

Creating a Kiste answers once the machine accepts SSH and commands.

Request IDs

Every answer carries an x-request-id header, and error bodies repeat it as request_id. You can send your own ID in x-request-id (the CLI does, one per command, and accepts --request-id); it is kept. Quote it to support.

Errors

Errors have one envelope with a registered code, a stable type, a message and hint for people, param, retryable, request_id and docs_url:

{ "error": { "code": "K01", "type": "machine_not_found", "message": "There is no Kiste named review-42 in your account. (code: K01)", "hint": "Check the name in your list of Kisten.", "param": null, "retryable": false, "request_id": "01J9Z8X7W6V5T4S3R2Q1P0N9M8", "docs_url": "https://kiste.run/errors/K01" } }

Branch on type; its meaning never changes. Errors that can be retried after a fixed delay send Retry-After. Errors lists every code.

Rate limits

Requests are counted per minute. A spent budget answers 429 with L01 rate_limited and a Retry-After header. The budgets are listed in Rate limits and quotas.

Body limits

Request	Largest body
`/v1` requests	64 KiB
Sign-in, OAuth, device keys, desktop sessions	8 KiB

A larger body answers 413 with P03 payload_too_large. Environment manifests and other large JSON documents have their own limits on their fields.

A compute service that can't be reached

When the compute service behind kiste.run can't be reached for a moment, requests that need it answer 503 with Retry-After: 30 and N01 instead of a gateway error page. Your Kisten are not affected; try again.