.. role:: green

Volume Functions
================

Fetch a Volume
--------------

**Type:** :guilabel:`GET`

.. py:function:: https://cloud.syminet.com/api/v1/volumes/{VOLUME_ID}

    Return details of a volume.

**Required URL Parameters:**

VOLUME_ID
  Volume ID to fetch.

.. code-block:: shell
   :caption: Curl

    curl --request GET \
         --url https://cloud.syminet.com/api/v1/volumes/VOLUME_ID \
         --header "authorization:bearer $API_TOKEN"

.. code-block:: json
    :caption: Response

    {
      "created" : "Wed, 20 Nov 2024 22:01:30 GMT",
      "datacenter_id" : 6,
      "deleted" : null,
      "host_id" : 41,
      "id" : 160,
      "in_progress" : null,
      "progress" : null,
      "queued" : null,
      "queued_user_id" : 2316,
      "snapshot_uuid" : null,
      "status" : "active",
      "user_id" : 1424,
      "vm_id" : 3247,
      "vol_allocated" : null,
      "vol_uuid" : "980d1d45-5d8a-45a1-863e-719c8e7bc1bf",
      "volname" : "myvolume",
      "volsize" : 100
    }


List Volumes for a Slice
------------------------

**Type:** :guilabel:`GET`

.. py:function:: https://cloud.syminet.com/api/v1/images/snapshots/{SLICE_ID}

    Return a list of all snapshots for ``SLICE_ID``.

**Required URL Parameters:**

SLICE_ID
  Slice ID to list volumes for.

.. code-block:: shell
   :caption: Curl

    curl --request GET \
         --url https://cloud.syminet.com/api/v1/images/snapshots/SLICE_ID \
         --header "authorization:bearer $API_TOKEN"


.. code-block:: json
    :caption: Response

    {
      "data" : [
        {
          "backup_full_size" : 50,
          "created" : "Fri, 01 Nov 2024 21:23:13 GMT",
          "duration" : "43s",
          "id" : 14901,
          "name" : "11test1-173049603"
        },
        {
          "backup_full_size" : 50,
          "created" : "Thu, 29 Aug 2024 23:17:36 GMT",
          "duration" : "47s",
          "id" : 13680,
          "name" : "11testing-1724973454"
        }
      ]
    }



Attach a Volume
---------------

**Type:** :guilabel:`POST`

.. py:function:: https://cloud.syminet.com/api/v1/volumes/{VOLUME_ID}/attach/{SLICE_ID}

    Attach ``SNAPSHOT_ID`` to ``SLICE_ID``.

**Required URL Parameters:**

VOLUME_ID
  Volume ID to attach.

SLICE_ID
  Slice ID to attach.

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/volumes/VOLUME_ID/attach/SLICE_ID \
         --header "authorization:bearer $API_TOKEN"


**Response:** :green:`202 OK`


Detach a Volume
---------------

**Type:** :guilabel:`POST`

.. py:function:: https://cloud.syminet.com/api/v1/volumes/{VOLUME_ID}/detach

    Detach VOLUME_ID from a slice.

.. Note::

   It is strongly recommended to unmount the volume on any slice it is currently 
   mounted on before detaching it.

**Required URL Parameters:**

VOLUME_ID
  Volume ID to detach.

.. code-block:: shell
   :caption: Curl

    curl --request POST \
         --url https://cloud.syminet.com/api/v1/volumes/VOLUME_ID/detach \
         --header "authorization:bearer $API_TOKEN"


**Response:** :green:`202 OK`


Rename a Volume
---------------

**Type:** :guilabel:`PUT`

.. py:function:: https://cloud.syminet.com/api/v1/volumes/{VOLUME_ID}/rename

    Rename volume ``VOLUME_ID``.

**Required URL Parameters:**

VOLUME_ID
  Volume ID to rename.

**Required JSON Properties:**

volume_name
  New volume name.

.. code-block:: shell
   :caption: Curl

    curl --request PUT \
         --url https://cloud.syminet.com/api/v1/volumes/VOLUME_ID/rename \
         --header "content-type: application/json" \
         --header "authorization:bearer $API_TOKEN" \
         --data '
         {
            "volume_name": "myvolume-renamed"
         }
         '

**Response:** :green:`202 OK`