# REST API: App API

> The 27 operations of the area App API, with parameters, bodies and responses.

Source: https://pithyx.org/docs/reference/api/app-api/
Markdown: https://pithyx.org/docs/reference/api/app-api.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/app-files/content

The file of a file token from POST /api/app/files/url, with range requests, for 5 minutes; inline for images, audio, video and PDF, an attachment with download=true. Needs no session cookie and no Authorization header: the token is the query parameter pithyx-token.

**Parameters**

| Name       | In    | Type    | Required | Description |
| ---------- | ----- | ------- | -------- | ----------- |
| `download` | query | boolean | no       |             |

**Responses**

- 200

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/app/directory/groups

Every group of the box but the built-in one. Needs the permission directory.read.

**Responses**

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

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/app/directory/users

Every active user of the box with its groups. Needs the permission directory.read.

**Responses**

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

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/app/files/content

The content of a file in a location, with range requests. A shared folder needs files.shares and files.read.

**Parameters**

| Name      | In    | Type   | Required | Description |
| --------- | ----- | ------ | -------- | ----------- |
| `share`   | query | string | no       |             |
| `storage` | query | string | no       |             |
| `path`    | query | string | no       |             |

**Responses**

- 200

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/app/files/content

Streams the body into the file at path (fs.entry.exists unless overwrite=true). A shared folder needs files.shares and files.write, a storage request a mapping for reading and writing; the user needs write access either way.

**Parameters**

| Name        | In    | Type    | Required | Description |
| ----------- | ----- | ------- | -------- | ----------- |
| `share`     | query | string  | no       |             |
| `storage`   | query | string  | no       |             |
| `path`      | query | string  | no       |             |
| `overwrite` | query | boolean | no       |             |

**Responses**

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

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/app/files/entry

A file or folder in a location, with whether the app may write it.

**Parameters**

| Name      | In    | Type   | Required | Description |
| --------- | ----- | ------ | -------- | ----------- |
| `share`   | query | string | no       |             |
| `storage` | query | string | no       |             |
| `path`    | query | string | no       |             |

**Responses**

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

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/app/files/folders

Creates a folder in a location, with the same rules as writing a file.

**Parameters**

| Name      | In    | Type   | Required | Description |
| --------- | ----- | ------ | -------- | ----------- |
| `share`   | query | string | no       |             |
| `storage` | query | string | no       |             |
| `path`    | query | string | no       |             |

**Responses**

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

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/app/files/handles

The desktop tells the daemon that the user handed one file of a shared folder to this window (a pick, a save dialog or Open with). The window may then read it with files.read, or also write it with files.write, without files.shares; only this exact path, and the user's own rights still apply. Only the desktop calls this, after a dialog the user answered.

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

**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/app/files/list

One page of a folder in a shared folder (share, needs files.shares) or a storage request of the manifest (storage), as the user and with the user's rights. Parameters as for GET /api/files/{shareId}/list.

**Parameters**

| Name      | In    | Type            | Required | Description |
| --------- | ----- | --------------- | -------- | ----------- |
| `share`   | query | string          | no       |             |
| `storage` | query | string          | no       |             |
| `path`    | query | string          | no       |             |
| `sort`    | query | string          | no       |             |
| `order`   | query | string          | no       |             |
| `limit`   | query | integer (int32) | no       |             |
| `cursor`  | query | string          | no       |             |

**Responses**

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

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/app/files/operations

As POST /api/files/operations, with each place a shared folder (share, needs files.shares, files.read where entries are copied or moved from and files.write where anything changes) or a storage request (storage, needs a mapping for reading and writing where anything changes). Follow the job on jobs/<id>.

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

**Responses**

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

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/app/files/rename

Renames a file or folder within its folder; an existing name is never replaced. Needs the permissions of writing: files.shares and files.write for a shared folder.

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

**Responses**

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

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/app/files/shares

The shared folders the user can use, without their place on the host. Needs the permission files.shares.

**Responses**

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

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/app/files/trash

The recycle bin of a shared folder, as GET /api/files/{shareId}/trash. Needs files.shares and files.read.

**Parameters**

| Name     | In    | Type            | Required | Description |
| -------- | ----- | --------------- | -------- | ----------- |
| `share`  | query | string          | no       |             |
| `cursor` | query | string          | no       |             |
| `limit`  | query | integer (int32) | no       |             |

**Responses**

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

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/app/files/trash/delete

Starts a job that deletes recycle bin items for good. Needs files.shares and files.write.

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

**Responses**

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

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/app/files/trash/empty

Starts a job that deletes everything in the recycle bin for good. Needs files.shares and files.write.

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

**Responses**

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

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/app/files/trash/restore

Starts a job that puts recycle bin items back. Needs files.shares and files.write.

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

**Responses**

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

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/app/files/url

A URL that reads one file with range requests for 5 minutes, without the desktop session. Needs the permissions of reading the file.

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

**Responses**

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

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/app/files/versions

Earlier versions of a file or folder of a shared folder, as GET /api/files/{shareId}/versions. Needs files.shares and files.read.

**Parameters**

| Name    | In    | Type   | Required | Description |
| ------- | ----- | ------ | -------- | ----------- |
| `share` | query | string | no       |             |
| `path`  | query | string | no       |             |

**Responses**

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

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/app/files/versions/restore

Starts a job that copies a version back, as POST /api/files/{shareId}/versions/restore. Needs files.shares, files.read and files.write.

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

**Responses**

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

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/app/jobs/{id}/cancel

Cancels a job the token's app started for the user; any other job is jobs.job.not_found.

**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/).

## POST /api/app/logs

Stores log entries of the token's app for its user, as source app/<id>. Debug entries only while an administrator switched debug logging on for the app; at most 100 entries per request within the app's rate limit.

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

**Responses**

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

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/app/notifications

A notification of the token's app for its user, with at most two buttons, data that comes back with a click and a tag that replaces the app's earlier notification with the same tag. Needs the permission notifications.

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

**Responses**

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

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/app/storage

The keys the token's app stored for its user.

**Responses**

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

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/app/storage/value

A value the token's app stored for its user under key, or null.

**Parameters**

| Name  | In    | Type   | Required | Description |
| ----- | ----- | ------ | -------- | ----------- |
| `key` | query | string | no       |             |

**Responses**

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

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/app/storage/value

Stores a value of the token's app for its user: keys of 1 to 128 characters, values of at most 64 KB of JSON, at most 1 MB per app and user (app.storage.too_large).

**Parameters**

| Name  | In    | Type   | Required | Description |
| ----- | ----- | ------ | -------- | ----------- |
| `key` | query | string | no       |             |

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

**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/).

## DELETE /api/app/storage/value

Removes a value of the token's app for its user; a missing one is no error.

**Parameters**

| Name  | In    | Type   | Required | Description |
| ----- | ----- | ------ | -------- | ----------- |
| `key` | query | string | no       |             |

**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/app/tickets

A one-time ticket for one WebSocket to an endpoint of the app's backend (app.backend.endpoint_unknown for a name the manifest does not declare), valid 30 seconds, bound to what the host token is bound to.

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

**Responses**

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

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