# REST API: Shares

> The 9 operations of the area Shares, with parameters, bodies and responses.

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

**Responses**

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

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

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

**Responses**

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

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/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.

**Parameters**

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

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

**Responses**

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

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

**Parameters**

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

**Responses**

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

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

**Parameters**

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

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

**Responses**

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

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

**Parameters**

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

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

**Responses**

- 204

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

**Parameters**

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

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

**Responses**

- 204

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

**Responses**

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

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

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

**Responses**

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

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).