# REST-API: Files

> Die 15 Operationen des Bereichs Files, mit Parametern, Bodys und Antworten.

Source: https://pithyx.org/de/docs/reference/api/files/
Markdown: https://pithyx.org/de/docs/reference/api/files.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/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](https://pithyx.org/de/docs/reference/errors/).

## 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](https://pithyx.org/de/docs/reference/api/schemas/#fileentry)

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/files/{shareId}/entry

**Parameter**

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

**Antworten**

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

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/files/{shareId}/folders

**Parameter**

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

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

**Antworten**

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

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/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](https://pithyx.org/de/docs/reference/api/schemas/#folderpage)

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/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](https://pithyx.org/de/docs/reference/api/schemas/#renamerequest)

**Antworten**

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

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/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](https://pithyx.org/de/docs/reference/errors/).

## 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](https://pithyx.org/de/docs/reference/api/schemas/#thumbnailrequest)

**Antworten**

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

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/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](https://pithyx.org/de/docs/reference/api/schemas/#trashpage)

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/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](https://pithyx.org/de/docs/reference/api/schemas/#trashitemsrequest)

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

## 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](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/).

## 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](https://pithyx.org/de/docs/reference/api/schemas/#trashitemsrequest)

**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/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](https://pithyx.org/de/docs/reference/api/schemas/#fileversionlist)

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/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](https://pithyx.org/de/docs/reference/api/schemas/#fileversionrestorerequest)

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

## POST /api/files/operations

Starts copying, moving or deleting as a job and answers 202 with it; follow it on jobs/<id>. 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](https://pithyx.org/de/docs/reference/api/schemas/#fileoperationrequest)

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