# REST-API: Shares

> Die 9 Operationen des Bereichs Shares, mit Parametern, Bodys und Antworten.

Source: https://pithyx.org/de/docs/reference/api/shares/
Markdown: https://pithyx.org/de/docs/reference/api/shares.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/shares

The shares the user can use, with the user's access. Administrators get every share and its path on the host. The shares/list topic says when the list may have changed.

**Antworten**

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

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

Administrators only, and only on a development machine (fs.share.folder_dev_only elsewhere). Registers an existing folder on the host as a share; nobody but administrators has access until it is granted. Shared folders are otherwise created as datasets with POST /api/shares/plans.

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

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PATCH /api/shares/{shareId}

Administrators only. Changes the name shown, the description and whether SMB and SFTP offer the share (and whether SMB clients must encrypt); the folder and the dataset stay where they are.

**Parameter**

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

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

**Antworten**

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

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/shares/{shareId}/grants

Administrators only. The grants of users and groups on the share (read or readWrite) and every user with the access it ends up with: the union of its own grants and those of its groups, read and write for administrators, nothing while deactivated.

**Parameter**

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

**Antworten**

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

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/shares/{shareId}/grants

Administrators only. Replaces every grant of users and groups on the share. Applies to the next request, on disk (the share's Linux groups) and over SMB and SFTP.

**Parameter**

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

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

**Antworten**

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

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/shares/{shareId}/restore-points

Administrators only. Switches the shared folder's daily restore points (snapshots of its dataset kept 7 days) on or off. A folder share without a dataset answers fs.share.no_dataset.

**Parameter**

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

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

**Antworten**

- 204

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/shares/{shareId}/trash

Administrators only. Days the recycle bin keeps deleted items (0 to 3650; 0 keeps them until emptied). Applies to items already in the bin.

**Parameter**

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

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

**Antworten**

- 204

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/shares/details

Administrators only. Every share with its description, dataset, used and available space, quota, how many users may read or write and its SMB and SFTP settings.

**Antworten**

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

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/shares/plans

Administrators only. Returns the exact commands of creating a shared folder as a dataset (share.create) or deleting one (share.delete: keep its data, or destroy its dataset with every snapshot listed), with a plan id to run them with POST /api/storage/plans/{planId}/run. Runs nothing.

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

**Antworten**

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

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).