Restart Hibernated Instance

This endpoint wakes and restarts a hibernated or stopped X-Series GPU virtual machine instance using its Instance ID or IP address.

Wake Up a Hibernated Instance - Overview

The X-Series Restart API allows authenticated users to restart a hibernated or stopped virtual machine using its IP address or Instance ID.

This endpoint is useful for bringing an existing instance back online without creating a new virtual machine. It can be integrated into infrastructure automation scripts, application workflows, and custom instance management dashboards.

When a restart request succeeds, the API returns a confirmation message and the instance's public IP status. The public IP may initially be returned as Pending while the instance is being brought back online.

Important Note: Restarting an instance is subject to GPU availability.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/xseries/restart
Full URL	https://cloud.dataoorts.com/api/v1/xseries/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	Description
id_or_ip	String	Yes	The Instance ID or IP address of the hibernated or stopped virtual machine you want to restart.

Provide the identifier of the instance you want to bring back online. Verify that the identifier corresponds to the intended instance before submitting the request.

Request Examples

cURL - Use the following command to restart an instance using its Instance ID:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/xseries/restart" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "id_or_ip": "1373"
  }'

You can also provide the instance's IP address:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/xseries/restart" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "id_or_ip": "38.128.233.51"
  }'

Replace YOUR_API_KEY and the example identifier with your actual values.

Python Example Implementation:

Python

import os
import requests


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


def restart_xseries_instance(
    api_key: str,
    id_or_ip: str,
) -> dict:
    """
    Restart a hibernated or stopped X-Series instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        id_or_ip: The instance ID or IP address.

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

    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 = {
        "id_or_ip": id_or_ip,
    }

    response = requests.post(
        API_URL,
        headers=headers,
        json=payload,
        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:
        result = restart_xseries_instance(
            api_key=api_key,
            id_or_ip="1373",
        )

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

        if result.get("public_ip") == "Pending":
            print(
                "The instance is restarting. "
                "Its public IP is not yet available in the response."
            )

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

Windows PowerShell

PowerShell

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

To restart an instance using its IP address, replace "1373" in the function call with the appropriate IP address.

Example Success Response

When the restart request succeeds, the API returns a JSON response similar to the following:

JSON

{
  "message": "Instance restarted successfully.",
  "public_ip": "< same public_ip >",
  "status": "success"
}

The values returned depend on the result of the restart request.

Response Fields

Field	Type	Description
status	String	Indicates result of API request - A successful response returns success.
message	String	Descriptive message confirming that Instance restart request succeeded.
public_ip	String	The same public IP value returned by the API.

Understanding the Restart Process

A successful response confirms that the API reports the restart operation as successful. It does not necessarily mean that the instance is already fully operational or ready to accept connections.

After submitting the request:

1. Dataoorts verify and processes the restart request.
2. The instance begins returning to an operational state.
3. The Instance public_ip will remain same.

Important Notes

1. Restart Time: Allow at least 2-5 minutes for a hibernated instance to restart, Plan your deployment and workload schedules accordingly.

2. Static IP Retention: If the instance has a static IP address, that IP address remains the same after hibernation, according to the hibernation behavior documented by Dataoorts.

3. Restarting Existing Instances: This endpoint restarts an existing hibernated or stopped instance. It does not create a new virtual machine.

4. Handling Timeouts: If the request times out or returns an error, the restart may still have been initiated. Check the instance state before retrying the request to avoid unnecessary repeated restart attempts.

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 identifiers, network errors, timeouts, and unexpected response formats. The exact error codes and response messages depend on the API response.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes.

Get Help and Support

For assistance with instance restarts or API integration, contact the Dataoorts support team at [email protected]​.