Create an Instance

This endpoint provisions and launches a new Orion Series GPU virtual machine or Bare Metal instance using three core parameters: offer_id, region_id, and os_image. It is used to programmatically spin up high-value, cost-efficient compute nodes for deep learning workloads, parallel analytics, and model inference.

Create an Instance - Overview

The Orion Series Instance Creation API allows authenticated users to launch a new Orion virtual machine using three required parameters: offer_id, region_id, and os_image.

The selected offer determines the GPU configuration and associated hourly pricing, while the region and operating system image specify where the instance will be deployed and which OS image it will use.

When the request is accepted, the API returns the instance ID, hostname, provider VM ID, hourly cost, and current provisioning status.

Important Note: Ensure that the offer_id, region_id, and os_image values are correct and compatible before submitting the request.

🔒 Security Notice: For enhanced security, it is strongly recommended that you change the default SSH password immediately after establishing your initial connection to the instance.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/orion/create
Full URL	https://cloud.dataoorts.com/api/v1/orion/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
offer_id	String	Yes	The identifier of the Orion GPU instance offer you want to launch, such as H200x1.
region_id	String	Yes	The identifier of the deployment region, such as kansascity-usa-4.
os_image	String	Yes	The identifier of the os image to use for the instance, such as ubuntu22.04_cuda12.4_shade_os.

Use offer, region, & supported image information returned by the Orion Offers API to select compatible values.

Request Examples

cURL - Use the following command to launch an Orion instance:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/orion/create" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "offer_id": "H200x1",
    "region_id": "kansascity-usa-4",
    "os_image": "ubuntu22.04_cuda12.4_shade_os"
  }'

Replace YOUR_API_KEY with your actual Dataoorts Unify API key. Make sure the selected offer, region, and OS image are valid for your intended deployment.

Python Example Implementation

The following example uses the requests library to submit an instance creation request and display the returned instance details.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


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


def create_orion_instance(
    api_key: str,
    offer_id: str,
    region_id: str,
    os_image: str,
) -> dict:
    """
    Launch a new Orion GPU instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        offer_id: The identifier of the selected Orion offer.
        region_id: The identifier of the deployment region.
        os_image: The operating system image identifier.

    Returns:
        dict: The JSON response containing the launch result
              and instance 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 = {
        "offer_id": offer_id,
        "region_id": region_id,
        "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_orion_instance(
            api_key=api_key,
            offer_id="H200x1",
            region_id="kansascity-usa-4",
            os_image="ubuntu22.04_cuda12.4_shade_os",
        )

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

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

        print("Instance ID:", instance.get("instance_id"))
        print("Hostname:", instance.get("hostname"))
        print("Provider VM ID:", instance.get("provider_vmid"))
        print("Hourly Cost:", instance.get("hourly_cost"))
        print("Instance Status:", instance.get("status"))

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

Windows PowerShell

PowerShell

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

The script submits the creation request and displays the instance identifiers, hourly cost, and provisioning status returned by the API.

Example Success Response

When the instance provisioning request is accepted successfully, the API returns a JSON response similar to the following:

JSON

{
  "data": {
    "hostname": "inst-ae3ea7dec73f4986a452",
    "hourly_cost": 2.4952,
    "instance_id": 50,
    "provider_vmid": "sf-6979d897dbe948d5b8ff1ec6",
    "status": "pending"
  },
  "message": "Instance provisioning initiated for you successfully.",
  "status": "success"
}

The values shown above illustrate the response structure. Actual instance identifiers, hostname, hourly cost, and provisioning status depend on the result of the request.

Response Fields

Field	Type	Description
status	String	Result of API request, Successful response returns success.
message	String	A descriptive message confirming that instance provisioning was initiated successfully.
data	Object	Contains the details returned for the newly requested instance.
data.instance_id	Integer	The identifier assigned to the Orion instance.
data.hostname	String	The hostname returned for the instance.
data.provider_vmid	String	The Instance identifier returned by the underlying provider.
data.hourly_cost	Float	The hourly_cost reported for the instance in USD per Hour.
data.status	String	The instance provisioning status reported by the API, such as pending in the example response.

Understanding the Instance Creation Process

After submitting the request:

1. Dataoorts API processes the instance creation request using the supplied offer, region, and OS image.
2. If the provisioning request is accepted, the API returns the instance details and a confirmation message.
3. The returned data.status may be pending/Pending while provisioning is in progress.
4. Use returned instance_id when working with other Orion endpoints that require an instance identifier.

A successful API response with a pending status indicates that provisioning has been initiated; it does not necessarily mean that the instance is fully ready to use.

Important Notes

1. Correct Offer ID: Use a valid offer_id returned by the Orion Offers API.

2. Region Compatibility: Ensure that region_id matches a region available for the selected offer.

3. Supported OS Image: Provide an OS image supported by the selected offer. You can identify supported images through the supported_images field returned by the Offers API.

4. Provisioning Status: Instance initially report pending. Check its status before relying on it for workloads.

5. Hourly Cost: The hourly_cost field reports the cost returned by the API. Review the selected offer and applicable pricing information before launching the instance.

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

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 offer IDs, unsupported regions or OS images, network errors, request timeouts, server errors, 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 Orion instance creation, offer selection, region compatibility, or API integration, contact the Dataoorts support team at [email protected].