Detach Volume to Instance

This endpoint detaches an active storage volume from its currently assigned X-Series GPU virtual machine instance using the unique Volume ID.

Detach Volume from Instance - Overview

The X-Series Volume Detachment API allows authenticated users to detach an existing block storage volume from the GPU virtual machine to which it is currently attached.

This endpoint identifies the volume using its volume_id. It is useful for managing storage attachments, reorganizing storage resources & automating volume management workflows through the API.

When a volume is detached successfully, the API returns a confirmation message indicating that the detachment operation has completed.

Important Note: This endpoint requires only the volume ID. Make sure that you select the correct volume before submitting the request.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/xseries/volumes/detach
Full URL	https://cloud.dataoorts.com/api/v1/xseries/volumes/detach
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	The ID of the volume you want to detach from its attached instance.

Provide the ID of the existing volume. You do not need to specify an instance_id; the API identifies the volume using volume_id.

Request Examples

cURL - Use the following command to detach a volume:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/xseries/volumes/detach" \
  --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

Python

import os
import requests


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


def detach_xseries_volume(
    api_key: str,
    volume_id: int,
) -> dict:
    """
    Detach an existing X-Series volume from its instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        volume_id: The ID of the volume to detach.

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

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the response cannot be decoded as JSON.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "volume_id": volume_id,
    }

    response = requests.post(
        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."
        )

    try:
        result = detach_xseries_volume(
            api_key=api_key,
            volume_id=29161,
        )

        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 API response: {exc}.")

Set your API key before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python detach_volume.py

Windows PowerShell

PowerShell

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

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

Example Success Response

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

JSON

{
  "message": "volume detached successfully.",
  "status": "success"
}

The response confirms the result reported by the API.

Response Fields

Field	Type	Description
status	String	Indicates result of the API request. A successful response returns success.
message	String	A descriptive message confirming that the volume was detached successfully.

Understanding the Volume Detachment Process

After submitting the request:

1. API Processes the detachment request using the supplied volume_id.
2. If the operation succeeds, the API returns a confirmation message.
3. You can use the List All Volumes API to retrieve the latest volume information and check its reported status and attachment details.

Important: Detaching a volume releases its attachment to the instance, This endpoint does not request permanent deletion of the volume.

Important Notes

1. Correct Volume ID: Verify the volume_id before submitting the request to ensure that you detach the intended volume.

2. No Instance ID Required: The request requires only volume_id. The API does not require a separate instance_id in the request body.

3. Verify the Result: After a successful response, retrieve the volume list to check the attachment information reported by the API.

4. Application Dependencies: If an application or workload relies on the attached volume, account for the potential disruption before detaching it.

5. Handle Request Timeouts Carefully: If the request times out or returns an error, check the volume's current attachment information before retrying to avoid unnecessary repeated requests.

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, 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 the successful response shown above.

Get Help and Support

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