Create an Instance

This endpoint provisions and launches a new K-Series workstation-based GPU virtual machine using one of the live configuration offers retrieved in real time.

Create an Instance - Overview

The K-Series Create Instance API allows authenticated users to launch a new K-Series GPU virtual machine using one of the currently available instance offers.

The endpoint accepts an instance_name that identifies the desired GPU Instance configuration returned by the Live K-Series GPU Instance Offers API.

Before launching an instance, the API validates that the requested configuration exists, the selected offer is currently available, and the authenticated user has sufficient account balance.

If all validation checks pass, instance provisioning is initiated, and the response includes the local instance ID, provider VID, hourly cost, and initial provisioning status.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/kseries/create
Full URL	https://cloud.dataoorts.com/api/v1/kseries/create
Authentication	Bearer Token
Request Format	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 endpoint requires a JSON request body containing the name of the K-Series GPU configuration to launch.

Parameter	Type	Required	Description
instance_name	String	Yes	The instance offer name returned by the Get Live K-Series Offers endpoint.

Example Request Body

JSON

{
  "instance_name": "v100-5-85-800-generic.4"
}

Important: Always obtain the latest instance_name from the GET /api/v1/kseries/offers endpoint before creating an instance. The name must exactly match one of the available offers returned by that endpoint.

Request Examples

cURL - Use the following command to launch a K-Series GPU instance:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/kseries/create" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_name": "v100-5-85-800-generic.4"
  }'

Replace YOUR_API_KEY with your actual Unify API key.

Use an instance_name returned by the latest K-Series offers response.

Python Example Implementation

The following example uses the requests library to create a K-Series GPU instance. It reads the API key from an environment variable, handles unsuccessful HTTP responses, checks the response format, and displays the returned instance details.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


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


