Terminate an Instance

This endpoint permanently terminates a K-Series workstation instance and halts ongoing hourly compute charges using either its Local Instance ID or DC Provider VID.

Terminate an Instance - Overview

The K-Series Terminate Instance API allows authenticated users to terminate an existing K-Series instance associated with their Dataoorts account.

The endpoint supports identifying an instance using either its local instance ID or provider VID. The instance_id parameter can be provided in the JSON request body or as a URL query parameter.

Once terminated, the instance is permanently stopped and billing ends according to the provider's billing policy. Any outstanding usage charges are automatically settled before the instance is marked as terminated.

Warning: This action is irreversible. A terminated instance cannot be restarted.

Endpoint

Property	Value
HTTP Method	DELETE or POST
Endpoint	/kseries/delete
Full URL	https://cloud.dataoorts.com/api/v1/kseries/delete
Authentication	Bearer Token
Request Format	JSON body or URL query parameter
Response Format	JSON

The endpoint accepts DELETE requests and also supports POST requests for clients that do not support the HTTP DELETE method.

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
Content-Type: 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 endpoint requires the instance_id parameter to identify the K-Series instance to terminate.

Parameter	Type	Required	Description
instance_id	String or Integer	Yes	The local instance ID or provider VID of the instance to terminate.

The parameter can be supplied in either the JSON request body or the URL query string.

Example JSON Request Body

JSON

{
  "instance_id": 123
}

You can also provide the DC Provider VID as a string:

JSON

{
  "instance_id": "vs_abcd123456"
}

Replace the example value with the local instance ID or DC provider VID of the instance you want to terminate.

Request Examples

cURL - Use the following command to terminate instance using its local instance ID in JSON request body:

Bash

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

To terminate an instance using its DC Provider VID, Pass the VID as the instance_id value:

Bash

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

Alternative Request Using a Query Parameter

The API also accepts the instance identifier as a URL query parameter.

Using a local instance ID:

Bash

curl --request DELETE \
  --url "https://cloud.dataoorts.com/api/v1/kseries/delete?instance_id=123" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Using a DC Provider VID:

Bash

curl --request DELETE \
  --url "https://cloud.dataoorts.com/api/v1/kseries/delete?instance_id=vs_abcd123456" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Alternative POST Request

Clients that do not support HTTP DELETE method, use POST with the same endpoint & JSON request body:

Bash

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

Replace YOUR_API_KEY with your actual Unify API key and use the identifier of the intended instance.

Python Example Implementation

The following example uses the requests library to terminate a K-Series instance. It reads the API key from an environment variable, supports a local instance ID or provider VID, and handles unsuccessful HTTP responses and unexpected response formats.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


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


