REST-API: Files

Erzeugt aus dem OpenAPI-Dokument des Daemons. Konventionen, Anmeldung, der CSRF-Header und der WebSocket stehen unter API.

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.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja
path	query	string	ja
inline	query	boolean	nein

Antworten

• 200

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja
path	query	string	ja
overwrite	query	boolean	nein

Antworten

• 201: application/json: FileEntry

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

GET /api/files/{shareId}/entry

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja
path	query	string	ja

Antworten

• 200: application/json: FileEntry

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

POST /api/files/{shareId}/folders

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja

Anfrage-Body: application/json: NewFolderRequest

Antworten

• 201: application/json: FileEntry

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja
path	query	string	nein
sort	query	string	nein
order	query	string	nein
limit	query	integer (int32)	nein
cursor	query	string	nein

Antworten

• 200: application/json: FolderPage

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

POST /api/files/{shareId}/rename

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

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja

Anfrage-Body: application/json: RenameRequest

Antworten

• 200: application/json: FileEntry

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja
path	query	string	ja
size	query	string	nein
v	query	string	nein

Antworten

• 200

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja

Anfrage-Body: application/json: ThumbnailRequest

Antworten

• 200: application/json: ThumbnailStates

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja
cursor	query	string	nein
limit	query	integer (int32)	nein

Antworten

• 200: application/json: TrashPage

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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

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

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja

Anfrage-Body: application/json: TrashItemsRequest

Antworten

• 202: application/json: Job

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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

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

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja

Antworten

• 202: application/json: Job

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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

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

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja

Anfrage-Body: application/json: TrashItemsRequest

Antworten

• 202: application/json: Job

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja
path	query	string	ja

Antworten

• 200: application/json: FileVersionList

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
shareId	path	integer (int64)	ja

Anfrage-Body: application/json: FileVersionRestoreRequest

Antworten

• 202: application/json: Job

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.

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.

Anfrage-Body: application/json: FileOperationRequest

Antworten

• 202: application/json: Job

Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.