# REST-API: Apps

> Die 17 Operationen des Bereichs Apps, mit Parametern, Bodys und Antworten.

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

Erzeugt aus dem OpenAPI-Dokument des Daemons. Konventionen, Anmeldung, der CSRF-Header und der WebSocket stehen unter [API](https://pithyx.org/de/docs/developers/daemon/api/).

## GET /api/apps

Administrators only. Every installed app with its manifest, permissions, uid and state, and the app pool. The topic apps/admin carries the same and its changes.

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PATCH /api/apps/{appId}

Administrators only. Enables or disables an app. A disabled app keeps its data and grants, but nobody can open it, its frontend is not served and its tokens end.

**Parameter**

| Name    | Ort  | Typ    | Pflicht | Beschreibung |
| ------- | ---- | ------ | ------- | ------------ |
| `appId` | path | string | ja      |              |

**Anfrage-Body**: `application/json`: [UpdateAppRequest](https://pithyx.org/de/docs/reference/api/schemas/#updateapprequest)

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## DELETE /api/apps/{appId}

Administrators only. Removes an app as a job and answers 202 with it: data=keep removes its frontends and keeps its data on the app pool for a later install of the same app, data=delete destroys its dataset with every snapshot. Its grants go either way.

**Parameter**

| Name    | Ort   | Typ    | Pflicht | Beschreibung |
| ------- | ----- | ------ | ------- | ------------ |
| `appId` | path  | string | ja      |              |
| `data`  | query | string | ja      |              |

**Antworten**

- 202: `application/json`: [Job](https://pithyx.org/de/docs/reference/api/schemas/#job)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## GET /api/apps/{appId}/grants

Administrators only. Who may use an installed third-party app: the grants of users and groups on app:<id> (the built-in group users stands for everybody) and every user's result.

**Parameter**

| Name    | Ort  | Typ    | Pflicht | Beschreibung |
| ------- | ---- | ------ | ------- | ------------ |
| `appId` | path | string | ja      |              |

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PUT /api/apps/{appId}/grants

Administrators only. Replaces the grants of users and groups on the app, each with level allow; without any, only administrators use it. Applies at once and is pushed to the users' desktops.

**Parameter**

| Name    | Ort  | Typ    | Pflicht | Beschreibung |
| ------- | ---- | ------ | ------- | ------------ |
| `appId` | path | string | ja      |              |

**Anfrage-Body**: `application/json`: [AppGrantsRequest](https://pithyx.org/de/docs/reference/api/schemas/#appgrantsrequest)

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## GET /api/apps/{appId}/icon

The icon of an app the user may use (any app for administrators), served with Content-Security-Policy: default-src 'none'; sandbox.

**Parameter**

| Name    | Ort  | Typ    | Pflicht | Beschreibung |
| ------- | ---- | ------ | ------- | ------------ |
| `appId` | path | string | ja      |              |

**Antworten**

- 200: `image/svg+xml`: string (byte)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PUT /api/apps/{appId}/log-level

Administrators only. Switches the app's debug log entries on (debug) or off (info, the default); info, warn and error always reach the Log Center. The topic apps carries the level to the app's windows.

**Parameter**

| Name    | Ort  | Typ    | Pflicht | Beschreibung |
| ------- | ---- | ------ | ------- | ------------ |
| `appId` | path | string | ja      |              |

**Anfrage-Body**: `application/json`: [AppLogLevelRequest](https://pithyx.org/de/docs/reference/api/schemas/#apploglevelrequest)

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PUT /api/apps/{appId}/permissions

Administrators only. Grants or revokes permissions the app's manifest asks for (app.permission.not_requested for any other); the listed ones change, the others stay. A revoked permission stays revoked across updates. Users' windows of the app learn it with their next token (A11).

**Parameter**

| Name    | Ort  | Typ    | Pflicht | Beschreibung |
| ------- | ---- | ------ | ------- | ------------ |
| `appId` | path | string | ja      |              |

**Anfrage-Body**: `application/json`: [AppPermissionsRequest](https://pithyx.org/de/docs/reference/api/schemas/#apppermissionsrequest)

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## POST /api/apps/{appId}/rollback

Administrators only. Goes back to the version before the app's last update as a job: the app's dataset returns to the snapshot of that update, so its data goes back too, and the previous version runs again (app.app.no_previous without one).

**Parameter**

| Name    | Ort  | Typ    | Pflicht | Beschreibung |
| ------- | ---- | ------ | ------- | ------------ |
| `appId` | path | string | ja      |              |

**Antworten**

- 202: `application/json`: [Job](https://pithyx.org/de/docs/reference/api/schemas/#job)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PUT /api/apps/{appId}/storage/{storageId}

Administrators only. Maps an existing folder of a shared folder to a storage request of the app's manifest, replacing an earlier mapping: read-only, or read and write when the request asks for it (app.mapping.invalid otherwise). The folder keeps its rights, snapshots and backups and survives an uninstall.

**Parameter**

| Name        | Ort  | Typ    | Pflicht | Beschreibung |
| ----------- | ---- | ------ | ------- | ------------ |
| `appId`     | path | string | ja      |              |
| `storageId` | path | string | ja      |              |

**Anfrage-Body**: `application/json`: [AppStorageMappingRequest](https://pithyx.org/de/docs/reference/api/schemas/#appstoragemappingrequest)

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## DELETE /api/apps/{appId}/storage/{storageId}

Administrators only. Removes the folder mapped to a storage request of the app; the folder itself stays.

**Parameter**

| Name        | Ort  | Typ    | Pflicht | Beschreibung |
| ----------- | ---- | ------ | ------- | ------------ |
| `appId`     | path | string | ja      |              |
| `storageId` | path | string | ja      |              |

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## POST /api/apps/{appId}/tokens

A token for an app the signed-in user may use (any app for administrators; app.app.not_found otherwise), bound to the user, this session, the app and the window instance, valid 5 minutes. kind host is for the daemon's API for apps (/api/app/**) and stays in the desktop; kind backend is for the app's backend (app.backend.missing without one). Needs the session cookie and the CSRF header; ask again before expiresAt.

**Parameter**

| Name    | Ort  | Typ    | Pflicht | Beschreibung |
| ------- | ---- | ------ | ------- | ------------ |
| `appId` | path | string | ja      |              |

**Anfrage-Body**: `application/json`: [AppTokenRequest](https://pithyx.org/de/docs/reference/api/schemas/#apptokenrequest)

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PUT /api/apps/{appId}/update-policy

Administrators only. The app's own update policy (automatic, notify, none), or null to follow the box's.

**Parameter**

| Name    | Ort  | Typ    | Pflicht | Beschreibung |
| ------- | ---- | ------ | ------- | ------------ |
| `appId` | path | string | ja      |              |

**Anfrage-Body**: `application/json`: [AppUpdatePolicyRequest](https://pithyx.org/de/docs/reference/api/schemas/#appupdatepolicyrequest)

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PUT /api/apps/packages

Administrators only. Streams an app package (<id>-<version>.pithyxapp, a gzip-compressed tar archive) as the raw body, at most 256 MB with 512 MB of files. Unpacks and checks it (archive, layout, manifest, icon; ids under org.pithyx.* are refused) and keeps it for 15 minutes for its installation by the same administrator. Answers with what installing it would do, including the permission changes of an update.

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## GET /api/apps/packages/{packageId}

Administrators only. The check result of an uploaded package again, while it is kept (app.package.not_found otherwise).

**Parameter**

| Name        | Ort  | Typ    | Pflicht | Beschreibung |
| ----------- | ---- | ------ | ------- | ------------ |
| `packageId` | path | string | ja      |              |

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## DELETE /api/apps/packages/{packageId}

Administrators only. Discards an uploaded package without installing it.

**Parameter**

| Name        | Ort  | Typ    | Pflicht | Beschreibung |
| ----------- | ---- | ------ | ------- | ------------ |
| `packageId` | path | string | ja      |              |

**Antworten**

- 204

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## POST /api/apps/packages/{packageId}/install

Administrators only. Installs or updates the app from an uploaded package as a job and answers 202 with it. The first app needs pool, the pool for every app's data; access (everybody by default) decides who may use a newly installed app. An update takes a snapshot of the app's dataset first and returns to it when a step fails.

**Parameter**

| Name        | Ort  | Typ    | Pflicht | Beschreibung |
| ----------- | ---- | ------ | ------- | ------------ |
| `packageId` | path | string | ja      |              |

**Anfrage-Body**: `application/json`: [InstallAppRequest](https://pithyx.org/de/docs/reference/api/schemas/#installapprequest)

**Antworten**

- 202: `application/json`: [Job](https://pithyx.org/de/docs/reference/api/schemas/#job)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).