Get Supported OS Images

List All Available OS Images - Overview

The X-Series OS Images API allows authenticated users to retrieve the list of operating system images available for launching virtual machines on the Dataoorts platform.

The endpoint returns the available OS image names, including standard Linux distributions and GPU-optimized images configured with specific NVIDIA drivers, CUDA versions, or Docker support.

Use this API to dynamically retrieve available operating system options when building instance launch workflows, provisioning automation, or custom infrastructure management tools.

The list reflects the images returned by the API at the time of the request. Available images may change as new configurations are introduced or existing images are updated.

Endpoint

Property	Value
HTTP Method	`GET`
Endpoint	`/xseries/images`
Full URL	`https://cloud.dataoorts.com/api/v1/xseries/images`
Authentication	Bearer Token
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.

Authorization: Bearer YOUR_API_KEY
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

This endpoint does not require any query parameters or a request body. Send a GET request with the required authentication header.

Request Examples

cURL - Retrieve all available X-Series operating system images using the following command:

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/xseries/images" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Replace YOUR_API_KEY with your actual Dataoorts Unify API key.

Python Example Implementation:

import os
import requests


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


def get_xseries_os_images(api_key: str) -> dict:
    """
    Retrieve all available X-Series operating system images.

    Args:
        api_key: Your Dataoorts Unify API key.

    Returns:
        dict: The JSON response containing the available OS images.

    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}",
        "Accept": "application/json",
    }

    response = requests.get(
        API_URL,
        headers=headers,
        timeout=30,
    )

    response.raise_for_status()
    return response.json()


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 = get_xseries_os_images(api_key)

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

        print("\nAvailable OS Images:")

        for image in result.get("images", []):
            print("-", image)

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

    except ValueError as exc:
        print(f"Invalid JSON response: {exc}.")

Set your API key before running the script.

Linux / macOS

export DATAOORTS_API_KEY="YOUR_API_KEY"
python xseries_images.py

Windows PowerShell

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

The script prints the response status, total image count, message, and each available OS image.

Example Json Response

A successful request returns a JSON object containing the request status, number of available images, a descriptive message, and an array of image names.

HTTP Status: 200 OK

{
  "status": "success",
  "count": 13,
  "message": "Available X-Series OS images retrieved successfully.",
  "images": [
    "AlmaLinux 9 Plain",
    "Debian 12 Plain",
    "Ubuntu Server 22.04 LTS (Jammy Jellyfish)",
    "Ubuntu Server 22.04 LTS R535 CUDA 12.2",
    "Ubuntu Server 22.04 LTS R535 CUDA 12.2 with Docker",
    "Ubuntu Server 22.04 LTS R550 CUDA 12.4",
    "Ubuntu Server 22.04 LTS R550 CUDA 12.4 H200-opt",
    "Ubuntu Server 22.04 LTS R550 CUDA 12.4 with Docker",
    "Ubuntu Server 22.04 LTS R570 CUDA 12.8",
    "Ubuntu Server 22.04 LTS R570 CUDA 12.8 with Docker",
    "Ubuntu Server 24.04 LTS (Noble Numbat)",
    "Ubuntu Server 24.04 LTS R570 CUDA 12.8",
    "Ubuntu Server 24.04 LTS R570 CUDA 12.8 with Docker"
  ]
}

This example illustrates the response structure, The number and names of available images may differ from the current API response.

Response Fields

Field	Type	Description
`status`	String	Indicates result of API request, Successful response returns `success`.
`count`	Integer	The number of OS images returned in the response.
`message`	String	A descriptive message about the result of the request.
`images`	Array of strings	The available operating system image names that can be used in supported X-Series instance launch workflows.

Each item in the images or os_images array is an OS image name returned by the API.

Understanding OS Images

Dataoorts provides different os images for general-purpose workloads and GPU-enabled workloads.

Standard OS images: Standard images, such as AlmaLinux & Debian, provide base operating system env. for supported workloads.

GPU-optimized images: Images containing NVIDIA driver and CUDA version identifiers are configured for GPU-related workloads. The driver and CUDA versions can help you select an image that matches your application's software requirements.

Docker-enabled images: Images labelled with Docker include Docker support for container-based workloads, according to the image configuration.

Specialized GPU images: Some images include additional identifiers, such as H200-opt, for specific configurations or optimized environments.

Always review image name and its compatibility with your intended workload before launching an instance.

Using OS Images in Instance Launch Workflows

You can use this endpoint to populate an os selection menu in your application or automation workflow.

A typical workflow is:

Authenticate with your Dataoorts API key.
Request the available OS images from the X-Series Images API.
Read the returned images or os_images array.
Present the available image names to the user or select an appropriate image for your workload.
Use selected image in corresponding vm launch request, following that endpoint parameter requirements.

Important: This endpoint lists available image names, It does not launch a virtual machine or independently provide every configuration detail associated with an image.

Error Handling

If the request fails, the API may return an HTTP error response instead of the successful JSON response.

Common causes include auth errors, unsuccessful HTTP responses, network failures, or invalid response format.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes, Handle these exceptions to prevent failed requests from interrupting your application.

Do not assume that error responses contain the same fields as a successful response.

Get Help and Support

For assistance with OS images, X-Series configuration, or API integration, contact the Dataoorts support team.

Support Email: [email protected]