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

# 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:

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

## Long-running operations

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](https://docs.kiste.run/api/events.md#read-events)
(`instance.stopped`, `instance.running`, `instance.error`, `instance.deleted`).
A second lifecycle request meanwhile answers `409` with
[K05](https://docs.kiste.run/errors/k.md#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`:

```json
{ "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](https://docs.kiste.run/errors.md) lists every code.

## Rate limits

Requests are counted per minute. A spent budget answers `429` with
[L01](https://docs.kiste.run/errors/l.md#l01) `rate_limited` and a `Retry-After` header. The budgets are
listed in [Rate limits and quotas](https://docs.kiste.run/limits.md).

## 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](https://docs.kiste.run/errors/p.md#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](https://docs.kiste.run/errors/n.md#n01) instead of a gateway error page. Your Kisten are not
affected; try again.

## Related topics

- [Overview](https://docs.kiste.run/api.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)
- [Schemas](https://docs.kiste.run/api/schemas.md)
- Previous: [Overview](https://docs.kiste.run/api.md)
- Next: [Kisten](https://docs.kiste.run/api/instances.md)