Restart an Instance

This endpoint resumes and powers on a hibernated or stopped Nova Series GPU virtual machine instance using its unique Instance ID.

Restart an Instance - Overview

The Nova Series Restart API allows authenticated users to restart a hibernated or stopped Nova virtual machine using its instance ID.

This endpoint provides additional flexibility when restarting an instance through two configuration parameters: flexible and contract. These parameters determine whether the instance must restart with its original configuration and which pricing model should be used.

The API supports strict and flexible restart behavior, along with On-Demand, Spot, or existing contract selection. Useful when restarting instances in environments where GPU resource availability may vary.

When the restart succeeds, the API returns the instance type, new hourly cost, public IP address, region, and a confirmation message.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/nova/restart
Full URL	https://cloud.dataoorts.com/api/v1/nova/restart
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_id	Integer	Yes	—	The ID of the Nova instance you want to restart.
flexible	Boolean	No	false	Determines whether the instance can restart with an adjusted configuration if the original resources are unavailable.
contract	String	No	same	Specifies the pricing contract to use: same, on-demand, or spot.

Understanding the flexible Parameter

The flexible parameter determines how the API handles resource availability during a restart.

Value	Behavior
false	Strict mode. The instance attempts to restart with exactly the same configuration as before.
true	Flexible mode. The instance first attempts to restart with its original configuration. If the required resources are unavailable, the API can fall back to a slightly adjusted configuration based on availability.

Flexible mode can help restart an instance when its original GPU configuration is temporarily unavailable. The resulting configuration may differ from the original instance configuration.

Understanding the contract Parameter

The contract parameter controls the pricing model used for the restart.

Value	Description
same	Uses the same pricing contract as the instance's previous configuration.
on-demand	Requests the On-Demand pricing model.
spot	Requests the Spot pricing model.

Choose the contract according to your requirements. The availability of a suitable configuration depends on the selected contract and available resources.

Request Examples

cURL — Strict Mode

Use the following command to restart an instance with its original configuration and existing pricing contract:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/nova/restart" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_id": 430,
    "flexible": false,
    "contract": "same"
  }'

cURL — Flexible Mode

Use flexible mode when the instance can restart with a slightly adjusted configuration if its original resources are unavailable.

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/nova/restart" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_id": 430,
    "flexible": true,
    "contract": "same"
  }'

cURL — Select a Specific Contract

To request a different pricing contract, set contract to on-demand or spot.

For example, to request a Spot restart:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/nova/restart" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_id": 430,
    "flexible": true,
    "contract": "spot"
  }'

Replace YOUR_API_KEY and the example instance ID with your actual values.

Python Example Implementation

The following example uses the requests library to restart a Nova instance with the selected flexibility and pricing contract settings.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


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


def restart_nova_instance(
    api_key: str,
    instance_id: int,
    flexible: bool = False,
    contract: str = "same",
) -> dict:
    """
    Restart a hibernated or stopped Nova instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_id: The ID of the instance to restart.
        flexible: Whether to allow an adjusted configuration
                  if the original resources are unavailable.
        contract: Pricing contract: 'same', 'on-demand', or 'spot'.

    Returns:
        dict: The JSON response returned by the API.

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

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

    contract = contract.lower()

    if contract not in {"same", "on-demand", "spot"}:
        raise ValueError(
            "contract must be 'same', 'on-demand', or 'spot'."
        )

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

    payload = {
        "instance_id": instance_id,
        "flexible": flexible,
        "contract": contract,
    }

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

    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 = restart_nova_instance(
            api_key=api_key,
            instance_id=430,
            flexible=False,
            contract="same",
        )

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

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

        print("Instance Type:", instance.get("instance_type"))
        print("New Hourly Cost:", instance.get("new_hourly_cost"))
        print("Public IP:", instance.get("public_ip"))
        print("Region:", instance.get("region"))

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

Windows PowerShell

PowerShell

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

To use flexible mode, change flexible=False to flexible=True. To select a different pricing model, change contract="same" to either contract="on-demand" or contract="spot".

Example Success Response

When the restart succeeds, the API returns a JSON response containing the updated instance details.

Strict Mode — flexible: false

JSON

{
  "data": {
    "instance_type": "1H100.80S.32V",
    "new_hourly_cost": 2.6335,
    "public_ip": "95.133.252.78",
    "region": "FIN-03"
  },
  "message": "Instance Restarted Successfully (Strict Mode).",
  "status": "success"
}

Flexible Mode — flexible: true

JSON

{
  "data": {
    "instance_type": "1H100.80S.32V",
    "new_hourly_cost": 2.6335,
    "public_ip": "95.133.252.61",
    "region": "FIN-03"
  },
  "message": "Instance Restarted Successfully (Flexible Mode).",
  "status": "success"
}

The examples illustrate the response structure. Actual instance details, pricing, and public IP addresses depend on the result of the restart request.

Note: The supplied flexible-mode example also returns a message containing strict Mode. Verify this message text in the API implementation before publishing if it is not intended wording for a flexible restart.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success.
message	String	A confirmation message describing the restart result and mode reported by the API.
data	Object	Contains updated instance details returned after the restart.
data.instance_type	String	The instance type identifier used for the restarted instance.
data.new_hourly_cost	Float	The new hourly cost reported by the API.
data.public_ip	String	The public IP address returned for the restarted instance.
data.region	String	The region associated with the restarted instance.

Understanding the Restart Process

After submitting the request:

1. API processes the restart request using the supplied instance ID, flexibility setting, and pricing contract.
2. The API attempts to restart the instance using the original configuration.
3. If flexible is true and the original resources are unavailable, the API can fall back to a slightly adjusted configuration, subject to availability.
4. When restart succeeds, API returns the resulting instance type, hourly cost, public IP address, and region.

A successful response confirms the restart result reported by the API. It does not necessarily guarantee that the instance is immediately ready to accept connections.

Important Notes

1. Verify the Instance ID: Ensure that instance_id identifies intended Nova VM before submitting request.

2. Strict Mode: Set flexible to false when the instance must restart with its original configuration.

3. Flexible Mode: Set flexible to true when configuration adjustments are acceptable if the original resources are unavailable.

4. Pricing Contract: Select same, on-demand, or spot according to your requirements. Review the returned new_hourly_cost after the restart.

5. Configuration Changes: In flexible mode, resulting vm configuration may differ from original configuration if the API falls back to available resources. Review instance_type and new_hourly_cost in the response.

6. Public IP Address: Use the public_ip value returned by the API. Do not assume the address will always match a previously recorded IP address.

7. Handle Timeouts Carefully: If the request times out or returns an error, check the instance's current state before retrying. The restart may have been processed even if the client did not receive a 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 instance IDs, invalid contract values, resource availability issues, 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 a successful response.

Get Help and Support

For assistance with Nova instance restarts, configuration flexibility, or pricing contracts, contact the Dataoorts support team at [email protected].