Create an Instance

This endpoint launches a new X-Series GPU virtual machine instance using the specified VM configuration name and operating system image.

Create an Instance - Overview

The X-Series Instance Creation API allows authenticated users to launch a new virtual machine by specifying the full VM configuration name and the operating system image.

The API creates an instance using the selected GPU configuration and OS image. Once the instance is created, its public IP address may initially appear as Pending. After a short period, an IP address is automatically assigned and attached to the instance.

Use this endpoint to automate GPU instance provisioning, integrate instance creation into your applications, and build custom infrastructure management workflows.

Important Note: Provide the exact full VM name, including its price, and the complete OS image name as returned by the corresponding Dataoorts APIs.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/xseries/create
Full URL	https://cloud.dataoorts.com/api/v1/xseries/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
VM	String	Yes	The complete VM configuration name, including its displayed price.
OS-Image	String	Yes	The complete name of the operating system image to install on the instance.

Important: Both values must match the corresponding names returned by the Dataoorts API, Do not omit the price from the VM value or shorten the OS-Image name.

You can retrieve the available VM configurations from the Get All Available Offers and the available operating system images from the Get Supported OS Images.

Request Examples

cURL - Use the following command to launch a new X-Series instance:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/xseries/create" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "VM": "VM_H100x1_180.0RAM_28CPU_850SSD: $1.74/Hour",
    "OS-Image": "Ubuntu Server 22.04 LTS R535 CUDA 12.2 with Docker"
  }'

Replace YOUR_API_KEY with your actual Dataoorts Unify API key. You can change the VM configuration and OS image according to your requirements.

---

Python Example Implementation

Python

import os
import requests


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


def create_xseries_instance(
    api_key: str,
    vm: str,
    os_image: str,
) -> dict:
    """
    Launch a new X-Series virtual machine.

    Args:
        api_key: Your Dataoorts Unify API key.
        vm: The full VM configuration name, including its price.
        os_image: The complete operating system image name.

    Returns:
        dict: The JSON response containing the launch result
              and instance information.

    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 = {
        "VM": vm,
        "OS-Image": os_image,
    }

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

    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_instance(
            api_key=api_key,
            vm="VM_H100x1_180.0RAM_28CPU_850SSD: $1.74/Hour",
            os_image="Ubuntu Server 22.04 LTS R535 CUDA 12.2 with Docker",
        )

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

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

        print("Instance ID:", instance.get("instance_id"))
        print("Public IP:", instance.get("public_ip"))
        print("SSH User:", instance.get("ssh_user"))
        print("Hourly Cost:", instance.get("hourly_cost"))

        if instance.get("public_ip") == "Pending":
            print(
                "The instance has been created. "
                "The public IP will be assigned automatically."
            )

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

Windows PowerShell

PowerShell

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

The script submits the instance creation request and prints the instance ID, public IP, SSH username, and hourly cost returned by the API.

Example Success Response

When an instance is created successfully, the API returns a JSON response similar to the following:

JSON

{
  "data": {
    "hourly_cost": 1.74162,
    "instance_id": 1390,
    "public_ip": "Pending",
    "ssh_user": "ubuntu"
  },
  "message": "X-Series Instance Launched Successfully.",
  "status": "success"
}

The returned values depend on the selected VM configuration and the newly created instance.

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 instance was launched successfully.
data.instance_id	Integer	The identifier assigned to the newly created instance.
data.hourly_cost	Number	The hourly cost reported for the newly created instance.
data.public_ip	String	The public IP address assigned to the instance. Initially, this may be Pending.
data.ssh_user	String	The SSH username associated with the instance, such as ubuntu in the example response.

Understanding the Instance Creation Process

After submitting the request:

1. Dataoorts processes Instance creation request using specified VM configs and OS image.
2. When the instance is created successfully, the API returns its instance information.
3. The public_ip field may initially contain Pending updated within 2-5 minutes after boot.
4. After a short period, a public IP address is automatically assigned and attached to the instance.
5. Once the IP address is available and the instance is ready, you can use the returned SSH username and appropriate SSH credentials to connect, subject to the applicable network and access settings.

A successful API response confirms that the instance launch operation succeeded. It does not necessarily mean that the instance is immediately ready for SSH connections.

Important Notes

1. Use the Full VM Name: Always provide the exact VM configuration name, including its displayed price. For example: VM_H100x1_180.0RAM_28CPU_850SSD: $1.74/Hour

2. Use the Complete OS Image Name: The OS-Image value must match the complete operating system image name returned by the OS Images API.

3. Public IP Assignment: The public IP may initially be returned as Pending. Check the instance information endpoint again after a short period to retrieve its latest state and IP address.

4. Instance Costs: The hourly_cost field reports the hourly cost returned by the API. Review the selected configuration and applicable pricing before launching an instance.

5. Handle Request Timeouts Carefully: Instance creation may take time. If request times out or returns error, check whether instance was created before retrying, to avoid unintentionally launching duplicate instances.

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 VM or OS image values, network errors, timeouts, & unexpected response formats. Exact error codes & response messages depend on API response.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. A timeout does not necessarily establish whether the instance was created, so verify the instance state before submitting another creation request.

Get Help and Support

For assistance with instance creation, VM configuration, OS images, or API integration, contact the Dataoorts support team at [email protected].