# REST API: Files

> The 15 operations of the area Files, with parameters, bodies and responses.

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

**Parameters**

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

**Responses**

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

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

**Parameters**

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

**Responses**

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

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

**Parameters**

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

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

**Responses**

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

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

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

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

**Responses**

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

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/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](https://pithyx.org/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.

**Parameters**

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

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

**Responses**

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

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

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

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

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

## 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**

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

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

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

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