# REST API: Storage

> The 19 operations of the area Storage, with parameters, bodies and responses.

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

Administrators only. Current storage alerts with the caller's mute flags, and the SMART state of every disk; live through the storage/alerts topic.

**Responses**

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

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/storage/alerts/{key}/mute

Administrators only. Hides a current alert for the caller until it goes away or becomes more severe. Alerts cannot be deleted.

**Parameters**

| Name  | In   | Type   | Required | Description |
| ----- | ---- | ------ | -------- | ----------- |
| `key` | path | string | yes      |             |

**Responses**

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

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

## DELETE /api/storage/alerts/{key}/mute

Administrators only. Shows a muted alert again.

**Parameters**

| Name  | In   | Type   | Required | Description |
| ----- | ---- | ------ | -------- | ----------- |
| `key` | path | string | yes      |             |

**Responses**

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

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/storage/disks

Administrators only. Every disk with the disk guard's verdict: whether a new pool may use it, and why not.

**Responses**

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

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/storage/import/scan

Administrators only. Looks for pools on the disks that are not imported (zpool import, which reads every disk's labels and may wake a sleeping disk) and returns each with its layout and the disk guard's import verdict. Imports nothing; importing is the plan pool.import.readonly, then pool.import.

**Responses**

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

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

Administrators only. Probes the chosen disks, asks the disk guard and returns the exact commands of a destructive storage action, with a plan id to run them. Runs nothing.

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

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

## POST /api/storage/plans/{planId}/run

Administrators only. Runs a plan exactly as it was shown, as a job; the disk guard checks every disk again right before each command. A plan runs once and expires after 10 minutes.

**Parameters**

| Name     | In   | Type   | Required | Description |
| -------- | ---- | ------ | -------- | ----------- |
| `planId` | path | string | 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/).

## GET /api/storage/pools

Administrators only. Pools with their vdevs, and datasets, as last read; live through the storage/pools topic.

**Responses**

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

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/storage/pools/{pool}/scrub

Administrators only. Starts a scrub of the pool, or resumes a paused one, and returns at once; progress arrives on storage/pools.

**Parameters**

| Name   | In   | Type   | Required | Description |
| ------ | ---- | ------ | -------- | ----------- |
| `pool` | path | string | yes      |             |

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

## DELETE /api/storage/pools/{pool}/scrub

Administrators only. Stops the running scrub; the next one starts from the beginning.

**Parameters**

| Name   | In   | Type   | Required | Description |
| ------ | ---- | ------ | -------- | ----------- |
| `pool` | path | string | yes      |             |

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

## POST /api/storage/pools/{pool}/scrub/pause

Administrators only. Pauses the running scrub; starting it again resumes where it stopped.

**Parameters**

| Name   | In   | Type   | Required | Description |
| ------ | ---- | ------ | -------- | ----------- |
| `pool` | path | string | yes      |             |

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

Administrators only. Scrub schedules per pool and the SMART self-test schedules, with their last and next runs.

**Responses**

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

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/storage/schedules

Administrators only. Sets how often a pool is scrubbed or the disks run a self-test: off, weekly or monthly.

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

**Responses**

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

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/storage/snapshots

Administrators only. The snapshots of a dataset as last read, oldest first. pithyxKind is set for snapshots Pithyx took.

**Parameters**

| Name      | In    | Type   | Required | Description |
| --------- | ----- | ------ | -------- | ----------- |
| `dataset` | query | string | yes      |             |

**Responses**

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

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/storage/snapshots

Administrators only. Takes pithyx-manual-<utc> of the dataset now. Manual snapshots are never pruned by a schedule.

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

**Responses**

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

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/storage/snapshots/hold

Administrators only. Places the hold "pithyx" on the snapshot, so neither a schedule nor anyone else can destroy it.

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

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

## POST /api/storage/snapshots/release

Administrators only. Releases the hold "pithyx" of the snapshot. Holds of other tools stay.

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

**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/storage/snapshots/schedules

Administrators only. The hourly, daily, weekly and monthly schedules of a dataset; off with the default counts (24, 7, 4, 6) until saved.

**Parameters**

| Name      | In    | Type   | Required | Description |
| --------- | ----- | ------ | -------- | ----------- |
| `dataset` | query | string | yes      |             |

**Responses**

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

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/storage/snapshots/schedules

Administrators only. Saves the given schedules of a dataset. A schedule takes pithyx-<kind>-<utc> once per UTC hour, day, week (from Monday) or month and keeps its newest keep snapshots; it never deletes other snapshots, held ones or ones dated after the current time.

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

**Responses**

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

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