Get All OS Images

This endpoint retrieves all available operating system images compatible with a specified Nova Series instance type.

Get All OS Images - Overview

The Nova Series OS Images API allows authenticated users to retrieve the operating system images available for a specified Nova instance type.

The endpoint returns image information such as the image name, image type, category, unique image ID, included software details, and default image status. You can optionally provide an instance_type to retrieve images associated with a particular instance configuration.

Use this endpoint to select an operating system image when launching a Nova virtual machine, build OS image selection menus, and automate instance provisioning workflows.

Important Note: Always use the image_type value when launching a new VM instance. The name field is intended for display, while image_type identifies image option to use in the instance launch request.

Endpoint

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

HTTP

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 accepts an optional query parameter.

Parameter	Type	Required	Description
instance_type	String	No	The instance type ID for which you want to retrieve available OS images.

When instance_type is provided, API retrieves the images associated with that instance type. If omitted, the endpoint can be used to retrieve the available images without specifying a particular instance type.

Use the appropriate instance_type identifier returned by the Nova Offers API when filtering images for a specific configuration.

Request Examples

1. Get All Available OS Images

cURL - Retrieve available OS images without specifying an instance type:

Bash

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

2. Get OS Images for a Specific Instance Type

Use the instance_type query parameter to retrieve images for a particular Nova instance configuration.

Bash

curl --get \
  --url "https://cloud.dataoorts.com/api/v1/nova/images" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --data-urlencode "instance_type=1H100.80S.32V"

Replace YOUR_API_KEY with your actual Unify API key and provide the appropriate instance type ID.

Python Example Implementation

Python

import os
import requests


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


def get_nova_images(
    api_key: str,
    instance_type: str | None = None,
) -> dict:
    """
    Retrieve available Nova operating system images.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_type: Optional Nova instance type ID used to
                       filter available OS images.

    Returns:
        dict: The JSON response containing 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",
    }

    params = {}

    if instance_type:
        params["instance_type"] = instance_type

    response = requests.get(
        API_URL,
        headers=headers,
        params=params,
        timeout=60,
    )

    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:
        # Retrieve images for a specific instance type.
        result = get_nova_images(
            api_key=api_key,
            instance_type="1H100.80S.32V",
        )

        # To retrieve images without filtering, use:
        # result = get_nova_images(api_key=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("-" * 40)
            print("Name:", image.get("name"))
            print("Image Type:", image.get("image_type"))
            print("Category:", image.get("category"))
            print("Image ID:", image.get("id"))
            print("Default:", image.get("is_default"))
            print("Cluster Image:", image.get("is_cluster"))
            print("Details:", image.get("details"))

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

Windows PowerShell

PowerShell

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

To retrieve images for a specific instance type, pass its ID through the instance_type argument. To retrieve images without filtering by instance type, omit that argument.

Example Success Response

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

HTTP Status: 200 OK

JSON

{
  "count": 16,
  "images": [
    {
      "category": "docker",
      "details": [
        "Ubuntu 26.04",
        "CUDA 13.2 Open",
        "Docker"
      ],
      "id": "603f7d69-882c-4000-9c25-7843ae307ff6",
      "image_type": "26.04.cuda13.2.docker",
      "is_cluster": false,
      "is_default": false,
      "name": "Ubuntu 26.04 + CUDA 13.2 Open + Docker"
    },
    {
      "category": "ubuntu",
      "details": [
        "Ubuntu 26.04",
        "CUDA 13.2 Open"
      ],
      "id": "e25c357f-01f7-497d-a3fa-36c9c4e27403",
      "image_type": "26.04.cuda13.2",
      "is_cluster": false,
      "is_default": false,
      "name": "Ubuntu 26.04 + CUDA 13.2 Open"
    },
    {
      "category": "jupyterLab",
      "details": [
        "Ubuntu 24.04",
        "CUDA 12.8",
        "PyTorch 2.7"
      ],
      "id": "2222da25-bb0d-41cc-a191-dccae45d96fd",
      "image_type": "jupyter.cuda.12.8",
      "is_cluster": false,
      "is_default": true,
      "name": "Jupyter Nvidia Open Driver"
    }
  ],
  "message": "VM-OS Images",
  "status": "success"
}

The response above is abbreviated to show representative OS image configurations, The actual response may contain additional images depending on the instance type and current availability.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success.
message	String	A descriptive message returned by the API.
count	Integer	The number of OS image entries returned by the API.
images	Array of objects	Contains the available operating system image configurations.
images[].id	String	The unique identifier associated with the OS image.
images[].name	String	The human-readable name of the operating system image.
images[].image_type	String	The image type identifier. Use this value when launching a new VM instance.
images[].category	String	The category associated with the image, such as ubuntu, docker, or jupyterLab.
images[].details	Array of strings	Describes the image components, such as the Ubuntu version, CUDA version, PyTorch version, or Docker availability.
images[].is_default	Boolean	Indicates whether the image is marked as a default option by the API.
images[].is_cluster	Boolean	Indicates whether the image is marked as a cluster image.

Understanding OS Images

OS images provide different base environments and software configurations for virtual machine workloads.

1. Ubuntu Images

Ubuntu images provide a base operating system environment. The image name and details field can identify the Ubuntu version included in the image.

Examples include:

• Ubuntu 24.04
• Ubuntu 26.04

2. CUDA-Enabled Images

Some images include a CUDA configuration intended for GPU workloads. Their names or details fields identify the listed CUDA version and related configuration.

Choose an image that meets your application's software compatibility requirements.

3. Docker Images

Images with a Docker category or a name containing Docker indicate that Docker is included in the image configuration.

These images may be useful for container-based applications and development workflows.

4. Jupyter Images

Images in the jupyterLab category provide Jupyter-oriented environments. Their details fields can identify the listed CUDA and PyTorch configurations.

Review the returned image information to select the environment that best suits your workload.

Using image_type When Launching an Instance

Always use the image_type field when selecting an OS image for a new Nova VM instance.

For example, the API may return the following image:

JSON

{
  "name": "Ubuntu 26.04 + CUDA 13.2 Open + Docker",
  "image_type": "26.04.cuda13.2.docker"
}

Use the value 26.04.cuda13.2.docker as the image selection identifier in the corresponding Nova VM instance creation request.

Do not substitute the display name or the image UUID for image_type unless the relevant instance creation endpoint explicitly requires a different field.

Important Notes

1. Use the Correct Image Identifier: Always use returned image_type value when launching VM instance.

2. Instance Type Filtering: Supply instance_type when you need images associated with a specific config.

3. Default Images: The is_default field identifies images marked as default by the API. Do not assume that an image is the only supported option simply because it is marked as a default.

4. Image Compatibility: Review the image name and details fields to ensure that the selected operating system and included software match your workload requirements.

5. Dynamic Availability: Available images may change. Retrieve the current list before launching an instance rather than permanently hardcoding image options.

6. Image Listing Only: This endpoint retrieves OS image information. It does not launch an instance or install an image by itself.

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 instance type values, network errors, request timeouts, server errors, & unexpected response formats. Error codes & messages depend on API response.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. Do not assume that an error response contains the same fields as a successful response.

Get Help and Support

For assistance with Nova OS images, image compatibility, or API integration, contact the Dataoorts support team at [email protected].