---
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
$ 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
$ 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         |
| ---------------- | -------------------- |
| `YES`            | `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
{
  "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
$ 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           |
| -------- | --------------------------- | ------------------ |
| `DELTE`  | `/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-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 Request

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