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

# Desktop

> Desktop links, and the routes the desktop viewer uses with them.

Desktop links, and the routes the desktop viewer uses with them.

## Create a desktop link

`POST /v1/instances/{name}/desktop-link`

Mints a reusable link to the Kiste's desktop at desktop.kiste.run. It opens only in browsers signed in to your account, any number of times, until it expires. `ttl_seconds` defaults to 3600 and must be between 60 and 604800 (seven days). Several links can be live at once; a stop and resume of the Kiste keeps them.

**Path parameters:**

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

```bash
curl -sS -X POST "https://kiste.run/v1/instances/review-42/desktop-link" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Request body (optional):** [CreateDesktopLinkRequest](https://docs.kiste.run/api/schemas.md#createdesktoplinkrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ttl_seconds` | integer (int32) or null | no |  |

**Responses:**

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

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

## Revoke desktop links

`DELETE /v1/instances/{name}/desktop-link`

Revokes every live desktop link of the Kiste and answers how many. Desktops already open in a browser keep running; revocation only stops new browsers from joining.

**Path parameters:**

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

```bash
curl -sS -X DELETE "https://kiste.run/v1/instances/review-42/desktop-link" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

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

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

## Check desktop readiness

`POST /v1/desktop/native/preflight`

Used by the desktop viewer: answers `204` once the desktop can stream, a retryable error while it is still starting. It needs the desktop link and your signed-in account; a link alone opens nothing.

**Request body:** [DesktopBootstrapPreflightRequest](https://docs.kiste.run/api/schemas.md#desktopbootstrappreflightrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine` | string | yes |  |
| `protocol` | string | yes |  |

**Responses:**

- `204` No content.

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

## Start a desktop session

`POST /v1/desktop/native/session`

Used by the desktop viewer: exchanges a desktop link for this browser's own stream session. The link is not used up. The browser's session lasts 24 hours, independent of the link.

**Request body:** [DesktopBootstrapRequest](https://docs.kiste.run/api/schemas.md#desktopbootstraprequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine` | string | yes |  |
| `protocol` | string | yes |  |

**Responses:**

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

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

## Re-enter a desktop session

`POST /v1/desktop/native/session/renew`

Used by the desktop viewer after a reload, with the session the browser already holds.

**Request body:** [DesktopBootstrapRequest](https://docs.kiste.run/api/schemas.md#desktopbootstraprequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `machine` | string | yes |  |
| `protocol` | string | yes |  |

**Responses:**

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

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

## Connect the desktop stream

`POST /v1/desktop/native/{session}/offer`

Used by the desktop viewer: exchanges the browser's WebRTC offer for the answer that starts video and audio.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `session` | string | yes | The desktop session. |

**Request body:** [NativeOfferRequest](https://docs.kiste.run/api/schemas.md#nativeofferrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sdp` | string | yes |  |

**Responses:**

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

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

## End a desktop session

`DELETE /v1/desktop/native/session/{session}`

Used by the desktop viewer: ends this browser's desktop session.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `session` | string | yes | The desktop session. |

**Responses:**

- `204` No content.

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

## Connect the recovery console

`GET /v1/desktop/recovery/{session}`

Used by the desktop viewer: the recovery console, a plain remote-framebuffer view of the desktop for when the video stream cannot start. It has its own short-lived authorization.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `session` | string | yes | The desktop session. |

**Responses:**

- `101` WebSocket upgrade.

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)
- [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: [SSH and terminal](https://docs.kiste.run/api/ssh-and-terminal.md)
- Next: [Kiste Stream](https://docs.kiste.run/api/stream.md)