Create an Instance

This endpoint provisions and launches a new Z-Series enterprise GPU virtual machine by specifying the desired GPU model (gpu_type), accelerator count (num_gpus), and local NVMe storage allocation (storage_gb).

Create an Instance - Overview

The Z-Series Create Instance API allows authenticated users to launch a new Z-Series GPU virtual machine using the specified GPU type, number of GPUs, and NVMe storage capacity.

Before provisioning, the API validates that the requested GPU type exists, the requested number of GPUs is available, the storage size is valid, and the authenticated user has sufficient account balance.

If all validation checks pass, the virtual machine is provisioned and the response returns the local instance ID, provider VID, SSH command, hourly GPU compute cost, and instance status.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/zseries/create
Full URL	https://cloud.dataoorts.com/api/v1/zseries/create
Authentication	Bearer Token
Request Format	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

Endpoint requires JSON request body containing the GPU type, number of GPUs, and NVMe storage capacity.

Parameter	Type	Required	Description
gpu_type	String	Yes	GPU model returned by the Z-Series offers endpoint. The value is case-sensitive.
num_gpus	Integer	Yes	Number of GPUs to allocate. Allowed values are 1, 2, 4, and 8.
storage_gb	Integer	Yes	Requested NVMe storage capacity in GB. Allowed range is 100–5000 GB.

Example Request Body

JSON

{
  "gpu_type": "H200",
  "num_gpus": 4,
  "storage_gb": 2800
}

Important: Always obtain the latest gpu_type from GET /api/v1/zseries/offers before creating a virtual machine. The GPU type must exactly match a value returned by the Live Offers endpoint.

Request Examples

cURL - Use the following command to launch a Z-Series GPU VM:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/zseries/create" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "gpu_type": "L4",
    "num_gpus": 1,
    "storage_gb": 800
  }'

Replace YOUR_API_KEY with your actual Dataoorts Unify API key. Select a currently available GPU type and provide the required GPU count and storage capacity.

Python Example Implementation

The following example uses the requests library to launch a Z-Series GPU virtual machine. It reads the API key from an environment variable, handles unsuccessful HTTP responses, and checks the response format before processing the returned data.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/zseries/create"


def create_zseries_instance(
    api_key: str,
    gpu_type: str,
    num_gpus: int,
    storage_gb: int,
) -> dict | None:
    """
    Launch a Z-Series GPU virtual machine.

    Args:
        api_key: Your Dataoorts Unify API key.
        gpu_type: The exact GPU type returned by the offers endpoint.
        num_gpus: Number of GPUs to allocate (1, 2, 4, or 8).
        storage_gb: Requested NVMe storage capacity in GB (100–5000).

    Returns:
        The JSON response containing the instance launch details,
        or None if the API returns a non-JSON response.

    Raises:
        ValueError:
            If the supplied GPU count or storage size is invalid,
            or if the response contains invalid JSON.
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
    """
    if num_gpus not in (1, 2, 4, 8):
        raise ValueError(
            "num_gpus must be one of: 1, 2, 4, 8."
        )

    if not 100 <= storage_gb <= 5000:
        raise ValueError(
            "storage_gb must be between 100 and 5000 GB."
        )

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

    payload = {
        "gpu_type": gpu_type,
        "num_gpus": num_gpus,
        "storage_gb": storage_gb,
    }

    response = requests.post(
        API_URL,
        headers=headers,
        json=payload,
        timeout=180,
    )

    response.raise_for_status()

    content_type = response.headers.get("Content-Type", "")

    if "application/json" not in content_type.lower():
        print("Non-JSON response received:")
        print(response.text[:500])
        return None

    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_zseries_instance(
            api_key=api_key,
            gpu_type="L4",
            num_gpus=1,
            storage_gb=800,
        )

        if result is not None:
            print("Status:", result.get("status"))
            print("Message:", result.get("message"))

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

            print("\nZ-Series Instance Details")
            print("Instance ID:", data.get("instance_id"))
            print("Provider VID:", data.get("provider_vid"))
            print("Status:", data.get("status"))
            print("Hourly Cost:", data.get("hourly_cost"))

            # SSH commands may contain connection details.
            # Keep them out of public logs and shared output.
            print(
                "SSH Command Available:",
                bool(data.get("ssh_command")),
            )

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

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

Set your API key in your Env before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python zseries_create.py

Windows PowerShell

PowerShell

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

