Terminate an Instance

This endpoint permanently terminates a Nova Series GPU virtual machine instance and deallocates its underlying compute and network resources using its unique Instance ID.

Terminate an Instance - Overview

The Nova Series Instance Termination API allows authenticated users to permanently terminate a Nova virtual machine using its instance ID.

This endpoint permanently deletes the selected instance and all associated data. It is intended for instances that are no longer required and can be integrated into infrastructure cleanup scripts, resource management tools, and automated workflows.

Important Warning: This operation is irreversible. Terminating an instance permanently deletes its associated data, which cannot be recovered through the deleted instance. Back up any required data and verify the instance ID before submitting the request.

Endpoint

Property	Value
HTTP Methods	DELETE or POST
Endpoint	/nova/delete
Full URL	https://cloud.dataoorts.com/api/v1/nova/delete
Authentication	Bearer Token
Content Type	application/json
Response Format	JSON

Both DELETE and POST are supported by the API.

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
instance_id	Integer	Yes	The ID of the Nova instance you want to permanently terminate.

Provide the ID of the intended instance. Carefully verify the identifier before submitting the request because the operation permanently deletes the instance and its associated data.

Request Examples

cURL — DELETE

Use the following command to terminate a Nova instance using the DELETE method:

Bash

curl --request DELETE \
  --url "https://cloud.dataoorts.com/api/v1/nova/delete" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_id": 430
  }'

cURL — POST

Alternatively, you can use the POST method:

Bash

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

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

Python Example Implementation

Following example uses requests library to terminate Nova VM. It supports both DELETE & POST methods.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


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


def delete_nova_instance(
    api_key: str,
    instance_id: int,
    method: str = "DELETE",
) -> dict:
    """
    Permanently terminate a Nova instance.

    WARNING:
        This operation permanently deletes the instance and
        all associated data.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_id: The ID of the instance to terminate.
        method: HTTP method, either DELETE or POST.

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

    Raises:
        ValueError:
            If the HTTP method is invalid or the response
            cannot be decoded as JSON.
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
    """
    method = method.upper()

    if method not in {"DELETE", "POST"}:
        raise ValueError("method must be 'DELETE' or 'POST'.")

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

    payload = {
        "instance_id": instance_id,
    }

    response = requests.request(
        method=method,
        url=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."
        )

    # Verify the instance ID and back up required data before proceeding.
    try:
        result = delete_nova_instance(
            api_key=api_key,
            instance_id=430,
            method="DELETE",
        )

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

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

Windows PowerShell

PowerShell

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

Replace 430 with the ID of the instance you intend to terminate. To use POST instead, change method="DELETE" to method="POST".

Important: The Python example performs the termination request directly. Verify the target instance and back up any required data before running it.

Example Success Response

When an instance is terminated successfully, the API returns a JSON response similar to the following:

JSON

{
  "message": "Instance 430 terminated successfully.",
  "status": "success"
}

The instance ID and message will reflect the actual request.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success.
message	String	A descriptive message confirming that the instance was terminated successfully.

Understanding the Termination Process

After submitting the request:

1. Dataoorts Nova API processes the termination request for the specified instance.
2. If the operation succeeds, the API returns a confirmation message.
3. The instance and its associated data are permanently deleted.
4. The deleted data cannot be recovered through the terminated instance ID.

Important: A successful termination response confirms the result reported by the API. If the request times out or returns an error, do not automatically assume the instance remains active.

Important Notes

1. Permanent Data Loss: Back up any required datasets, application files, configurations, and other important data before terminating the instance.

2. Verify the Instance ID: Confirm that instance_id identifies correct Nova VM before submitting the request.

3. Irreversible Operation: Termination is not the same as rebooting or hibernating an instance. Use this endpoint only when permanent deletion is intended.

4. Handle Timeouts Carefully: If the request times out or returns an error, check the instance's current state before retrying. The 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 instance IDs, network errors, request timeouts, server errors, and unexpected response formats. Error codes & response messages depend on 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 the successful response shown above.

Get Help and Support

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