REST API: App API
Generated from the daemon’s OpenAPI document. Conventions, sign-in, the CSRF header and the WebSocket are on API.
GET /api/app-files/content
Section titled “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.
GET /api/app/directory/groups
Section titled “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[]
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/app/directory/users
Section titled “GET /api/app/directory/users”Every active user of the box with its groups. Needs the permission directory.read.
Responses
- 200:
application/json: DirectoryUser[]
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/app/files/content
Section titled “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.
PUT /api/app/files/content
Section titled “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
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/app/files/entry
Section titled “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
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/files/folders
Section titled “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
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/files/handles
Section titled “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
Responses
- 204
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/app/files/list
Section titled “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
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/files/operations
Section titled “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/
Request body: application/json: AppFileOperationRequest
Responses
- 202:
application/json: Job
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/files/rename
Section titled “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
Responses
- 200:
application/json: AppFileEntry
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/app/files/shares
Section titled “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[]
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/app/files/trash
Section titled “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
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/files/trash/delete
Section titled “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
Responses
- 202:
application/json: Job
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/files/trash/empty
Section titled “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
Responses
- 202:
application/json: Job
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/files/trash/restore
Section titled “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
Responses
- 202:
application/json: Job
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/files/url
Section titled “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
Responses
- 200:
application/json: AppFileUrl
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/app/files/versions
Section titled “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
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/files/versions/restore
Section titled “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
Responses
- 202:
application/json: Job
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/jobs/{id}/cancel
Section titled “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.
POST /api/app/logs
Section titled “POST /api/app/logs”Stores log entries of the token’s app for its user, as source app/
Request body: application/json: AppLogBatch
Responses
- 200:
application/json: AppLogResult
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/app/notifications
Section titled “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
Responses
- 201:
application/json: Notification
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/app/storage
Section titled “GET /api/app/storage”The keys the token’s app stored for its user.
Responses
- 200:
application/json: AppStorageKeys
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/app/storage/value
Section titled “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
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/app/storage/value
Section titled “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
Responses
- 204
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
DELETE /api/app/storage/value
Section titled “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.
POST /api/app/tickets
Section titled “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
Responses
- 200:
application/json: AppTicket
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.