REST API: Shares
Generated from the daemon’s OpenAPI document. Conventions, sign-in, the CSRF header and the WebSocket are on API.
GET /api/shares
Section titled “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[]
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/shares
Section titled “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
Responses
- 201:
application/json: ShareInfo
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PATCH /api/shares/{shareId}
Section titled “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
Responses
- 200:
application/json: ShareDetails
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/shares/{shareId}/grants
Section titled “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
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/shares/{shareId}/grants
Section titled “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
Responses
- 200:
application/json: ShareGrants
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/shares/{shareId}/restore-points
Section titled “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
Responses
- 204
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/shares/{shareId}/trash
Section titled “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
Responses
- 204
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/shares/details
Section titled “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[]
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/shares/plans
Section titled “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
Responses
- 200:
application/json: StoragePlanPreview
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.