def delete_kseries_instance(
    api_key: str,
    instance_id: int | str,
) -> dict | None:
    """
    Terminate a K-Series instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_id: The local instance ID or provider VID.

    Returns:
        The JSON response containing the termination result,
        or None if the API returns a non-JSON response.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the response contains invalid JSON.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "instance_id": instance_id,
    }

    response = requests.delete(
        API_URL,
        headers=headers,
        json=payload,
        timeout=60,
    )

    response.raise_for_status()

    content_type = response.headers.get("Content-Type", "")

    if "application/json" not in content_type.lower():
        print("Non-JSON response received:")
        print(response.text[:500])
        return None

    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."
        )

    # Replace with the local instance ID or provider VID.
    instance_id = 123

    try:
        result = delete_kseries_instance(
            api_key=api_key,
            instance_id=instance_id,
        )

        if result is not None:
            print("Status:", result.get("status"))
            print("Message:", result.get("message"))

            if "current_status" in result:
                print("Current Status:", result.get("current_status"))

    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 in your Env before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python kseries_delete.py

Windows PowerShell

PowerShell

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

Script submits instance identifier & displays returned status & message when valid JSON response is received.

Example Success Response

Successful request returns a JSON object containing termination result, Descriptive message & response status.

JSON

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

The instance ID and response message may differ depending on the instance being terminated.

Already Terminated Response

If the instance has already been terminated, the API returns a successful response instead of an error.

JSON

{
  "status": "success",
  "message": "Instance is already terminated."
}

Response confirms that the instance is already terminated. In this response, current_status is not included.

Response Fields

Field	Type	Description
status	String	Indicates the result of the API request. A successful response returns success; an unsuccessful response returns error.
message	String	A descriptive message about the termination result.
current_status	String	The current instance status returned after termination. The example returns terminated. This field is not included in the already-terminated response.

Understanding Instance Information

Instance Identification

The instance_id parameter identifies the K-Series instance targeted by the request.

You can provide either the local instance ID or the provider VID. The identifier can be supplied in the JSON request body or as a URL query parameter.

Instance Termination

When the API returns "status": "success" with "current_status": "terminated", the response indicates that the instance has been terminated successfully.

If the instance is already terminated, the API returns a successful response with the message Instance is already terminated.

Billing and Connection Information

According to the supplied endpoint details, billing ends according to the provider's billing policy, and any outstanding usage charges are settled before the instance is marked as terminated. After successful termination, the instance status becomes terminated, and its connection information is removed.

Important Notes

1. Permanent Termination: This action is irreversible. A terminated instance cannot be restarted.

2. Instance Identifier: Provide either local instance ID or DC Provider VID through the instance_id parameter.

3. HTTP Methods: The endpoint accepts both DELETE and POST requests. Use DELETE as the primary method; use POST when the client does not support DELETE.

4. Request Parameter Location: The instance_id can be supplied in the JSON request body or as a URL query parameter.

5. Already-Terminated Instances: If the instance has already been terminated, the API returns a successful response instead of an error.

6. User Access: Only instances owned by the authenticated user can be terminated.

7. Billing: Outstanding usage charges are automatically settled before the instance is marked as terminated. Billing ends according to the provider's billing policy.

8. Connection Information: After successful termination, the instance's connection information is removed.

9. Verify Before Termination: Confirm that the identifier refers to the correct instance and back up any required data before submitting the request.

10. Request Timeout: If a request times out, check the instance status before retrying because the result of the original request may be uncertain.

11. API Key Security: Keep your API key confidential and store it in the DATAOORTS_API_KEY environment variable rather than hardcoding it in your application.

Error Handling

The API may return an unsuccessful HTTP status code and a JSON error response when a termination request cannot be completed.

Your application should handle authentication failures, missing instance identifiers, instances that cannot be found or accessed, provider API failures, db transaction errors, server errors, and unexpected response formats.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. Example also checks response content type and handles JSON decoding errors before processing the termination result.

Missing API Key

HTTP Status: 401 Unauthorized

JSON

{
  "status": "error",
  "message": "Authorization header with 'Bearer <TOKEN>' is required."
}

Include the Authorization header with a valid Bearer token.

Invalid API Key

HTTP Status: 403 Forbidden

JSON

{
  "status": "error",
  "message": "Unauthorized: Invalid API key."
}

Verify that your Dataoorts API key is valid and included in the request header.

Missing Instance ID

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Missing required field: 'instance_id'."
}

Provide the required instance_id in the JSON request body or as a URL query parameter.

Instance Not Found

HTTP Status: 404 Not Found

JSON

{
  "status": "error",
  "message": "K-Series instance not found or access denied."
}

Verify that the instance identifier is correct and that the instance belongs to the authenticated user.

Provider API Error

HTTP Status: 502 Bad Gateway

JSON

{
  "status": "error",
  "message": "API failed to delete Instance, Please contact support."
}

This response indicates a provider API failure. Contact the Dataoorts support team if the issue persists.

Database Transaction Error

HTTP Status: 500 Internal Server Error

JSON

{
  "status": "error",
  "message": "Database transaction error during termination."
}

This response indicates an error during the database transaction associated with termination. Check the instance status before retrying the request.

Internal Server Error

HTTP Status: 500 Internal Server Error

JSON

{
  "status": "error",
  "message": "Internal Server Error, Please Contact Support."
}

If the error persists, contact the Dataoorts support team for assistance.

General Error Handling

Scenario	Recommended Handling
API key is missing	Include Authorization header with a valid Bearer token.
API key is invalid	Verify the API key through the Dataoorts platform.
Instance ID is missing	Provide instance_id in request body or query string.
Instance is not found or access is denied	Verify the identifier and confirm that the instance belongs to the authenticated user.
Provider API returns 502	Contact support if the error persists.
Database transaction fails	Check the current instance status before retrying.
Request times out	Verify the instance status before submitting another termination request.
Response is not JSON	Inspect the returned response text without attempting to parse it as JSON.
Response contains invalid JSON	Handle the JSON decoding error before accessing response fields.

Get Help and Support

For assistance with K-Series VM termination or API integration, Contact support team at [email protected].