Skip to content
Pithyx

REST API: Files

View as Markdown

Generated from the daemon’s OpenAPI document. Conventions, sign-in, the CSRF header and the WebSocket are on API.

GET /api/files/{shareId}/content

Section titled “GET /api/files/{shareId}/content”

The file’s content with range requests (206, 416), ETag and Last-Modified. Sent as an attachment unless inline=true; always with Content-Security-Policy: sandbox, so a file is never run as part of the desktop.

Parameters

Name In Type Required Description
shareId path integer (int64) yes
path query string yes
inline query boolean no

Responses

  • 200

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

PUT /api/files/{shareId}/content

Section titled “PUT /api/files/{shareId}/content”

Streams the request body into the file at path (the body is the raw content). The file appears only when the body is complete. Fails with fs.entry.exists if the name is taken, unless overwrite=true.

Parameters

Name In Type Required Description
shareId path integer (int64) yes
path query string yes
overwrite query boolean no

Responses

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

GET /api/files/{shareId}/entry

Section titled “GET /api/files/{shareId}/entry”

Parameters

Name In Type Required Description
shareId path integer (int64) yes
path query string yes

Responses

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

POST /api/files/{shareId}/folders

Section titled “POST /api/files/{shareId}/folders”

Parameters

Name In Type Required Description
shareId path integer (int64) yes

Request body: application/json: NewFolderRequest

Responses

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

GET /api/files/{shareId}/list

Section titled “GET /api/files/{shareId}/list”

One page of a folder. Paths are relative to the share with / as separator; “.” and “..” are refused. sort is name (natural order, ignoring case), size or modified, order asc or desc; pass nextCursor as cursor for the next page. Subscribe to topic for live changes of the folder.

Parameters

Name In Type Required Description
shareId path integer (int64) yes
path query string no
sort query string no
order query string no
limit query integer (int32) no
cursor query string no

Responses

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

POST /api/files/{shareId}/rename

Section titled “POST /api/files/{shareId}/rename”

Renames a file or folder within its folder. An existing name is never replaced (fs.entry.exists).

Parameters

Name In Type Required Description
shareId path integer (int64) yes

Request body: application/json: RenameRequest

Responses

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

GET /api/files/{shareId}/thumbnail

Section titled “GET /api/files/{shareId}/thumbnail”

A cached WebP thumbnail of the file as it is now, with the same access check as its download; fs.thumbnail.not_found when there is none (yet). v is the version from the thumbnail state and only makes the URL change with the file.

Parameters

Name In Type Required Description
shareId path integer (int64) yes
path query string yes
size query string no
v query string no

Responses

  • 200

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

POST /api/files/{shareId}/thumbnails

Section titled “POST /api/files/{shareId}/thumbnails”

Which of the named entries of a folder have a thumbnail (JPEG, PNG, WebP and GIF by content). Answers at once and renders nothing itself: missing thumbnails are queued and announced on the returned topic. Only ask for entries on screen.

Parameters

Name In Type Required Description
shareId path integer (int64) yes

Request body: application/json: ThumbnailRequest

Responses

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

GET /api/files/{shareId}/trash

Section titled “GET /api/files/{shareId}/trash”

The share’s recycle bin, newest first, with the share’s retention. Deleting a file or folder moves it here unless the delete is permanent.

Parameters

Name In Type Required Description
shareId path integer (int64) yes
cursor query string no
limit query integer (int32) no

Responses

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

POST /api/files/{shareId}/trash/delete

Section titled “POST /api/files/{shareId}/trash/delete”

Starts a job that deletes the given recycle bin items for good.

Parameters

Name In Type Required Description
shareId path integer (int64) yes

Request body: application/json: TrashItemsRequest

Responses

  • 202: application/json: Job

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

POST /api/files/{shareId}/trash/empty

Section titled “POST /api/files/{shareId}/trash/empty”

Starts a job that deletes everything in the share’s recycle bin for good.

Parameters

Name In Type Required Description
shareId path integer (int64) yes

Responses

  • 202: application/json: Job

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

POST /api/files/{shareId}/trash/restore

Section titled “POST /api/files/{shareId}/trash/restore”

Starts a job that puts items back where they were, recreating missing folders. onConflict defaults to rename.

Parameters

Name In Type Required Description
shareId path integer (int64) yes

Request body: application/json: TrashItemsRequest

Responses

  • 202: application/json: Job

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

GET /api/files/{shareId}/versions

Section titled “GET /api/files/{shareId}/versions”

Earlier versions of a file or folder from the snapshots of the share’s dataset, newest first; also for an entry deleted since. A file is listed once per distinct content and not while it equals the current file. Empty when the share is not on a ZFS dataset. Needs read access.

Parameters

Name In Type Required Description
shareId path integer (int64) yes
path query string yes

Responses

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

POST /api/files/{shareId}/versions/restore

Section titled “POST /api/files/{shareId}/versions/restore”

Starts a job that copies a version back: next to the current entry as “name (version yyyy-MM-dd HH.mm UTC)”, or over it with overwrite=true (files are replaced, folders merged). Needs read-write access.

Parameters

Name In Type Required Description
shareId path integer (int64) yes

Request body: application/json: FileVersionRestoreRequest

Responses

  • 202: application/json: Job

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.

POST /api/files/operations

Section titled “POST /api/files/operations”

Starts copying, moving or deleting as a job and answers 202 with it; follow it on jobs/. Access is checked now: read on the sources for copy, write on the sources for move and delete, write on the target. Deleting moves to the share’s recycle bin unless permanent is true. onConflict decides about names that exist in the target: fail (default), skip, overwrite (folders are merged) or rename.

Request body: application/json: FileOperationRequest

Responses

  • 202: application/json: Job

Any failure answers with problem details (application/problem+json) and a stable code from the error reference.