def create_kseries_instance(
    api_key: str,
    instance_name: str,
) -> dict | None:
    """
    Launch a K-Series GPU instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_name: The exact instance offer name returned
                       by the K-Series offers endpoint.

    Returns:
        The JSON response containing the instance creation 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_name": instance_name,
    }

    response = requests.post(
        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."
        )

    try:
        result = create_kseries_instance(
            api_key=api_key,
            instance_name="v100-5-85-800-generic.4",
        )

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

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

            print("\nK-Series Instance Details")
            print("Instance ID:", data.get("instance_id"))
            print("Provider VID:", data.get("provider_vid"))
            print("Hourly Cost:", data.get("hourly_cost"))
            print("Status:", data.get("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_create.py

Windows PowerShell

PowerShell

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

Script submits selected offer name & displays returned instance ID, provider VID, hourly cost, & initial status.

Example Success Response

A successful request returns HTTP 201 Created with a JSON object containing the newly created instance details, a descriptive message, and the response status.

HTTP Status: 201 Created

JSON

{
  "data": {
    "hourly_cost": 1.7068,
    "instance_id": 58,
    "provider_vid": "deb23dd2-70b4-11f1-af18-fba4a7b5def5",
    "status": "Pending"
  },
  "message": "Instance provisioning initiated successfully.",
  "status": "success"
}

The values above illustrate the response structure. Instance identifiers, provider VIDs, and hourly costs may differ in subsequent API responses.

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 result of the instance creation request.
data	Object	Contains the details returned for the newly created K-Series instance.

Instance Record Fields

The data object contains the information returned after the instance creation request.

Field	Type	Description
data.instance_id	Integer	The local instance ID assigned to the newly created instance.
data.provider_vid	String	The DC Provider's instance identifier (VID).
data.hourly_cost	Float	The hourly instance price in USD.
data.status	String	Initial provisioning status returned. Example returns Pending.

Understanding Instance Information

Instance Offer Selection

The instance_name parameter specifies which K-Series GPU configuration to launch.

Before submitting the creation request, retrieve the current offers using GET /api/v1/kseries/offers and select an exact name value from the returned offers.

The API validates that the requested configuration exists and the selected offer is currently available.

Instance Provisioning

When the creation request passes validation, the API initiates instance provisioning.

The response returns an initial status of Pending. Provisioning may take several minutes, depending on data center (DC) provider capacity.

Use the following endpoints to monitor the instance:

• GET /api/v1/kseries/instance — retrieve information about a single instance using its local instance ID or DC Provider VID.
• GET /api/v1/kseries/instances — retrieve all instances associated with the authenticated user.

Continue checking the instance information until the instance becomes active.

Hourly Cost

The hourly_cost field reports the hourly price returned for the selected instance configuration. All pricing values are returned in USD. The supplied endpoint details state that an initial charge of approximately 10 minutes of usage is deducted when provisioning begins. Refer to the applicable Dataoorts billing details for the exact amount charged and the billing policy for the instance.

Provisioning Workflow

The K-Series instance creation process follows these steps:

1. Authenticate the request using your Dataoorts API key.
2. Fetch the latest GPU offers using GET /api/v1/kseries/offers.
3. Select the desired configuration using its exact instance_name.
4. Submit a POST request to /api/v1/kseries/create.
5. The API validates the instance config, offer availability, account balance, & DC provider config.
6. If validation succeeds, provisioning begins and the instance is returned with a Pending status.
7. Use GET /api/v1/kseries/instance or GET /api/v1/kseries/instances to monitor the GPU Instance until it becomes active.

Important Notes

1. Latest Offers: Always retrieve the latest offers before creating an instance. The instance_name must exactly match a name returned by GET /api/v1/kseries/offers.

2. Offer Availability: The selected configuration must be available when the creation request is submitted. An offer that was previously available may become unavailable.

3. Account Balance: The authenticated user must have sufficient account balance for the request to proceed.

4. Initial Status: Newly created instances are returned with a status of Pending. This does not mean the instance is immediately ready for use.

5. Provisioning Time: Provisioning may take several minutes, depending on provider capacity.

6. Pricing Currency: All pricing values are returned in USD.

7. Initial Charge: An initial charge of approximately 10 minutes of usage is deducted when provisioning begins, according to the supplied endpoint details.

8. Database Transaction: If a database error occurs after the provider creates the instance, the API attempts to clean up the provider instance to prevent orphaned resources.

9. Request Timeout: If the request times out, check the instance list before retrying the creation request because the outcome of the original request may be uncertain.

10. 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

API may return an unsuccessful HTTP status code & JSON error response when the instance cannot be created.

Your application should handle authentication failures, invalid request payloads, missing parameters, unavailable offers, insufficient account balance, provider API failures, configuration verification failures, database transaction errors, and unexpected response formats.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. The example also checks the response content type and handles JSON decoding errors before processing the K-Series GPU Instance creation 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.

Invalid JSON

HTTP Status: 400 Bad Request

JSON

{
  "status": "error",
  "message": "Invalid JSON payload."
}

Ensure that the request body contains valid JSON.

Missing Required Field

HTTP Status: 400 Bad Request

JSON

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

Provide the required instance_name field in the JSON request body.

Invalid or Out-of-Stock Offer

HTTP Status: 404 Not Found

JSON

{
  "status": "error",
  "message": "Invalid 'instance_name' or item is currently out of stock."
}

Retrieve the latest offers and verify that the selected instance_name exists and is currently available.

Insufficient Balance

HTTP Status: 402 Payment Required

JSON

{
  "status": "error",
  "message": "Insufficient balance - Required: $0.89, Available: $0.35."
}

Add sufficient funds to your account before submitting the request again. The amounts in this example are illustrative of the supplied response.

DC Provider API Error

HTTP Status: 502 Bad Gateway

JSON

{
  "status": "error",
  "message": "DDRA Server API Error or Capacity full."
}

This response indicates a provider API error or insufficient provider capacity. Check the current offers and try again later if appropriate.

Configuration Verification Failed

HTTP Status: 502 Bad Gateway

JSON

{
  "status": "error",
  "message": "Unable to verify instance configurations right now."
}

The API could not verify the instance configuration. Retry later if the problem persists.

Database Transaction Failed

HTTP Status: 500 Internal Server Error

JSON

{
  "status": "error",
  "message": "Database transaction failed, Instance launch reverted."
}

The API reports that the launch transaction was reverted. Check the instance list 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 the Authorization header with a valid Bearer token.
API key is invalid	Verify the API key through the Dataoorts platform.
Request body is invalid	Send a valid JSON object containing instance_name.
instance_name is missing	Include the required instance_name field.
Offer is invalid or unavailable	Retrieve the latest K-Series offers and select an available config.
Account balance is insufficient	Add sufficient funds before retrying.
Provider returns 502	Check availability and retry later if appropriate.
Configuration verification fails	Retry later if the issue persists.
Database transaction fails	Check the instance list before retrying the creation request.
Request times out	Check whether the instance was created before submitting another 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 instance creation or API integration, Contact support team at [email protected].