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

# Images and environments

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

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.

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

**Responses:**

- `200` OK. Body: list of [MachineImage](https://docs.kiste.run/api/schemas.md#machineimage)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

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

```bash
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](https://docs.kiste.run/api/schemas.md#createimagerequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `components` | array of [ImageComponentSelection](https://docs.kiste.run/api/schemas.md#imagecomponentselection) | no |  |
| `from` | string | no |  |
| `name` | string | yes |  |
| `resources` | null or [ImageResources](https://docs.kiste.run/api/schemas.md#imageresources) | no |  |

**Responses:**

- `200` OK. Body: [MachineImage](https://docs.kiste.run/api/schemas.md#machineimage)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Resolve an image

`POST /v1/images/resolve`

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

```bash
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](https://docs.kiste.run/api/schemas.md#resolveimagerequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `components` | array of [ImageComponentSelection](https://docs.kiste.run/api/schemas.md#imagecomponentselection) | no |  |
| `from` | string | no |  |
| `resources` | null or [ImageResources](https://docs.kiste.run/api/schemas.md#imageresources) | no |  |

**Responses:**

- `200` OK. Body: [ResolvedImagePlan](https://docs.kiste.run/api/schemas.md#resolvedimageplan)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Get an image

`GET /v1/images/{id}`

One built-in or private image by its ID.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

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

**Responses:**

- `200` OK. Body: [MachineImage](https://docs.kiste.run/api/schemas.md#machineimage)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

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

**Responses:**

- `200` OK. Body: [DeletedImage](https://docs.kiste.run/api/schemas.md#deletedimage)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## List image components

`GET /v1/image-components`

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

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

**Responses:**

- `200` OK. Body: list of [ImageComponent](https://docs.kiste.run/api/schemas.md#imagecomponent)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## List environments

`GET /v1/environments`

Your launch environments.

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

**Responses:**

- `200` OK. Body: list of [EnvironmentResponse](https://docs.kiste.run/api/schemas.md#environmentresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

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

```bash
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](https://docs.kiste.run/api/schemas.md#createenvironmentrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `repositories` | array of [RepositorySpec](https://docs.kiste.run/api/schemas.md#repositoryspec) | no |  |
| `secret_files` | array of [SecretFileInput](https://docs.kiste.run/api/schemas.md#secretfileinput) | no |  |
| `setup_script` | string | no |  |
| `variables` | map of string | no |  |

**Responses:**

- `200` OK. Body: [EnvironmentVersionResponse](https://docs.kiste.run/api/schemas.md#environmentversionresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Get an environment

`GET /v1/environments/{name}`

An environment with its current version.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The Kiste's name. |

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

**Responses:**

- `200` OK. Body: [EnvironmentVersionResponse](https://docs.kiste.run/api/schemas.md#environmentversionresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The Kiste's name. |

```bash
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](https://docs.kiste.run/api/schemas.md#updateenvironmentrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `repositories` | array of [RepositorySpec](https://docs.kiste.run/api/schemas.md#repositoryspec) | no |  |
| `secret_files` | array of [SecretFileInput](https://docs.kiste.run/api/schemas.md#secretfileinput) | no |  |
| `setup_script` | string | no |  |
| `variables` | map of string | no |  |

**Responses:**

- `200` OK. Body: [EnvironmentVersionResponse](https://docs.kiste.run/api/schemas.md#environmentversionresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

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

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

**Responses:**

- `200` OK. Body: [RuntimeImageResponse](https://docs.kiste.run/api/schemas.md#runtimeimageresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Related topics

- [Overview](https://docs.kiste.run/api.md)
- [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)
- [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 Stream](https://docs.kiste.run/api/stream.md)
- Next: [Events, webhooks and alerts](https://docs.kiste.run/api/events.md)