Create an Instance

This endpoint provisions and launches a new Nova Series GPU virtual machine instance with customized hardware specs, operating system image, storage volume size, and pricing structure.

Create an Instance - Overview

The Nova Series Instance Creation API allows authenticated users to launch a new Nova virtual machine by specifying instance configs, deployment region, operating system image, OS volume size, and pricing contract.

This endpoint supports both On-Demand and Spot instances through the is_spot parameter. It can be integrated into automated provisioning workflows, custom infrastructure dashboards, and applications that dynamically launch GPU instances.

When an instance is launched successfully, the API returns its instance ID, hourly cost, public IP address, SSH username, and provider-side VM identifier.

Important Note: Ensure that you provide the correct instance type, region, and image ID. These values must correspond to valid configurations supported by the Nova platform.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/nova/create
Full URL	https://cloud.dataoorts.com/api/v1/nova/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	Default	Description
instance_type	String	Yes	—	The identifier of the Nova instance configuration to launch, such as 1H100.80S.32V.
region	String	Yes	—	The region where the instance should be deployed, such as FIN-03.
image_id	String	Yes	—	The identifier of the operating system image to use for the instance.
os_size_gb	Integer	No	60	The requested OS volume size in GB.
is_spot	Boolean	No	false	Determines the pricing contract. Set to true for Spot or false for On-Demand.

Selecting the Instance Configuration

Use the Nova Offers API to retrieve available instance configurations and their associated regions: GET /api/v1/nova/offers

Use the Nova OS Images API to retrieve available operating system images: GET /api/v1/nova/images

Make sure the selected instance type, region, and OS image are compatible with the intended deployment.

Request Examples

cURL — Launch an On-Demand Instance

Use the following command to launch a Nova instance with the On-Demand pricing model:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/nova/create" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_type": "1H100.80S.32V",
    "region": "FIN-03",
    "image_id": "ubuntu-24.04-cuda-12.8-open-docker",
    "os_size_gb": 150,
    "is_spot": false
  }'

cURL — Launch a Spot Instance

To request a Spot instance, set is_spot to true.

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/nova/create" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_type": "1H100.80S.32V",
    "region": "FIN-03",
    "image_id": "ubuntu-24.04-cuda-12.8-open-docker",
    "os_size_gb": 150,
    "is_spot": true
  }'

Replace YOUR_API_KEY with your actual Dataoorts Unify API key. Adjust the instance type, region, image ID, and OS size according to your requirements.

Python Example Implementation

The following example uses requests library to launch a Nova instance and display the returned instance info.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


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


def create_nova_instance(
    api_key: str,
    instance_type: str,
    region: str,
    image_id: str,
    os_size_gb: int = 60,
    is_spot: bool = False,
) -> dict:
    """
    Launch a Nova GPU instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_type: Nova instance configuration identifier.
        region: Deployment region code.
        image_id: Operating system image identifier.
        os_size_gb: Requested OS volume size in GB. Defaults to 60.
        is_spot: Whether to request Spot pricing. Defaults to False.

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

    Raises:
        ValueError:
            If the parameters are invalid or the response is not valid JSON.
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
    """
    if not isinstance(os_size_gb, int) or isinstance(os_size_gb, bool):
        raise ValueError("os_size_gb must be an integer.")

    if os_size_gb <= 0:
        raise ValueError("os_size_gb must be greater than zero.")

    if not isinstance(is_spot, bool):
        raise ValueError("is_spot must be a boolean.")

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

    payload = {
        "instance_type": instance_type,
        "region": region,
        "image_id": image_id,
        "os_size_gb": os_size_gb,
        "is_spot": is_spot,
    }

    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_nova_instance(
            api_key=api_key,
            instance_type="1H100.80S.32V",
            region="FIN-03",
            image_id="ubuntu-24.04-cuda-12.8-open-docker",
            os_size_gb=150,
            is_spot=False,
        )

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

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

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

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

Windows PowerShell

PowerShell

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

To launch a Spot instance, change is_spot=False to is_spot=True.

To use the default OS volume size, you can omit the os_size_gb argument. The default value is 60 GB.

Example Success Response

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

JSON

{
  "data": {
    "hourly_cost": 2.6335,
    "instance_id": 430,
    "osd_vmid": "50504a26-5c27-4a69-b8a9-26890bf03b44",
    "public_ip": "95.133.252.120",
    "ssh_user": "root"
  },
  "message": "Nova Instance Launched Successfully.",
  "status": "success"
}

The values shown above illustrate the response structure. The actual instance ID, cost, provider VM ID, and IP address depend on the result of the request.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success.
message	String	A confirmation message indicating that the Nova instance was launched successfully.
data	Object	Contains the details of the newly launched instance.
data.instance_id	Integer	The identifier assigned to the new instance.
data.hourly_cost	Float	The hourly cost reported for the instance.
data.osd_vmid	String	The provider-side VM identifier returned by the API.
data.public_ip	String	The public IP address returned for the instance.
data.ssh_user	String	The SSH username associated with the instance, such as root in the example.

Understanding the Instance Creation Process

After submitting the request:

1. Dataoorts processes the instance creation request using the specified instance type, region, image, OS volume size, and pricing contract.
2. When the instance launches successfully, the API returns its instance information.
3. The response provides the instance ID, reported hourly cost, public IP address, SSH username, and provider-side VM identifier.
4. Use the returned instance ID when calling other Nova endpoints that operate on an individual instance.

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

Important Notes

1. Instance Type: Use a valid instance type identifier returned by the Nova Offers API.

2. Region: Provide a supported region compatible with the selected instance configuration.

3. OS Image: Use the image identifier expected by the Nova creation endpoint. Ensure that it corresponds to a valid image available for the selected configuration.

4. OS Volume Size: The os_size_gb parameter specifies the requested OS volume size in GB. If omitted, the API uses the default value of 60 GB.

5. Pricing Contract: Set is_spot to true for Spot pricing or false for On-Demand pricing.

6. Hourly Cost: The hourly_cost field reports the cost returned by the API. Review the applicable pricing details for the selected contract.

7. Handle Timeouts Carefully: If the request times out or returns an error, check whether the instance was created before retrying. The server may have processed request even if the client did not receive the response.

Error Handling

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

Your application should handle authentication failures, invalid instance types, incompatible regions or images, unsupported OS volume sizes, network errors, request 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 the successful response shown above.

Get Help and Support

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