# REST API: Desktop

> The 10 operations of the area Desktop, with parameters, bodies and responses.

Source: https://pithyx.org/docs/reference/api/desktop/
Markdown: https://pithyx.org/docs/reference/api/desktop.md

Generated from the daemon's OpenAPI document. Conventions, sign-in, the CSRF header and the WebSocket are on [API](https://pithyx.org/docs/developers/daemon/api/).

## GET /api/desktop

**Responses**

- 200: `application/json`: [DesktopState](https://pithyx.org/docs/reference/api/schemas/#desktopstate)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## PUT /api/desktop/appearance

Saves the accent color and the wallpaper of the signed-in user, for every device. GET /api/desktop returns them.

**Request body**: `application/json`: [Appearance](https://pithyx.org/docs/reference/api/schemas/#appearance)

**Responses**

- 204

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## GET /api/desktop/devices

**Responses**

- 200: `application/json`: [DeviceLayout](https://pithyx.org/docs/reference/api/schemas/#devicelayout)[]

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## GET /api/desktop/items

**Responses**

- 200: `application/json`: [DesktopItem](https://pithyx.org/docs/reference/api/schemas/#desktopitem)[]

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## POST /api/desktop/items

Creates an item. The answer is 201 with the item, its URL as Location and its version as ETag.

**Request body**: `application/json`: [NewDesktopItem](https://pithyx.org/docs/reference/api/schemas/#newdesktopitem)

**Responses**

- 201: `application/json`: [DesktopItem](https://pithyx.org/docs/reference/api/schemas/#desktopitem)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## PATCH /api/desktop/items/{id}

Changes one item; fields left out stay. Send the item's version from GET /api/desktop/items or the ETag of its last change as If-Match: "n". If the item changed in between (for example on another device), the answer is 412 with desktop.item.conflict and the current version in params.version. Without If-Match the change is unconditional. The new version comes back as ETag.

**Parameters**

| Name       | In     | Type            | Required | Description |
| ---------- | ------ | --------------- | -------- | ----------- |
| `id`       | path   | integer (int64) | yes      |             |
| `If-Match` | header | string          | no       |             |

**Request body**: `application/json`: [DesktopItemChange](https://pithyx.org/docs/reference/api/schemas/#desktopitemchange)

**Responses**

- 200: `application/json`: [DesktopItem](https://pithyx.org/docs/reference/api/schemas/#desktopitem)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## DELETE /api/desktop/items/{id}

Deletes one item. Deleting an item that does not exist (any more) also answers 204.

**Parameters**

| Name | In   | Type            | Required | Description |
| ---- | ---- | --------------- | -------- | ----------- |
| `id` | path | integer (int64) | yes      |             |

**Responses**

- 204

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## PUT /api/desktop/layout

Saves this device's layout. Send the version from GET /api/desktop or the ETag of the last save as If-Match: "n". If another tab saved in between, the answer is 412 with desktop.layout.conflict and the current version in params.version. Without If-Match the save is unconditional. The new version comes back as ETag.

**Parameters**

| Name       | In     | Type   | Required | Description |
| ---------- | ------ | ------ | -------- | ----------- |
| `If-Match` | header | string | no       |             |

**Request body**: `application/json`: [JsonElement](https://pithyx.org/docs/reference/api/schemas/#jsonelement)

**Responses**

- 204

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## POST /api/desktop/layout/copy

**Request body**: `application/json`: [CopyLayoutRequest](https://pithyx.org/docs/reference/api/schemas/#copylayoutrequest)

**Responses**

- 200: `application/json`: [SavedLayout](https://pithyx.org/docs/reference/api/schemas/#savedlayout)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## PUT /api/desktop/preferences/{appId}

**Parameters**

| Name    | In   | Type   | Required | Description |
| ------- | ---- | ------ | -------- | ----------- |
| `appId` | path | string | yes      |             |

**Request body**: `application/json`: [WindowPreferenceRequest](https://pithyx.org/docs/reference/api/schemas/#windowpreferencerequest)

**Responses**

- 204

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).