Create an Volume

This endpoint creates a persistent block storage volume of a specified size within a designated cloud region on the Dataoorts platform.

Create a Volume - Overview

The X-Series Volume Creation API allows authenticated users to create a block storage volume in a specified region with a defined storage capacity.

This endpoint is useful for provisioning additional storage for GPU virtual machines, automating storage management, and integrating volume creation into custom infrastructure workflows.

When a volume is created successfully, the API returns its volume ID, display ID, storage capacity, region, and the initial deduction amount reported by the service.

Important Note: A volume can only be attached to a GPU instance located in the same region. Before creating a volume, verify the region of the target instance using the GPU Regions and Volumes.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/xseries/volumes/create
Full URL	https://cloud.dataoorts.com/api/v1/xseries/volumes/create
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
size	Integer	Yes	The requested volume capacity in gigabytes (GiB).
region	String	Yes	The region code in which the volume should be created, such as CANADA-1.

Important: Use a valid region code returned by the GPU Regions API. If the volume is intended for a particular GPU instance, ensure that the selected region matches the instance's region.

Request Examples

cURL - Use the following command to create a 100 GB volume in the CANADA-1 region:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/xseries/volumes/create" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "size": 100,
    "region": "CANADA-1"
  }'

Replace YOUR_API_KEY with your actual Dataoorts Unify API key. Adjust size and region according to your storage requirements and the available regions.

---

Python Example Implementation

The following example uses requests library to create a volume and retrieve the resulting volume details.

Python

import os
import requests


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


def create_xseries_volume(
    api_key: str,
    size_gb: int,
    region_code: str,
) -> dict:
    """
    Create an X-Series block storage volume.

    Args:
        api_key: Your Dataoorts Unify API key.
        size_gb: Requested volume size in GB.
        region_code: Region code for volume creation.

    Returns:
        dict: The JSON response containing the created volume details.

    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 = {
        "size": size_gb,
        "region": region_code,
    }

    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 = create_xseries_volume(
            api_key=api_key,
            size_gb=100,
            region_code="CANADA-1",
        )

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

        volume = result.get("data", {})

        print("Volume ID:", volume.get("volume_id"))
        print("Display ID:", volume.get("display_id"))
        print("Size (GB):", volume.get("size_gb"))
        print("Region:", volume.get("region"))
        print("Initial Deduction:", volume.get("initial_deduction"))

    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 create_volume.py

Windows PowerShell

PowerShell

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

The script submits the volume creation request and prints the volume identifiers, storage capacity, region, and initial deduction returned by the API.

Example Success Response

A successful request returns a JSON response containing the newly created volume's information.

HTTP Status: 201 Created 'The API may also return 200 OKfor some Regions'

JSON

{
  "data": {
    "display_id": "SSD-0729161",
    "initial_deduction": 0.00569,
    "region": "CANADA-1",
    "size_gb": 100,
    "volume_id": 29161
  },
  "message": "Volume created successfully.",
  "status": "success"
}

The values shown above illustrate the response structure. The actual volume IDs, display ID, region, size, and deduction depend on the request and the API response.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success.
message	String	A descriptive message confirming that the volume was created successfully.
data.volume_id	Integer	The identifier assigned to the newly created volume.
data.display_id	String	The display identifier associated with the volume.
data.size_gb	Integer	The created volume's storage capacity in GB.
data.region	String	The region code in which the volume was created.
data.initial_deduction	Number	The initial deduction amount reported by the API for the volume creation operation.

Understanding the Volume Creation Process

After submitting the request:

1. Dataoorts processes the volume creation request using the specified storage capacity & region.
2. When the volume is created successfully, the API returns its volume ID and other details.
3. Store the returned volume_id and display_id if your application needs to reference the volume in subsequent workflows.
4. If you intend to attach the volume to a GPU instance, ensure that the instance is located in the same region as the volume.

Important: This endpoint creates a volume. It does not, by itself, attach the volume to a GPU instance.

Important Notes

1. Region Compatibility: A volume can only be attached to a GPU instance located in the same region. Verify the target instance's region before creating the volume.

2. Volume Size: Provide the required storage capacity through the size parameter. Use an appropriate size for your workload and the capacity supported by the service.

3. Volume Identification: Save the returned volume_id and display_id for future reference and storage management operations.

4. Initial Deduction: The initial_deduction field reports the amount returned by the API. Refer to the applicable Dataoorts billing details for its exact calculation and currency.

5. Handle Request Timeouts Carefully: If a request times out or returns an error, check whether the volume was created before retrying. This helps avoid unintentionally creating duplicate volumes.

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 region codes, unsupported volume sizes, network errors, timeouts, and unexpected response formats. The exact error codes and 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 creation, region compatibility, or API integration, contact the Dataoorts support team at [email protected].