API reference

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, and the endpoint pages here are generated from that document, so they list exactly what is deployed.

A first request

Create an API key, then:

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

{
  "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 lists them all.)

Create a Kiste:

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 explains what an API key can and can't do.

Endpoints

Conventions covers lists, long operations, request IDs, errors and limits that apply to every endpoint.