The script submits the selected GPU type, GPU count, and storage capacity, then displays the returned instance ID, provider VID, status, and hourly cost.

Example Success Response

A successful request returns HTTP 201 Created with a JSON object containing the newly created instance details, a descriptive message, and the response status.

HTTP Status: 201 Created

JSON

{
  "data": {
    "hourly_cost": 0.48,
    "instance_id": 19,
    "provider_vid": "434190",
    "ssh_command": "ssh -i temporary.pem -o StrictHostKeyChecking=no [email protected]",
    "status": "Active"
  },
  "message": "Instance provisioning initiated successfully.",
  "status": "success"
}

The values above illustrate the response structure. Instance identifiers, provider VIDs, SSH commands, statuses, and costs may differ in subsequent API responses.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success; an unsuccessful response returns error.
message	String	A descriptive message about the result of the instance creation request.
data	Object	Contains the details returned for the newly created Z-Series virtual machine.

Instance Record Fields

The data object contains the information returned after the instance creation request.

Field	Type	Description
data.instance_id	Integer	The local instance ID assigned to the virtual machine.
data.provider_vid	String	The provider's virtual machine identifier.
data.ssh_command	String	The SSH command returned for connecting to the Instance.
data.hourly_cost	Float	hourly GPU compute cost in USD. Storage is billed separately.
data.status	String	Instance status returned by API. The example returns Active.

Understanding Instance Information

GPU Configuration

The gpu_type parameter specifies the GPU model, while num_gpus specifies the number of GPUs to allocate.

Supported GPU quantities are 1, 2, 4, and 8. Always retrieve the latest offers using GET /api/v1/zseries/offers and use the exact, case-sensitive gpu_type returned by that endpoint.

NVMe Storage Capacity

The storage_gb parameter specifies the requested NVMe storage capacity in GB.

The supported storage range is 100–5000 GB. The API validates the requested storage size before provisioning the virtual machine.

Instance Provisioning

After the API validates GPU availability, storage capacity, account balance, and provider configuration, provisioning proceeds.

The supplied successful response returns an instance status of Active alongside the message Instance provisioning initiated successfully. Check the response and use the returned status when determining the instance state.

Instance Identification

The response includes instance_id and provider_vid. These fields identify the local instance record and the provider's virtual machine, respectively.

Retain these identifiers for subsequent instance management operations.

SSH Connection

The ssh_command field provides the SSH command returned by the API. The example uses the temporary.pem private key.

Use the downloaded private key as required by the command and keep it secure. Do not publish SSH connection details or expose private key contents in shared logs.

Hourly Cost and Storage Billing

The hourly_cost field reports the GPU compute cost per hour in USD. Storage is billed separately.

According to the supplied endpoint notes, an initial deduction of approximately 10 minutes of GPU compute usage plus NVMe storage is charged when provisioning begins.

Refer to the applicable Dataoorts billing details for the exact charges and billing policy.

Provisioning Workflow

The Z-Series instance creation process follows these steps:

1. Authenticate using your Dataoorts API key.
2. Fetch available GPU configurations using GET /api/v1/zseries/offers.
3. Select the desired gpu_type, num_gpus, and storage_gb.
4. Submit a POST request to /api/v1/zseries/create.
5. The API validates the GPU type, GPU availability, storage size, account balance, and provider configuration.
6. If validation succeeds, provisioning proceeds and the API returns the instance details.
7. Use the appropriate Z-Series instance information endpoint to review the returned instance status and connection information.

Important Notes

1. Latest Offers: Always retrieve the latest GPU offers before creating a virtual machine. The gpu_type must exactly match one of the values returned by the Live Offers endpoint.

2. Supported GPU Counts: The allowed values for num_gpus are 1, 2, 4, and 8.

3. Storage Limits: The allowed storage_gb range is 100–5000 GB.

4. Account Balance: The authenticated user must have sufficient account balance for the request to proceed.

5. Pricing Currency: All pricing values are returned in USD.

6. Separate Storage Billing: The returned hourly_cost includes GPU compute charges only. NVMe storage is billed separately.

7. Initial Deduction: An initial charge of approximately 10 minutes of GPU compute usage plus NVMe storage is charged when provisioning begins.

8. SSH Connection: The returned ssh_command is intended to be used with the downloaded temporary.pem private key. Keep the private key and connection details secure.

9. Request Timeout: The Python example uses a timeout of 180 seconds. If the request times out, check the instance list before retrying because the outcome of the original request may be uncertain.

