open-nomad/website/pages/api-docs/volumes.mdx

---
layout: api
page_title: Volumes - HTTP API
sidebar_title: Volumes
description: The `/volume` endpoints are used to query for and interact with volumes.
---

# Volumes HTTP API

The `/volume` endpoints are used to query for and interact with volumes.

## List Volumes

This endpoint lists all volumes.

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

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

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

### Parameters

- `type` `(string: "")`- Specifies the type of volume to
  query. Currently only supports `csi`. This is specified as a query
  string parameter. Returns an empty list if omitted.

- `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). This is specified 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). This is specified as a query string parameter.

### Sample Request

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

### Sample Response

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

## Read Volume

This endpoint reads information about a specific volume.

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

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#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. This is specified 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": "volume-id1",
  "Topologies": [{ "foo": "bar" }],
  "AccessMode": "multi-node-single-writer",
  "AttachmentMode": "file-system",
  "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:3.2"
            },
            {
              "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
    }
  ],
  "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 Volume

This endpoint registers an external volume with Nomad. It is an error
to register an existing volume.

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

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#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. This is specified as part of the
  path.

### Sample Payload

The payload must include a JSON document that described the volume's
parameters.

```json
{
  "Volumes": [
    {
      "ID": "volume-id1",
      "Name": "volume id1",
      "Namespace": "default",
      "ExternalID": "volume-id1",
      "Topologies": [{ "foo": "bar" }],
      "AccessMode": "multi-node-single-writer",
      "AttachmentMode": "file-system",
      "PluginID": "plugin-id1"
    }
  ]
}
```

### Sample Request

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

## Delete Volume

This endpoint deregisters an external volume with 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 table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#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. This is specified 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.
  This is specified as a query string parameter.

### Sample Request

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

## Detach Volume

This endpoint detaches an external 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 table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#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. This is specified as part of the
  path.

- `node` `(string: <required>)`- The node to detach the volume from.
This is specified 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
```