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

# Overview

> The Kiste HTTP API at kiste.run, its authentication and every endpoint.

Everything the CLI and the console do goes through one HTTP API at
`https://kiste.run`. It is described by an OpenAPI 3.1 document at
[kiste.run/openapi.json](https://kiste.run/openapi.json), and the endpoint pages
here are generated from that document, so they list exactly what is deployed.

## A first request

Create an [API key](https://docs.kiste.run/account/api-keys.md), then:

```bash
curl -sS https://kiste.run/v1/instances \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

```json
{
  "object": "list",
  "data": [
    { "object": "instance", "name": "review-42", "status": "running", "vcpu": 4, "memory_mib": 8192, "disk_mib": 81920 }
  ],
  "first_id": "…",
  "last_id": "…",
  "has_more": false
}
```

(The answer has more fields; [InstanceResponse](https://docs.kiste.run/api/schemas.md#instanceresponse)
lists them all.)

Create a Kiste:

```bash
curl -sS https://kiste.run/v1/instances \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"api-test","profile":"desktop","vcpu":4,"memory_mib":8192,"disk_mib":81920,"ssh_public_key":"ssh-ed25519 AAAA… you@laptop","ttl_seconds":3600}'
```

## Authentication

Every `/v1` request needs a bearer token in the `Authorization` header:

- an **API key** (`ksta_…`), created in the console under **API keys** or with
  `kiste auth token create`, for scripts, CI and agents;
- the token of a **CLI sign-in**, which `kiste login` stores for the CLI.

Browser sessions of the console use a cookie instead and work only on
console.kiste.run itself. [API keys](https://docs.kiste.run/account/api-keys.md) explains what an API key can
and can't do.

## Endpoints

- [Kisten](https://docs.kiste.run/api/instances.md): Create, read, stop, resume, restart, fork, rename, update, delete.
- [Commands](https://docs.kiste.run/api/commands.md): Run commands with exact output; durable records; cancel and interrupt.
- [Snapshots](https://docs.kiste.run/api/snapshots.md): Named snapshots and checkpoints; restore.
- [SSH and terminal](https://docs.kiste.run/api/ssh-and-terminal.md): The SSH tunnel, the host key, the browser terminal.
- [Desktop](https://docs.kiste.run/api/desktop.md): Desktop links and the viewer's routes.
- [Kiste Stream](https://docs.kiste.run/api/stream.md): Publish and revoke ports.
- [Images and environments](https://docs.kiste.run/api/images.md): Images, components, environments, image versions.
- [Events, webhooks and alerts](https://docs.kiste.run/api/events.md): The event stream, webhook endpoints, alerts.
- [Account and access](https://docs.kiste.run/api/account.md): Account, limits, sign-ins, API keys, device keys, export, deletion.
- [Sign-in and platform](https://docs.kiste.run/api/platform.md): OAuth for the CLI, platform status, the specification, installers.

[Conventions](https://docs.kiste.run/api/conventions.md) covers lists, long operations, request IDs,
errors and limits that apply to every endpoint.

## Related topics

- [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)
- [Schemas](https://docs.kiste.run/api/schemas.md)
- Previous: [kiste doctor](https://docs.kiste.run/cli/doctor.md)
- Next: [Conventions](https://docs.kiste.run/api/conventions.md)