10. Database Transaction: If a database error occurs after the provider creates the instance, the API attempts to clean up the provider instance to prevent orphaned resources.

11. API Key Security: Keep your API key confidential and store it in the DATAOORTS_API_KEY environment variable rather than hardcoding it in your application.

Error Handling

API may return unsuccessful HTTP status code & JSON error response when the instance cannot be created.

Your application should handle authentication failures, invalid request payloads, missing parameters, invalid GPU counts, invalid storage sizes, unavailable GPU types, insufficient GPU capacity, insufficient account balance, provider API failures, database transaction errors, and unexpected response formats.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. The example also checks the response content type and handles JSON decoding errors before processing the instance creation result.

Missing API Key

HTTP Status: 401 Unauthorized

JSON

{
  "status": "error",
  "message": "Authorization header with 'Bearer <TOKEN>' is required."
}

Include the Authorization header with a valid Bearer token.

Missing Token

HTTP Status: 401 Unauthorized

JSON

{
  "status": "error",
  "message": "API Token is missing or empty, Please provide in Header."
}

Ensure that the API token is present and non-empty.

Invalid API Key

HTTP Status: 403 Forbidden

JSON

{
  "status": "error",
  "message": "Invalid API key - IP Blocked Next Time."
}

Verify that your Dataoorts API key is valid and included in the request header.

Invalid JSON

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Invalid JSON payload."
}

Ensure that the request body contains valid JSON.

Missing Required Fields

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "gpu_type, num_gpus, and storage_gb are required."
}

Provide all three required parameters in the JSON request body.

Invalid GPU Count

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "num_gpus must be one of: 1, 2, 4, 8"
}

Set num_gpus to one of the supported values: 1, 2, 4, or 8.

Invalid Storage Size

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "storage_gb must be between 100 and 5000 GB."
}

Provide a storage_gb value between 100 and 5000, inclusive.

Invalid Numeric Values

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Invalid numerical values provided."
}

Verify that num_gpus and storage_gb contain valid numerical values.

GPU Type Not Available

HTTP Status: 404 Not Found

JSON

{
  "status": "error",
  "message": "Invalid 'gpu_type' or item is currently out of stock."
}

Retrieve the latest offers and verify that the requested GPU type exists and is currently available.

Insufficient GPU Capacity

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Only 2 GPU Cards available for NVIDIA H200"
}

Check the available GPU capacity and submit a request for a supported quantity of available GPUs.

Insufficient Balance

HTTP Status: 402 Payment Required

JSON

{
  "status": "error",
  "message": "Insufficient balance, Required: $1.78, Available: $0.95."
}

Add sufficient funds to your account before submitting the request again. The amounts above illustrate the supplied error response.

Provider API Error

HTTP Status: 502 Bad Gateway

JSON

{
  "status": "error",
  "message": "DDRA Server API Error or Capacity full."
}

This response indicates a provider API error or insufficient capacity. Check current offer availability and try again later if appropriate.

Database Transaction Failed

HTTP Status: 500 Internal Server Error

JSON

{
  "status": "error",
  "message": "Database transaction failed, VM launch reverted."
}

The API reports that launch transaction was reverted. Check instance list before retrying the creation request.

Internal Server Error

HTTP Status: 500 Internal Server Error

JSON

{
  "status": "error",
  "message": "Internal DDRA Server Error, Please Contact Support."
}

If the error persists, contact the Dataoorts support team for assistance.

General Error Handling

Scenario	Recommended Handling
API key is missing	Include the Authorization header with a valid Bearer token.
API key is invalid	Verify the API key through the Dataoorts platform.
Request body is invalid	Send a valid JSON object containing all required parameters.
GPU count is invalid	Use 1, 2, 4, or 8.
Storage size is invalid	Provide a value between 100 and 5000 GB.
GPU type is invalid or unavailable	Retrieve the latest offers and select an available GPU type.
GPU capacity is insufficient	Check available capacity and adjust the requested GPU count.
Account balance is insufficient	Add sufficient funds before retrying.
Provider returns 502	Check capacity and retry later if appropriate.
Database transaction fails	Check the instance list before retrying the creation request.
Request times out	Check whether the instance was created before submitting another request.
Response is not JSON	Inspect the returned response text without attempting to parse it as JSON.
Response contains invalid JSON	Handle JSON decoding error before accessing response fields.

Get Help and Support

For assistance with Z-Series instance creation or API integration, Contact support team at [email protected].