Terminate an Volume

This endpoint permanently deletes a specific persistent storage volume using its unique Volume ID.

Delete a Volume - Overview

The X-Series Volume Deletion API allows authenticated users to permanently delete an existing block storage volume using its volume ID.

This endpoint is useful for removing storage resources that are no longer required and automating volume cleanup through custom infrastructure management workflows.

When a volume is deleted successfully, the API returns a confirmation message indicating that the volume has been permanently deleted.

Important Warning: Volume deletion is a permanent operation. Verify the volume ID and ensure that any required data has been backed up before submitting the request. Do not delete a volume that is still required by an application or workload.

Endpoint

Property	Value
HTTP Methods	POST or DELETE
Endpoint	/xseries/volumes/delete
Full URL	https://cloud.dataoorts.com/api/v1/xseries/volumes/delete
Authentication	Bearer Token
Content Type	application/json
Response Format	JSON

Authentication

This endpoint requires a valid Dataoorts Unify API key.

Include your API key in the Authorization header using the Bearer authentication scheme.

HTTP

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Generate or manage your API key through the Dataoorts Unify API.

Keep your API key confidential and never expose it in public repositories or client-side applications.

Request Parameters

The request body must be sent as JSON.

Parameter	Type	Required	Description
volume_id	Integer or String	Yes	ID of volume you want to permanently delete.

Provide the identifier of the existing volume you intend to delete. Verify the ID before submitting the request because the operation permanently removes the volume.

Request Examples

cURL - Use the following command to delete a volume using the POST method:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/xseries/volumes/delete" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "volume_id": 29161
  }'

Alternatively, you can use the DELETE HTTP method:

Bash

curl --request DELETE \
  --url "https://cloud.dataoorts.com/api/v1/xseries/volumes/delete" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "volume_id": 29161
  }'

Replace YOUR_API_KEY and the example volume ID with your actual values.

---

Python Example Implementation

The following example uses the requests library to delete a volume and display the API response. It supports both POST and DELETE methods.

Python

import os
import requests


API_URL = (
    "https://cloud.dataoorts.com"
    "/api/v1/xseries/volumes/delete"
)


def delete_xseries_volume(
    api_key: str,
    volume_id: int | str,
    method: str = "POST",
) -> dict:
    """
    Permanently delete an X-Series storage volume.

    WARNING:
        This operation permanently deletes the selected volume.
        Back up any required data before proceeding.

    Args:
        api_key: Your Dataoorts Unify API key.
        volume_id: The ID of the volume to delete.
        method: HTTP method, either POST or DELETE.

    Returns:
        dict: The JSON response returned by the API.

    Raises:
        ValueError:
            If the HTTP method is invalid or the response is not valid JSON.
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
    """
    method = method.upper()

    if method not in {"POST", "DELETE"}:
        raise ValueError("method must be 'POST' or 'DELETE'.")

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "volume_id": volume_id,
    }

    response = requests.request(
        method=method,
        url=API_URL,
        headers=headers,
        json=payload,
        timeout=60,
    )

    response.raise_for_status()

    try:
        return response.json()
    except requests.exceptions.JSONDecodeError as exc:
        raise ValueError(
            "The API returned an invalid JSON response."
        ) from exc


if __name__ == "__main__":
    api_key = os.getenv("DATAOORTS_API_KEY")

    if not api_key:
        raise RuntimeError(
            "Set the DATAOORTS_API_KEY environment variable."
        )

    # Verify the volume ID before running this operation.
    volume_id = 29161

    try:
        result = delete_xseries_volume(
            api_key=api_key,
            volume_id=volume_id,
            method="POST",
        )

        print("Status:", result.get("status"))
        print("Message:", result.get("message"))

    except requests.exceptions.RequestException as exc:
        print(f"API request failed: {exc}.")

    except ValueError as exc:
        print(f"Invalid request or response: {exc}.")

Set your API key before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python delete_volume.py

Windows PowerShell

PowerShell

$env:DATAOORTS_API_KEY="YOUR_API_KEY"
python delete_volume.py

The script submits the deletion request and displays the status and confirmation message returned by the API.

To use the DELETE method, change method="POST" to method="DELETE" in the function call.

Example Success Response

When a volume is deleted successfully, the API returns a JSON response similar to the following:

JSON

{
  "status": "success",
  "message": "volume 29161 has been permanently deleted."
}

The volume ID and message will reflect the actual deletion request.

Response Fields

Field	Type	Description
status	String	Indicates result of the API request, Successful response returns success.
message	String	Descriptive message confirming that volume has been permanently deleted.

Understanding the Volume Deletion Process

After submitting the request:

1. API processes the deletion request using the supplied volume_id.
2. If the deletion succeeds, the API returns a confirmation message.
3. The volume is permanently deleted & should no longer be treated as an available storage resource.
4. If needed, use List All Volumes API to retrieve volume records returned by the service and verify the result.

Important: This endpoint deletes a volume. It does not merely detach the volume from an instance.

Important Notes

1. Permanent Data Loss: Deleting a volume permanently removes the storage resource. Back up any required data before submitting the request.

2. Verify the Volume ID: Ensure that volume_id identifies the correct volume. An incorrect ID may target a different storage resource than intended.

3. Check Volume Attachments: Before deletion, review the volume's current attachment information and check the applicable service requirements. Ensure that deleting volume will not disrupt applications or workloads.

4. No Instance ID Required: The request requires only volume_id. A separate instance_id is not part of the request payload.

5. Handle Request Timeouts Carefully: If the request times out or returns an error, verify the volume's current state before retrying. A timeout does not necessarily mean the server failed to process the deletion.

Error Handling

If request fails, API may return unsuccessful HTTP status code and JSON response containing an error message.

Your application should handle authentication failures, invalid volume IDs, network errors, request timeouts, and unexpected response formats. Exact error codes and response messages depend on the API response.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. Do not assume that every response contains the same fields as a successful response.

Get Help and Support

For assistance with volume deletion, storage management, or API integration, contact the Dataoorts support team at [email protected].