---
layout: api
page_title: Volumes - HTTP API
description: |-
  The Nomad  `/volume` and `/volumes` endpoints query for and interact with Container Storage Interface (CSI) volumes and dynamic host volumes.
---

# Volumes HTTP API

The `/volume` and `/volumes` endpoints query for and interact with
Container Storage Interface (CSI) volumes and dynamic host volumes.

## List Volumes

This endpoint lists all volumes.

| Method | Path          | Produces           |
| ------ | ------------- | ------------------ |
| `GET`  | `/v1/volumes` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                                                 |
|------------------|--------------------------------------------------------------|
| `YES`            | `namespace:csi-list-volume`<br/>`namespace:host-volume-read` |

### Parameters

- `type` `(string: <required>)` - Specifies the type of volume to query. One of
  `csi` or `host`. The `host` value queries dynamic host volumes. Specify this
  as a query string parameter.

- `node_id` `(string: "")` - Specifies a string to filter volumes
  based on an Node ID prefix. Because the value is decoded to bytes,
  the prefix must have an even number of hexadecimal characters
  (0-9a-f). Specify this as a query string parameter.

- `plugin_id` `(string: "")` - Specifies a string to filter volumes
  based on a plugin ID prefix. Because the value is decoded to bytes,
  the prefix must have an even number of hexadecimal characters
  (0-9a-f). Specify this as a query string parameter.

- `next_token` `(string: "")` - This endpoint supports paging. The `next_token`
  parameter accepts a string which identifies the next expected volume. This
  value can be obtained from the `X-Nomad-NextToken` header from the previous
  response.

- `per_page` `(int: 0)` - Specifies a maximum number of volumes to return for
  this request. If omitted, the response is not paginated. The value of the
  `X-Nomad-NextToken` header of the last response can be used as the
  `next_token` of the next request to fetch additional pages.

