Images and environments

Machine images, their components, launch environments and the image version the platform serves.

List images

GET /v1/images

The built-in universal image and your private images.

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

Responses:

• 200 OK. Body: list of MachineImage

Errors use the error envelope.

Save an image

POST /v1/images

Validates a manifest of components and saves it as a private image you can create Kisten from. Every component is already part of the universal image, so the image is ready at once.

curl -sS -X POST "https://kiste.run/v1/images" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Rust work","from":"universal","components":[{"id":"rust","version":"1.97.1"}]}'

Request body: CreateImageRequest

Responses:

• 200 OK. Body: MachineImage

Errors use the error envelope.

Resolve an image

POST /v1/images/resolve

Resolves a manifest without saving it: exact versions, added dependencies, recommended resources and content hashes.

curl -sS -X POST "https://kiste.run/v1/images/resolve" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"universal","components":[{"id":"rust","version":"1.97.1"}]}'

Request body: ResolveImageRequest

Responses:

• 200 OK. Body: ResolvedImagePlan

Errors use the error envelope.

Get an image

GET /v1/images/{id}

One built-in or private image by its ID.

Path parameters:

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

Responses:

• 200 OK. Body: MachineImage

Errors use the error envelope.

Delete an image

DELETE /v1/images/{id}

Deletes a private image. It answers 409 while any Kiste still uses it; the built-in image cannot be deleted.

Path parameters:

curl -sS -X DELETE "https://kiste.run/v1/images/ID" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Responses:

• 200 OK. Body: DeletedImage

Errors use the error envelope.

List image components

GET /v1/image-components

The components an image manifest can select, with their exact versions and dependencies.

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

Responses:

• 200 OK. Body: list of ImageComponent

Errors use the error envelope.

List environments

GET /v1/environments

Your launch environments.

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

Responses:

• 200 OK. Body: list of EnvironmentResponse

Errors use the error envelope.

Create an environment

POST /v1/environments

Creates a launch environment: repositories to clone, variables, secret files and a setup script that runs in the background of a new Kiste. Secret files are stored encrypted.

curl -sS -X POST "https://kiste.run/v1/environments" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"backend","repositories":[{"url":"https://github.com/example/api.git"}],"setup_script":"cd api && npm ci"}'

Request body: CreateEnvironmentRequest

Responses:

• 200 OK. Body: EnvironmentVersionResponse

Errors use the error envelope.

Get an environment

GET /v1/environments/{name}

An environment with its current version.

Path parameters:

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

Responses:

• 200 OK. Body: EnvironmentVersionResponse

Errors use the error envelope.

Publish a new environment version

PUT /v1/environments/{name}

Every change creates a new, immutable version. A Kiste keeps the version it was created with.

Path parameters:

curl -sS -X PUT "https://kiste.run/v1/environments/review-42" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repositories":[{"url":"https://github.com/example/api.git"}],"setup_script":"cd api && npm ci"}'

Request body: UpdateEnvironmentRequest

Responses:

• 200 OK. Body: EnvironmentVersionResponse

Errors use the error envelope.

Get the current image version

GET /v1/runtime/image

The image version the platform serves and its release notes. A Kiste whose image_version differs has an update available; lines in the notes starting with BREAKING: deserve attention.

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

Responses:

• 200 OK. Body: RuntimeImageResponse

Errors use the error envelope.