Create an Instance

This endpoint provisions and launches a new Atlas Series GPU pod using a preconfigured hardware configuration identifier (config_id). Designed for massive-scale training and cost-efficient deep learning workloads, it instantly allocates containerized NVIDIA accelerator pods with pre-configured environments.

Create an Instance - Overview

The Atlas Series Instance API allows authenticated users to launch an Atlas Series GPU instance using a preconfigured instance configuration ID.

The endpoint accepts a config_id that identifies the Atlas GPU configuration to launch. The response includes the instance ID, container ID, public IP address, SSH username, and total hourly cost.

Use this endpoint to launch an Atlas Series pod with one of the config returned by the Atlas Series offers API.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/atlas/create
Full URL	https://cloud.dataoorts.com/api/v1/atlas/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 Atlas instance configuration ID.

Parameter	Type	Required	Description
config_id	String	Yes	The preconfigured Atlas Series GPU instance configuration ID used to launch the pod. For example, 1xB200-180GB.

Example Request Body

JSON

{
  "config_id": "1xB200-180GB"
}

Use a valid configuration ID returned by the Atlas Series offers endpoint.

Request Examples

cURL - Use the following command to launch an Atlas Series GPU instance:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/atlas/create" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "config_id": "1xB200-180GB"
  }'

Replace YOUR_API_KEY with your actual Unify API key and use the configuration ID you want to launch.

Python Example Implementation

The following example uses the requests library to launch an Atlas Series GPU instance. It reads the API key from an environment variable, handles unsuccessful HTTP responses, and checks whether the API returns a JSON response.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests
from typing import Any


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


def create_atlas_instance(
    api_key: str,
    config_id: str,
) -> dict[str, Any] | None:
    """
    Launch an Atlas Series GPU instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        config_id: The preconfigured Atlas instance configuration ID.

    Returns:
        The JSON response containing the launched instance details,
        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 JSON response cannot be decoded.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "config_id": config_id,
    }

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

    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_atlas_instance(
            api_key=api_key,
            config_id="1xB200-180GB",
        )

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

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

            print("\nAtlas Instance Details")
            print("Instance ID:", data.get("instance_id"))
            print("Container ID:", data.get("container_id"))
            print("Public IP:", data.get("public_ip"))
            print("SSH User:", data.get("ssh_user"))
            print("Total Hourly Cost:", data.get("total_hourly_cost"))

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

Windows PowerShell

PowerShell

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

The script submits the selected configuration ID and displays the returned instance ID, container ID, public IP, SSH username, and total hourly cost when a valid JSON response is received.

Example Success Response

A successful request returns a JSON object containing the launched instance details, a descriptive message, and the response status.

HTTP Status: 200 OK

JSON

{
  "data": {
    "container_id": "container-cqgwyg5vn134o96z",
    "instance_id": 10,
    "public_ip": "38.127.229.94",
    "ssh_user": "ubuntu",
    "total_hourly_cost": 2.49
  },
  "message": "Atlas Instance Launched Successfully.",
  "status": "success"
}

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

Response Fields

Field	Type	Description
status	String	Indicates result of the API request. A successful response returns success.
message	String	A descriptive message about the result of the instance launch request.
data	Object	Contains the details of the launched Atlas Series instance.

Instance Record Fields

The data object contains the information returned for the launched instance.

Field	Type	Description
data.instance_id	Integer	The identifier assigned to the Atlas instance.
data.container_id	String	The container identifier associated with the instance.
data.public_ip	String	The public IP address returned for the instance.
data.ssh_user	String	The SSH username returned for connecting to the instance.
data.total_hourly_cost	Float	The total hourly cost reported for launched configuration.

Understanding Instance Information

Instance Configuration

The config_id specifies which preconfigured Atlas Series GPU configuration to launch. For example, 1xB200-180GB identifies the configuration used in the sample request. Use the Atlas Series offers endpoint to review available configurations before submitting a creation request.

Instance Identification

The response includes both instance_id and container_id. These fields identify the instance and its associated container as reported by the API. Use returned identifiers when referencing instance in subsequent workflows supported by the Atlas Series API.

Public IP and SSH User

The public_ip field provides the IP address returned by the API, while ssh_user provides the SSH username. Use these values when preparing to connect to the instance. The example response alone does not establish whether the instance is immediately ready for an SSH connection.

Hourly Cost

The total_hourly_cost field reports the total hourly cost returned for the launched configuration. In the example response, the value is 2.49. Refer to applicable billing details for exact charging rules.

Important Notes

1. Configuration ID: Provide a valid Atlas Series config_id. The example uses 1xB200-180GB.

2. Instance Launch: This endpoint initiates creation of an Atlas Series pod using the specified configuration.

3. Request Timeout: The example uses a timeout of 180 seconds because instance creation may take longer than a standard information-retrieval request.

4. Response Format: The supplied implementation expects a JSON response. It checks the Content-Type header before attempting to decode the response.

5. Instance Connection: Use the returned public_ip and ssh_user when preparing for SSH access. Confirm that the instance is ready before attempting to connect.

6. Pricing Information: The total_hourly_cost field reports the cost returned by the API. Consult the applicable billing details for exact charging rules.

7. API Key Security: Store your API key in the DATAOORTS_API_KEY environment variable rather than hardcoding it in your application.

Error Handling

If the request fails, the API may return an unsuccessful HTTP status code or a response that does not match the expected JSON format.

Your application should handle authentication failures, network errors, request timeouts, server errors, 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. The example also checks the response content type and handles JSON decoding errors before processing the returned instance details.

Scenario	Recommended Handling
API key is missing	Set the API_KEY secret environment variable.
Authentication fails	Verify that the API key is valid and included in the Authorization header.
HTTP request fails	Catch requests.exceptions.RequestException and inspect the error details.
Request times out	Handle the timeout exception and check the instance information before retrying the creation request.
Response is not JSON	Inspect the returned response text and handle it without attempting to parse it as JSON.
Response contains invalid JSON	Handle the JSON decoding error before accessing response fields.

Avoid blindly retrying an instance creation request after a timeout because the result of the original request may be uncertain.

Get Help and Support

For assistance with Atlas Series pods creation or API integration, contact support team at [email protected].