- `filter` `(string: "")` - Specifies the [expression](/nomad/api-docs#filtering)
  used to filter the results. Consider using pagination or a query parameter to
  reduce resource used to serve the request.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/volumes?type=csi&node_id=foo&plugin_id=plugin-id1
```

### Sample Response for CSI Volumes

```json
[
  {
    "ID": "volume-id1",
    "ExternalID": "vol-abcdef",
    "Namespace": "default",
    "Name": "volume id1",
    "Topologies": [
      {
        "foo": "bar"
      }
    ],
    "AccessMode": "multi-node-single-writer",
    "AttachmentMode": "file-system",
    "CurrentReaders": 2,
    "CurrentWriters": 1,
    "Schedulable": true,
    "PluginID": "plugin-id1",
    "Provider": "ebs",
    "ControllerRequired": true,
    "ControllersHealthy": 3,
    "ControllersExpected": 3,
    "NodesHealthy": 15,
    "NodesExpected": 18,
    "ResourceExhausted": 0,
    "CreateIndex": 42,
    "ModifyIndex": 64
  }
]
```

### Sample Response for dynamic host volumes

```json
[
  {
    "CapacityBytes": 1048576000,
    "CreateIndex": 42,
    "CreateTime": 1736191825846395400,
    "ID": "3735cc2c-cc64-11ef-89ed-bfb5b3bc38ea",
    "ModifyIndex": 64,
    "ModifyTime": 1736191825846395400,
    "Name": "example",
    "Namespace": "default",
    "NodeID": "5c5830d0-cc64-11ef-a293-4f03e55969ea",
    "NodePool": "default",
    "PluginID": "plugin-id1",
    "State": "ready"
  }
]
```

## Read CSI Volume

This endpoint reads information about a specific CSI volume.

| Method | Path                        | Produces           |
| ------ | --------------------------- | ------------------ |
| `GET`  | `/v1/volume/csi/:volume_id` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                |
| ---------------- | --------------------------- |
| `YES`            | `namespace:csi-read-volume` |

### Parameters

- `:volume_id` `(string: <required>)` - Specifies the ID of the
  volume. This must be the full ID. Specify this as part of the
  path.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/volume/csi/volume-id1
```

### Sample Response

```json
{
  "ID": "volume-id1",
  "Name": "volume id1",
  "Namespace": "default",
  "ExternalID": "vol-abcdef",
  "Topologies": [{ "foo": "bar" }],
  "AccessMode": "multi-node-single-writer",
  "AttachmentMode": "file-system",
  "RequestedCapabilities": [
    {
      "AccessMode": "single-node-writer",
      "AttachmentMode": "file-system"
    },
    {
      "AccessMode": "single-node-writer",
      "AttachmentMode": "block-device"
    }
  ],
  "Allocations": [
    {
      "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
      "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
      "Name": "example.cache[0]",
      "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
      "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
      "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",
      "RescheduleTracker": {
        "Events": [
          {
            "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
            "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",
            "RescheduleTime": 1517434161192946200,
            "Delay": "5000000000"
          }
        ]
      },
      "JobID": "example",
      "TaskGroup": "cache",
      "DesiredStatus": "run",
      "DesiredDescription": "",
      "ClientStatus": "running",
      "ClientDescription": "",
      "TaskStates": {
        "redis": {
          "State": "running",
          "FinishedAt": "0001-01-01T00:00:00Z",
          "LastRestart": "0001-01-01T00:00:00Z",
          "Restarts": 0,
          "StartedAt": "2017-07-25T23:36:26.106431265Z",
          "Failed": false,
          "Events": [
            {
              "Type": "Received",
              "Time": 1495747371795703800,
              "FailsTask": false,
              "RestartReason": "",
              "SetupError": "",
              "DriverError": "",
              "ExitCode": 0,
              "Signal": 0,
              "Message": "",
              "KillTimeout": 0,
              "KillError": "",
              "KillReason": "",
              "StartDelay": 0,
              "DownloadError": "",
              "ValidationError": "",
              "DiskLimit": 0,
              "FailedSibling": "",
              "VaultError": "",
              "TaskSignalReason": "",
              "TaskSignal": "",
              "DriverMessage": ""
            },
            {
              "Type": "Driver",
              "Time": 1495747371798867200,
              "FailsTask": false,
              "RestartReason": "",
              "SetupError": "",
              "DriverError": "",
              "ExitCode": 0,
              "Signal": 0,
              "Message": "",
              "KillTimeout": 0,
              "KillError": "",
              "KillReason": "",
              "StartDelay": 0,
              "DownloadError": "",
              "ValidationError": "",
              "DiskLimit": 0,
              "FailedSibling": "",
              "VaultError": "",
              "TaskSignalReason": "",
              "TaskSignal": "",
              "DriverMessage": "Downloading image redis:7"
            },
            {
              "Type": "Started",
              "Time": 1495747379525667800,
              "FailsTask": false,
              "RestartReason": "",
              "SetupError": "",
              "DriverError": "",
              "ExitCode": 0,
              "Signal": 0,
              "Message": "",
              "KillTimeout": 0,
              "KillError": "",
              "KillReason": "",
              "StartDelay": 0,
              "DownloadError": "",
              "ValidationError": "",
              "DiskLimit": 0,
              "FailedSibling": "",
              "VaultError": "",
              "TaskSignalReason": "",
              "TaskSignal": "",
              "DriverMessage": ""
            }
          ]
        }
      },
      "CreateIndex": 54,
      "ModifyIndex": 57,
      "CreateTime": 1495747371794276400,
      "ModifyTime": 1495747371794276400
    }
  ],
  "ReadAllocs": {
    "a8198d79-cfdb-6593-a999-1e9adabcba2e": null
  },
  "WriteAllocs": {},
  "Schedulable": true,
  "PluginID": "plugin-id1",
  "Provider": "ebs",
  "Version": "1.0.1",
  "ControllerRequired": true,
  "ControllersHealthy": 3,
  "ControllersExpected": 3,
  "NodesHealthy": 15,
  "NodesExpected": 18,
  "ResourceExhausted": 0,
  "CreateIndex": 42,
  "ModifyIndex": 64
}
```

## Register CSI Volume

This endpoint registers an external CSI volume with Nomad. The volume must exist
in the external storage provider. Refer to the [Create CSI Volume][] section for
details.

Making the same request again with a higher `RequestedCapacityMin` value
may trigger a [Volume Expansion][].

| Method | Path                        | Produces           |
| ------ | --------------------------- | ------------------ |
| `PUT`  | `/v1/volume/csi/:volume_id` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                 |
| ---------------- | ---------------------------- |
| `NO`             | `namespace:csi-write-volume`. <br/>`namespace:sentinel-override` if `PolicyOverride` set |

### Parameters

- `:volume_id` `(string: <required>)` - Specifies the ID of the
  volume. This must be the full ID. Specify this as part of the
  path.

- `Volumes` <code>([Volumes][csi-volume-spec]:</code> `<required>`) - Specifies
  the JSON definition of the CSI volume. You should include the ID field if you
  are updating an existing volume. Note that you must include the `NodeID` field
  for the register API.

- `PolicyOverride` `(bool: false)` - If set, Nomad overrides any soft mandatory
  Sentinel policies. This field allows creating a volume when it would be denied
  by policy.

### Sample Payload

```json
{
  "PolicyOverride": false,
  "Volumes": [
    {
      "ExternalID": "vol-abcdef",
      "ID": "volume-id1",
      "Name": "volume one",
      "Namespace": "default",
      "PluginID": "plugin-id1",
      "RequestedCapabilities": [
        {
          "AccessMode": "single-node-writer",
          "AttachmentMode": "file-system"
        },
        {
          "AccessMode": "single-node-writer",
          "AttachmentMode": "block-device"
        }
      ],
      "Secrets": {
        "password": "xyzzy"
      },
      "Topologies": [{ "foo": "bar" }]
    }
  ]
}
```

### Sample Request

```shell-session
$ curl \
    --request PUT \
    --data @payload.json \
    https://localhost:4646/v1/volume/csi/volume-id1
```

## Create CSI Volume

This endpoint creates a CSI volume in an external storage provider and registers
it with Nomad. Only CSI plugins that implement the
[Controller][csi_plugins_internals] interface with the `CREATE_DELETE_VOLUME`
capability support this endpoint.

Making the same request again with a higher `RequestedCapacityMin` value
may trigger a [Volume Expansion][].

| Method | Path                               | Produces           |
| ------ | ---------------------------------- | ------------------ |
| `PUT`  | `/v1/volume/csi/:volume_id/create` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                 |
| ---------------- | ---------------------------- |
| `NO`             | `namespace:csi-write-volume`. <br/>`namespace:sentinel-override` if `PolicyOverride` set |

### Parameters

- `:volume_id` `(string: <required>)` - Specifies the ID of the
  volume. This must be the full ID. Specify this as part of the
  path.

- `Volumes` <code>([Volumes][csi-volume-spec]:</code> `<required>`) - Specifies
  the JSON definition of the CSI volume. You should include the ID field if you
  are updating an existing volume. 

- `PolicyOverride` `(bool: false)` - If set, Nomad overrides any soft mandatory
  Sentinel policies. This field allows creating a volume when it would be denied
  by policy.

### Sample Payload

```json
{
  "PolicyOverride": false,
  "Volumes": [
    {
      "ID": "volume-id1",
      "Name": "volume one",
      "Namespace": "default",
      "PluginID": "plugin-id1",
      "MountOptions": {
        "FsType": "ext4",
        "MountFlags": ["ro", "noatime"],
      },
      "RequestedCapacityMin": 10737418240,
      "RequestedCapacityMax": 21474836480,
      "RequestedCapabilities": [
        {
          "AccessMode": "single-node-writer",
          "AttachmentMode": "file-system"
        },
        {
          "AccessMode": "single-node-writer",
          "AttachmentMode": "block-device"
        }
      ],
      "Secrets": {
        "password": "xyzzy"
      },
      "SnapshotID": "snap-12345",
      "Topologies": [{ "foo": "bar" }]
    }
  ]
}
```

### Sample Request

```shell-session
$ curl \
    --request PUT \
    --data @payload.json \
    https://localhost:4646/v1/volume/csi/volume-id1
```


## Deregister CSI Volume

This endpoint deregisters an external CSI volume from Nomad. It is an error to
deregister a volume that is in use.

| Method   | Path                        | Produces           |
| -------- | --------------------------- | ------------------ |
| `DELETE` | `/v1/volume/csi/:volume_id` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                 |
| ---------------- | ---------------------------- |
| `NO`             | `namespace:csi-write-volume` |

### Parameters

- `:volume_id` `(string: <required>)` - Specifies the ID of the
  volume. This must be the full ID. Specify this as part of the
  path.

- `force` `(bool: false)` - Force deregistration of the volume and immediately
  drop claims for terminal allocations. Returns an error if the volume has
  running allocations. This does not detach the volume from client nodes.
  Specify this as a query string parameter.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    https://localhost:4646/v1/volume/csi/volume-id1?force=false
```

## Delete CSI Volume

This endpoint deletes an external CSI volume from the storage provider, and
deregisters it from Nomad. It is an error to delete a volume that is in
use. Only CSI plugins that implement the [Controller][csi_plugins_internals]
interface with the `CREATE_DELETE_VOLUME` capability support this endpoint.

| Method   | Path                               | Produces           |
| -------- | ---------------------------------- | ------------------ |
| `DELETE` | `/v1/volume/csi/:volume_id/delete` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                 |
| ---------------- | ---------------------------- |
| `NO`             | `namespace:csi-write-volume` |

This endpoint accepts a `X-Nomad-CSI-Secrets` header to set secrets
for deleting the volume as comma-separated key-value pairs (see the
example below). These secrets will be merged with any secrets already
stored when the CSI volume was created.

The volume must still be registered with Nomad in order to be deleted. This API
call fails if an allocation still claims the volume or if Nomad is unpublishing
the volume.

### Parameters

- `:volume_id` `(string: <required>)` - Specifies the ID of the
  volume. This must be the full ID. Specify this as part of the
  path.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    -H "X-Nomad-CSI-Secrets: secret-key-1=value-1,secret-key-2=value-2" \
    https://localhost:4646/v1/volume/csi/volume-id1/delete
```

## Detach CSI Volume

This endpoint detaches an external CSI volume from a Nomad client node. It is an
error to detach a volume that is in use.

| Method   | Path                               | Produces           |
| -------- | ---------------------------------- | ------------------ |
| `DELETE` | `/v1/volume/csi/:volume_id/detach` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                 |
| ---------------- | ---------------------------- |
| `NO`             | `namespace:csi-write-volume` |

### Parameters

- `:volume_id` `(string: <required>)` - Specifies the ID of the
  volume. This must be the full ID. Specify this as part of the
  path.

- `node` `(string: <required>)` - The node to detach the volume from.
  Specify this as a query string parameter.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    https://localhost:4646/v1/volume/csi/volume-id/detach?node=00000000-0000-0000-0000-000000000000
```

## List External CSI Volumes

This endpoint lists storage CSI volumes that are known to the external storage
provider but may not be registered with Nomad. Only CSI plugins that implement
the [Controller][csi_plugins_internals] interface with the `LIST_VOLUMES`
capability support this endpoint.

| Method | Path                   | Produces           |
|--------|------------------------|--------------------|
| `GET`  | `/v1/volumes/external` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                 |
| ---------------- | ---------------------------- |
| `YES`             | `namespace:csi-list-volume` |

### Parameters

- `plugin_id` `(string: "")` - Specifies a string to filter volumes
  based on a plugin ID prefix. Because the value is decoded to bytes,
  the prefix must have an even number of hexadecimal characters
  (0-9a-f). Specify this as a query string parameter.

- `next_token` `(string: "")` - This endpoint supports paging. The
  `next_token` parameter accepts a string returned in a previous response's
  `NextToken` field to request the next page of results.

- `per_page` `(int: <required>)` - Specifies a maximum number of snapshots to
  return for this request. The response includes a `NextToken` field that
  can be passed to the next request to fetch additional pages.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/volumes/external?&plugin_id=plugin-id1&per_page=2
```

### Sample Response

```json
{
  "NextToken": "eyJ2IjoiMiIsImMiOiJLZ",
  "Volumes": [
    {
      "ExternalID": "vol-37ac485e",
      "CapacityBytes": 1000000,
      "SnapshotID": "snap-12345",
      "PublishedExternalNodeIDs": ["i-12345", "i-abcde"],
      "IsAbnormal": false,
      "Status": ""
    },
    {
      "ExternalID": "vol-10ac4879",
      "CapacityBytes": 1000000,
      "SnapshotID": "snap-abcdef",
      "PublishedExternalNodeIDs": ["i-12345", "i-abcde"],
      "IsAbnormal": true,
      "Status": "example error message from provider"
    }
  ]
}
```

## Create CSI Volume Snapshot

This endpoint creates a snapshot of a CSI volume on the external storage
provider. Only CSI plugins that implement the
[Controller][csi_plugins_internals] interface with the `CREATE_DELETE_SNAPSHOT`
capability support this endpoint.

| Method   | Path                              | Produces           |
| -------- | --------------------------------- | ------------------ |
| `POST`    | `/v1/volumes/snapshot`           | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                 |
| ---------------- | ---------------------------- |
| `NO`             | `namespace:csi-write-volume` |


### Sample Payload

The payload must include a JSON document that describes the snapshot's
parameters.

```json
{
  "Snapshots": [
    {
      "SourceVolumeID": "volume-id1",
      "PluginID": "plugin-id1",
      "Name": "mysnap",
      "Secrets": {
        "password": "xyzzy"
      },
      "Parameters": {
        "example": "infrequent_access"
      }
    }
  ]
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/volumes/snapshot
```

### Sample Response

```json
{
  "Snapshots": [
    {
      "ID": "snap-031f5f7e3406d594a",
      "SizeBytes": 10737418240,
      "CreateTime": 1617909982,
      "IsReady": false,
      "SourceVolumeID": "volume-id1"
    }
  ]
}
```

## Delete CSI Volume Snapshot

This endpoint deletes a CSI volume snapshot from the external storage
provider. Only CSI plugins that implement the
[Controller][csi_plugins_internals] interface with the `CREATE_DELETE_SNAPSHOT`
capability support this endpoint.

| Method   | Path                   | Produces           |
| -------- | ---------------------- | ------------------ |
| `DELETE` | `/v1/volumes/snapshot` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                 |
| ---------------- | ---------------------------- |
| `NO`             | `namespace:csi-write-volume` |

This endpoint accepts a `X-Nomad-CSI-Secrets` header to set secrets
for deleting the snapshot as comma-separated key-value pairs (see the
example below). These secrets will be merged with any secrets already
stored when the CSI snapshot was created.

### Parameters

- `plugin_id` `(string: <required>)` - Specifies the prefix of a CSI plugin ID
  to perform the delete. Because the value is decoded to bytes, the prefix must
  have an even number of hexadecimal characters (0-9a-f). Specify this as a
  query string parameter.

- `snapshot_id` `(string: <required>)` - Specifies the snapshot ID to
  delete. Specify this as a query parameter.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    -H "X-Nomad-CSI-Secrets: secret-key-1=value-1,secret-key-2=value-2" \
    https://localhost:4646/v1/volumes/snapshot
```

## List CSI Volume Snapshots

This endpoint lists CSI volume snapshots on the external storage provider. Only
CSI plugins that implement the [Controller][csi_plugins_internals] interface
with the `LIST_SNAPSHOTS` capability support this endpoint.


| Method | Path                   | Produces           |
| ------ | ---------------------- | ------------------ |
| `GET`  | `/v1/volumes/snapshot` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                |
| ---------------- | --------------------------- |
| `YES`            | `namespace:csi-list-volume` |

This endpoint accepts a `X-Nomad-CSI-Secrets` header to set secrets
for deleting the snapshot as comma-separated key-value pairs (see the
example below). These secrets will be merged with any secrets already
stored when the CSI snapshot was created.

### Parameters

- `plugin_id` `(string: <required>)` - Specifies the prefix of a CSI plugin ID
  to perform the list. Because the value is decoded to bytes, the prefix must
  have an even number of hexadecimal characters (0-9a-f). Specify this as
  a query string parameter.

- `next_token` `(string: "")` - This endpoint supports paging. The
  `next_token` parameter accepts a string returned in a previous response's
  `NextToken` field to request the next page of results.

- `per_page` `(int: <required>)` - Specifies a maximum number of snapshots to
  return for this request. The response includes a `NextToken` field that
  can be passed to the next request to fetch additional pages.

### Sample Request

```shell-session
$ curl \
    -H "X-Nomad-CSI-Secrets: secret-key-1=value-1,secret-key-2=value-2" \
    https://localhost:4646/v1/volumes/snapshot?plugin_id=plugin-id1&per_page=2
```

### Sample Response

```json
{
  "NextToken": "eyJ2IjoiMiIsImMiOiJLZ",
  "Snapshots": [
    {
      "CreateTime": 1227088980,
      "ExternalSourceVolumeID": "vol-37ac485e",
      "ID": "snap-9df717f4",
      "IsReady": true,
      "Parameters": null,
      "PluginID": "aws-ebs0",
      "SizeBytes": 2147483648
    },
    {
      "CreateTime": 1227091232,
      "ExternalSourceVolumeID": "vol-10ac4879",
      "ID": "snap-5cf81835",
      "IsReady": true,
      "Parameters": null,
      "PluginID": "aws-ebs0",
      "SizeBytes": 11811160064
    }
  ]
}
```

## Read Dynamic Host Volume

This endpoint reads information about a specific dynamic host volume.

| Method | Path                         | Produces           |
|--------|------------------------------|--------------------|
| `GET`  | `/v1/volume/host/:volume_id` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                 |
|------------------|------------------------------|
| `YES`            | `namespace:host-volume-read` |

### Parameters

- `:volume_id` `(string: <required>)` - Specifies the ID of the
  volume. This must be the full ID. Specify this as part of the
  path.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/volume/host/c0f7ee7d-5cc6-92fd-f2b5-14b79f01979f
```

### Sample Response

```json
{
  "Allocations": [],
  "CapacityBytes": 49283072,
  "CreateIndex": 11,
  "CreateTime": 1736191993011594200,
  "HostPath": "/run/nomad/dev/alloc_mounts/c0f7ee7d-5cc6-92fd-f2b5-14b79f01979f",
  "ID": "c0f7ee7d-5cc6-92fd-f2b5-14b79f01979f",
  "ModifyIndex": 12,
  "ModifyTime": 1736191993011594200,
  "Name": "external-plugin",
  "Namespace": "default",
  "NodeID": "670cb259-bc26-653b-e316-655af04ad260",
  "NodePool": "default",
  "Parameters": {
    "hello": "world"
  },
  "PluginID": "example-plugin-mkfs",
  "RequestedCapabilities": [
    {
      "AccessMode": "single-node-writer",
      "AttachmentMode": "file-system"
    }
  ],
  "RequestedCapacityMaxBytes": 50000000,
  "RequestedCapacityMinBytes": 50000000,
  "State": "ready"
}
```

## Create Dynamic Host Volume

This endpoint creates a dynamic host volume and registers it with Nomad.

The response body includes the volume definition with the `ID` and `NodeID`
fields populated. Making the same request without the ID creates a new volume on
a different node. Making a request with the ID set updates the volume to the new
parameters, if possible.

| Method | Path                     | Produces           |
|--------|--------------------------|--------------------|
| `PUT`  | `/v1/volume/host/create` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                                                                                                                   |
|------------------|--------------------------------------------------------------------------------------------------------------------------------|
| `NO`             | `namespace:host-volume-create` or<br/>`namespace:host-volume-write`.<br/>`namespace:sentinel-override` if `PolicyOverride` set |

### Parameters

- `Volume` `(Volume: <required>)` - Specifies the JSON definition of the host
  volume. You should include the ID field if you are updating an existing
  volume.

- `PolicyOverride` `(bool: false)` - If set, Nomad overrides any soft mandatory
  Sentinel policies. This field allows creating a volume when it would be denied
  by policy.

### Sample Payload

```json
{
  "PolicyOverride": false,
  "Volume": {
    "Name": "example",
    "Namespace": "default",
    "NodePool": "prod",
    "PluginID": "mkdir",
    "RequestedCapacityMinBytes": 10737418240,
    "RequestedCapacityMaxBytes": 21474836480,
    "RequestedCapabilities": [
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "file-system"
      },
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "block-device"
      }
    ],
    "Constraints": [
      {
        "LTarget": "${attr.kernel.name}",
        "RTarget": "linux",
        "Operand": "="
      }
    ],
    "Parameters": {
      "foo": "bar"
    }
  }
}
```

### Sample Request

```shell-session
$ curl \
    --request PUT \
    --data @payload.json \
    https://localhost:4646/v1/volume/host/create
```

### Sample Response

```json
{
  "Volume": {
    "Allocations": [],
    "CapacityBytes": 21474836480,
    "Constraints": [
      {
        "LTarget": "${attr.kernel.name}",
        "RTarget": "linux",
        "Operand": "="
      }
    ],
    "CreateIndex": 11,
    "CreateTime": 1736191993011594200,
    "ID": "c0f7ee7d-5cc6-92fd-f2b5-14b79f01979f",
    "ModifyIndex": 11,
    "ModifyTime": 1736191993011594200,
    "Name": "example",
    "Namespace": "default",
    "NodeID": "45460554-cc67-11ef-84b7-33d383a55487",
    "NodePool": "prod",
    "Parameters": {
      "foo": "bar"
    },
    "PluginID": "mkdir",
    "RequestedCapabilities": [
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "file-system"
      },
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "block-device"
      }
    ],
    "RequestedCapacityMaxBytes": 21474836480,
    "RequestedCapacityMinBytes": 10737418240,
    "State": "pending"
  },
  "Warnings": null
}
```

## Register Dynamic Host Volume

This endpoint registers an existing dynamic host volume with Nomad.

| Method | Path                       | Produces           |
|--------|----------------------------|--------------------|
| `PUT`  | `/v1/volume/host/register` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                                                                                                                     |
|------------------|----------------------------------------------------------------------------------------------------------------------------------|
| `NO`             | `namespace:host-volume-register` or<br/>`namespace:host-volume-write`.<br/>`namespace:sentinel-override` if `PolicyOverride` set |

### Parameters

- `Volume` `(Volume: <required>)` - Specifies the JSON definition of the host
  volume. You should include the ID field if you are updating an existing
  volume.

- `PolicyOverride` `(bool: false)` - If set, Nomad overrides any soft mandatory
  Sentinel policies. This field allows registering a volume when it would be denied
  by policy.

### Sample Payload

```json
{
  "PolicyOverride": false,
  "Volume": {
    "Name": "example",
    "Namespace": "default",
    "NodePool": "prod",
    "PluginID": "mkdir",
    "RequestedCapacityMinBytes": 10737418240,
    "RequestedCapacityMaxBytes": 21474836480,
    "RequestedCapabilities": [
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "file-system"
      },
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "block-device"
      }
    ],
    "Constraints": [
      {
        "LTarget": "${attr.kernel.name}",
        "RTarget": "linux",
        "Operand": "="
      }
    ],
    "Parameters": {
      "foo": "bar"
    }
  }
}
```

### Sample Request

```shell-session
$ curl \
    --request PUT \
    --data @payload.json \
    https://localhost:4646/v1/volume/host/register
```

### Sample Response

```json
{
  "Volume": {
    "Allocations": [],
    "CapacityBytes": 21474836480,
    "Constraints": [
      {
        "LTarget": "${attr.kernel.name}",
        "RTarget": "linux",
        "Operand": "="
      }
    ],
    "CreateIndex": 11,
    "CreateTime": 1736191993011594200,
    "ID": "c0f7ee7d-5cc6-92fd-f2b5-14b79f01979f",
    "ModifyIndex": 31,
    "ModifyTime": 1736191993721594200,
    "Name": "example",
    "Namespace": "default",
    "NodeID": "45460554-cc67-11ef-84b7-33d383a55487",
    "NodePool": "prod",
    "Parameters": {
      "foo": "bar"
    },
    "PluginID": "mkdir",
    "RequestedCapabilities": [
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "file-system"
      },
      {
        "AccessMode": "single-node-writer",
        "AttachmentMode": "block-device"
      }
    ],
    "RequestedCapacityMaxBytes": 21474836480,
    "RequestedCapacityMinBytes": 10737418240,
    "State": "ready"
  },
  "Warnings": null
}
```

## Delete Dynamic Host Volume

This endpoint deletes a dynamic host volume, and deregisters it from Nomad. It
is an error to delete a volume that is in use.

| Method   | Path                                | Produces           |
|----------|-------------------------------------|--------------------|
| `DELETE` | `/v1/volume/host/:volume_id/delete` | `application/json` |

The following table shows this endpoint's support for [blocking queries][] and
[required ACLs][].

| Blocking Queries | ACL Required                                                        |
|------------------|---------------------------------------------------------------------|
| `NO`             | `namespace:host-volume-write` or<br/>`namespace:host-volume-delete` |

### Parameters

- `:volume_id` `(string: <required>)` - Specifies the ID of the
  volume. This must be the full ID. Specify this as part of the
  path.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    https://localhost:4646/v1/volume/host/ba97ef42-cc68-11ef-a2e7-ffddaecbdb89
```

## List Task Group Host Volume Claims

This endpoint lists host volume claims made by task groups that
requested "sticky" volumes.

| Method | Path                 | Produces           |
|--------|----------------------|--------------------|
| `GET`  | `/v1/volumes/claims` | `application/json` |

The following table shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required                 |
|------------------|------------------------------|
| `YES`            | `namespace:host-volume-read` |

### Parameters
- `claim_id` `(string: "")` - Specifies the prefix of a task group volume
claim ID to perform the list. Specify this as a query string parameter.

- `namespace` `(string: <required>)` - Specifies the namespace used to filter
task group volume claims.

- `job_id` `(string: "")` - Specifies the job ID used to filter task group
volume claims.

- `task_group` `(string: "")` - Specifies the task group name used to filter
task group volume claims.

- `volume_name` `(string: "")` - Specifies the volume name used to filter
task group volume claims.

- `next_token` `(string: "")` - This endpoint supports paging. The
`next_token` parameter accepts a string returned in a previous response's
`NextToken` field to request the next page of results.

- `per_page` `(int: <required>)` - Specifies a maximum number of snapshots to
return for this request. The response includes a `NextToken` field that
you can pass to the next request to fetch additional pages.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/volumes/claims
```

### Sample Response

```json
[
  {
    "AllocID": "34e44207-0cf3-a24d-4bbe-6c91cec642ce",
    "CreateIndex": 15,
    "ID": "75c417b5-cf90-86e4-8ffc-d18f445e0721",
    "JobID": "example",
    "ModifyIndex": 15,
    "Namespace": "default",
    "TaskGroupName": "echo",
    "VolumeID": "0bb42da3-7e09-6937-a83d-69d5c9bfce30",
    "VolumeName": "sticky-volume"
  }
]
```

## Delete Task Group Host Volume Claims

This endpoint deletes host volume claims made by task groups that
requested "sticky" volumes.

| Method   | Path                          | Produces       |
|----------|-------------------------------|----------------|
| `DELETE` | `/v1/volumes/claim/:claim_id` | `(empty body)` |

The following table shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required                  |
|------------------|-------------------------------|
| `NO`             | `namespace:host-volume-write` |

### Parameters

- `claim_id` `(string: <required>)` - Specifies the ID of task group host volume claim
to delete and is specified as part of the path.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    https://localhost:4646/v1/volume/claim/75c417b5-cf90-86e4-8ffc-d18f445e0721
```

[blocking queries]: /nomad/api-docs#blocking-queries
[required ACLs]: /nomad/api-docs#acls
[csi]: https://github.com/container-storage-interface/spec
[csi_plugin]: /nomad/docs/job-specification/csi_plugin
[csi_plugins_internals]: /nomad/docs/architecture/storage/csi
[Create CSI Volume]: #create-csi-volume
[Volume Expansion]: /nomad/docs/other-specifications/volume/csi#volume-expansion
[csi-volume-spec]: /nomad/docs/other-specifications/volume/csi