### Start Virtual Machine using Hyperstack Cloud API

Source: https://docs.hyperstack.cloud/docs/faq

This snippet demonstrates how to initiate the startup process for a virtual machine that is in the 'SHUTOFF' state. It uses a GET request to the '/core/virtual-machines/{virtual_machine_id}/start' endpoint. A successful request returns a JSON object confirming the VM is scheduled to start. Ensure you replace '{virtual_machine_id}' with the actual ID of your VM and provide your 'api_key'.

```shell
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{virtual_machine_id}/start" \
  -H "accept: application/json" \
  -H "api_key: YOUR API KEY"
```

--------------------------------

### Install Packages and Start Service with Bash Script

Source: https://docs.hyperstack.cloud/docs/virtual-machines/initialization-configuration

This Bash script installs the 'HTTPd' and 'vim' packages using apt, enables and starts the 'HTTPd' service, and creates a simple 'index.html' file in the web server's root directory. It's designed for Debian-based systems.

```bash
#!/bin/bash  
# install additional packages  
sudo apt install -y HTTPd vim  
# enable and start the HTTPd service  
sudo systemctl enable HTTPd  
sudo systemctl start HTTPd  
# create a file in HTTP document root  
sudo echo "<p>hello world</p>" > /var/www/html/index.html  

```

--------------------------------

### Start virtual machine

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/virtual-machines/manage-vms

Starts a virtual machine. The VM will transition through STARTING state before becoming ACTIVE.

```APIDOC
## GET /core/virtual-machines/{id}/start

### Description
Starts a virtual machine.

### Method
GET

### Endpoint
`/core/virtual-machines/{id}/start`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the virtual machine.

### Response
#### Success Response (200)
- **status** (string) - The current status of the virtual machine operation (e.g., STARTING, ACTIVE).

#### Response Example
```json
{
  "status": "STARTING"
}
```
```

--------------------------------

### Install Hyperstack Python SDK from Source

Source: https://docs.hyperstack.cloud/docs/libraries/python

Installs the Hyperstack SDK by cloning the GitHub repository and running the setup script. This method is suitable for developers contributing to the SDK or needing to modify it.

```bash
git clone https://github.com/NexGenCloud/hyperstack-sdk-python.git
cd hyperstack-sdk-python
python setup.py install --user
```

--------------------------------

### Get Available Operating System Images

Source: https://docs.hyperstack.cloud/docs/api-reference/getting-started-api/create-virtual-machine

Retrieves a list of available operating system (OS) images that can be installed on your virtual machine.

```APIDOC
## GET /core/images

### Description
Call the GET /core/images endpoint to retrieve the list of available operating system (OS) images, and choose the OS to be installed on your virtual machine.

### Method
GET

### Endpoint
/core/images

### Parameters
#### Headers
- **api_key** (string) - Required - Your API key for authentication.

### Request Example
```bash
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/images"   -H "accept: application/json"  -H "api_key: YOUR API KEY"
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the result of the request.
- **images** (array) - An array of OS image objects, categorized by region and type.
  - **region_name** (string) - The name of the region where the images are available.
  - **type** (string) - The type of the operating system (e.g., "Ubuntu").
  - **logo** (string) - The URL of the OS logo.
  - **images** (array) - An array of specific OS image details.
    - **id** (integer) - The unique identifier for the OS image.
    - **name** (string) - The name of the OS image (e.g., "Ubuntu Server 22.04 LTS").
    - **region_name** (string) - The name of the region the image belongs to.
    - **type** (string) - The type of the operating system.
    - **version** (string) - The version of the operating system.
    - **size** (integer) - The size of the OS image in bytes.
    - **description** (string|null) - A description of the OS image.
    - **labels** (array) - An array of labels associated with the image.
    - **display_size** (string) - The display size of the OS image (e.g., "10.0 GB").
    - **is_public** (boolean) - Indicates if the image is publicly available.

#### Response Example
```json
{
    "status": true,
  "message": "Getting images successful",
  "images": [
    {
      "region_name": "NORWAY-1",
      "type": "Ubuntu",
      "logo": "https://infrahub-api.nexgencloud.com/os-logos/ubuntu.svg",
      "images": [
        {
          "id": 34,
          "name": "Ubuntu Server 22.04 LTS",
          "region_name": "NORWAY-1",
          "type": "Ubuntu",
          "version": "Server 22.04 LTS",
          "size": 10737418240,
          "description": null,
          "labels": [],
          "display_size": "10.0 GB",
          "is_public": true
        },
        {...}
      ]
    }
  ]
}
```
```

--------------------------------

### Install Nvidia Drivers on Ubuntu 20.04 (cloud-init)

Source: https://docs.hyperstack.cloud/docs/hardware/gpu-driver-compability

This cloud-init script installs Nvidia drivers on Ubuntu 20.04. It downloads the CUDA keyring, updates package lists, and installs the CUDA toolkit. Ensure the system has internet connectivity.

```yaml
#cloud-config
runcmd:
  - 'wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-keyring_1.0-1_all.deb'
  - 'sudo dpkg -i cuda-keyring_1.0-1_all.deb'
  - 'sudo apt-get update'
  - 'sudo apt-get -y install cuda'

```

--------------------------------

### Install Nvidia Drivers on Ubuntu 22.04 (cloud-init)

Source: https://docs.hyperstack.cloud/docs/hardware/gpu-driver-compability

This cloud-init script installs Nvidia drivers on Ubuntu 22.04. It downloads the CUDA keyring, updates package lists, and installs the CUDA toolkit. Ensure the system has internet connectivity.

```yaml
#cloud-config
runcmd:
  - 'wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.0-1_all.deb'
  - 'sudo dpkg -i cuda-keyring_1.0-1_all.deb'
  - 'sudo apt-get update'
  - 'sudo apt-get -y install cuda'

```

--------------------------------

### Automate Nvidia Driver Installation on Linux VMs (cloud-init)

Source: https://docs.hyperstack.cloud/docs/hardware/gpu-driver-compability

This cloud-init script automates the download and execution of an Nvidia driver installation script on Linux-based virtual machines. It first downloads the installer script from a specified URL and then executes it. The script includes error handling and a reboot command.

```cloud-init
#cloud-config
write_files:
  - path: /tmp/download_and_run_script_nvidia.sh
    permissions: '0755'
    content: |
      #!/bin/bash
      set -e

      # Download the script
      echo "Downloading the init script..."
      SCRIPT_URL="https://api.nexgencloud.com:8080/public/nvidia/installer_script_main.sh"
      SCRIPT_NAME=$(basename "${SCRIPT_URL}")

      # Use wget if available, otherwise use curl
      if command -v wget >/dev/null 2>&1;
          then
              wget -O "/tmp/${SCRIPT_NAME}" "${SCRIPT_URL}"
          else
              curl -o "/tmp/${SCRIPT_NAME}" "${SCRIPT_URL}"
      fi

      # Make the downloaded script executable
      chmod +x "/tmp/${SCRIPT_NAME}"
      echo "Running the init script..."
      /tmp/${SCRIPT_NAME}

runcmd:
  - /tmp/download_and_run_script_nvidia.sh
  - [ shutdown, -r, now ]

```

--------------------------------

### Install Nvidia Drivers on Windows (Network Installer)

Source: https://docs.hyperstack.cloud/docs/hardware/gpu-driver-compability

Instructions for installing Nvidia drivers on Windows 10, 11, 2019 Server, and 2022 Server using the network installer. This method involves downloading an executable and following on-screen prompts. A reboot is recommended after installation.

```text
1. Download **cuda_12.3.1_windows_network.exe**
2. Follow on-screen prompts.
```

--------------------------------

### Start Virtual Machine

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/virtual-machines/manage-vms/start-vm

Initiates the startup of a virtual machine. Supply the virtual machine ID in the path to initiate the starting of the specified virtual machine.

```APIDOC
## GET /v1/core/virtual-machines/{id}/start

### Description
Initiates the startup of a virtual machine. Supply the virtual machine ID in the path to initiate the starting of the specified virtual machine.

### Method
GET

### Endpoint
/v1/core/virtual-machines/{id}/start

#### Path Parameters
- **id** (integer) - Required - The unique identifier of the virtual machine to be started.

#### Request Example
```curl
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{id}/start" \
  -H "accept: application/json" \
  -H "api_key: YOUR API KEY"
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates the result of the request to start the VM. `true` signifies success, while `false` indicates an error.
- **message** (string) - A description of the status of the request to start the VM.

#### Response Example
```json
{
  "status": true,
  "message": "string"
}
```
```

--------------------------------

### Install Docker Compose (Bash)

Source: https://docs.hyperstack.cloud/docs/tutorials/chatbot-support

Downloads and installs the latest version of Docker Compose, a tool for multi-container Docker applications. It retrieves the binary, places it in the executable path, and sets permissions.

```bash
VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | grep -Po '"tag_name": "\K.*\d')
DESTINATION=/usr/local/bin/docker-compose

sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION
sudo chmod +x /usr/local/bin/docker-compose
```

--------------------------------

### JSONL Data Format Example for AI Studio

Source: https://docs.hyperstack.cloud/docs/ai-studio/getting-started

This snippet illustrates the required format for JSONL files used to upload training data to Hyperstack AI Studio. Each line must be a valid JSON object representing a conversation, with 'messages' containing objects that specify 'role' and 'content'.

```json
{"messages": [{"role": "user", "content": "What's the capital of Australia?"}, {"role": "assistant", "content": "The capital of Australia is Canberra."}]}
{"messages": [{"role": "system", "content": "You are a travel advisor."}, {"role": "user", "content": "Where should I go in Europe for a summer vacation?"}, {"role": "assistant", "content": "Consider Italy, Spain, or Greece—they offer great weather, food, and culture in the summer!"}]}
{"messages": [{"role": "user", "content": "What's the capital of Australia?"}, {"role": "assistant", "content": "The capital of Australia is Canberra."}]}
```

--------------------------------

### Start a virtual machine

Source: https://docs.hyperstack.cloud/docs/virtual-machines/manage-vm-state

Initiates the startup process for a specified virtual machine.

```APIDOC
## GET /core/virtual-machines/{virtual_machine_id}/start

### Description
Starts a virtual machine. This operation is used to bring a stopped virtual machine back online.

### Method
GET

### Endpoint
/core/virtual-machines/{virtual_machine_id}/start

### Parameters
#### Path Parameters
- **virtual_machine_id** (string) - Required - The unique identifier of the virtual machine to start.

### Response
#### Success Response (200)
- **status** (string) - The updated status of the virtual machine (e.g., 'STARTING', 'ACTIVE').

#### Response Example
```json
{
  "status": "STARTING"
}
```
```

--------------------------------

### Retrieve Volume Details - cURL Example

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/volumes/retrieve-volume-details

Example of how to retrieve details for a specific volume using a cURL command. This demonstrates the necessary GET request, URL structure, and headers for authentication and content type.

```curl
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/volumes/123" \
  -H "accept: application/json" \
  -H "api_key: YOUR API KEY"
```

--------------------------------

### POST /v1/core/virtual-machines

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/virtual-machines/vm-core/create-vms

This endpoint allows you to create a new virtual machine instance. You can specify various parameters such as the VM name, image, flavor, and whether to assign a floating IP. Optionally, you can save the configuration as a provisioning profile by including a 'profile' object with 'name' and 'description'.

```APIDOC
## POST /v1/core/virtual-machines

### Description
Provisions a new virtual machine instance with specified configurations. Supports saving VM configurations as provisioning profiles.

### Method
POST

### Endpoint
`/v1/core/virtual-machines`

### Parameters
#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the virtual machine.
- **environment_name** (string) - Required - The name of the environment where the VM will be deployed.
- **image_name** (string) - Required - The name of the virtual machine image to use.
- **flavor_name** (string) - Required - The name of the virtual machine flavor (instance type).
- **key_name** (string) - Required - The name of the SSH key pair to associate with the VM.
- **assign_floating_ip** (boolean) - Optional - Whether to assign a floating IP address to the VM.
- **enable_port_randomization** (boolean) - Optional - Whether to enable port randomization for the VM.
- **count** (integer) - Optional - The number of VM instances to create (defaults to 1).
- **profile** (object) - Optional - Configuration object for creating a provisioning profile.
  - **name** (string) - Required - The name of the provisioning profile.
    Maximum length of 50 characters.
  - **description** (string) - Required - A brief description of the provisioning profile.
    Maximum length of 150 characters.
- **labels** (array of strings) - Optional - User-defined tags for the VM. Each label must consist only of alphanumeric characters, hyphens (`-`), or underscores (`_`), not exceed 100 characters, and a maximum of 10 labels per VM.
- **contract_id** (integer) - Optional - The ID of the contract to assign the VM to.

### Request Example
```json
{
  "name": "example-vm",
  "environment_name": "example-env",
  "image_name": "Ubuntu Server 22.04 LTS R535 CUDA 12.2",
  "flavor_name": "n3-A100x1",
  "key_name": "example-key",
  "assign_floating_ip": true,
  "enable_port_randomization": true,
  "count": 1,
  "profile": {
    "name": "web-server-profile",
    "description": "Standard web server configuration"
  },
  "labels": ["production", "web"],
  "contract_id": 12345
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates the result of the request. `true` for success, `false` for error.
- **message** (string) - A description of the status of the request.
- **instances** (array of objects) - An array containing details about the created VM instances. Refer to linked documentation for detailed object structure.

#### Response Example
```json
{
  "status": true,
  "message": "VM is scheduled for creation.",
  "instances": [
    {
      "id": 287911,
      "name": "example-vm",
      "status": "CREATING",
      "environment": {
        "id": 29862,
        "name": "example-env",
        "org_id": 3971,
        "region": "CANADA-1",
        "features": {
          "network_optimised": true,
          "green_status": "GREEN"
        }
      },
      "image": {
        "name": "Ubuntu Server 22.04 LTS R535 CUDA 12.2"
      },
      "flavor": {
        "id": 100,
        "name": "n3-A100x1",
        "cpu": 28,
        "ram": 120.0,
        "disk": 100,
        "ephemeral": 750,
        "gpu": "A100-80G-PCIe",
        "gpu_count": 1,
        "labels": [],
        "features": {
          "network_optimised": false,
          "no_hibernation": false,
          "no_snapshot": false,
          "local_storage_only": false
        }
      },
      "os": "Ubuntu Server 22.04 LTS R535 CUDA 12.2",
      "keypair": {
        "name": "example-key"
      },
      "volume_attachments": [],
      "power_state": null,
      "vm_state": null,
      "fixed_ip": null,
      "floating_ip": null,
      "floating_ip_status": "ATTACHING",
      "security_rules": [],
      "callback_url": null,
      "locked": false,
      "contract_id": null,
      "labels": [],
      "created_at": "2025-07-03T15:46:07",
      "features": {
        "network_optimised": false,
        "green_status": "GREEN"
      },
      "is_snapshotting": false,
      "cluster_id": null,
      "port_randomization": true,
      "port_randomization_status": "ENABLING",
      "requires_public_ip": false
    }
  ]
}
```

### Error Handling
If contract assignment fails, the VM will still be created on-demand, and the response will detail the reasons for failure.

### Authentication
API requests must include an `api_key` header with your valid API Key.
```

--------------------------------

### List Environments API Request (curl)

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/environments/list-environments

Example of how to make a GET request to the environments API endpoint using curl. This includes specifying the accept header and the API key for authentication.

```curl
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/environments" \
  -H "accept: application/json" \
  -H "api_key: YOUR API KEY"
```

--------------------------------

### POST /v1/core/profiles

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/profiles/create-profile

Creates a new virtual machine profile with specified configuration details. This includes environment, image, flavor, and other networking settings.

```APIDOC
## POST /v1/core/profiles

### Description
Creates a new virtual machine profile with specified configuration details. This includes environment, image, flavor, and other networking settings.

### Method
POST

### Endpoint
/v1/core/profiles

### Parameters
#### Request Body
- **name** (string) - Required - The name of the profile.
- **description** (string) - Optional - A description for the profile.
- **data** (object) - Required - The virtual machine configuration details.
  - **environment_name** (string) - Required - The name of the environment.
  - **image_name** (string) - Required - The name of the base image.
  - **volume_name** (string) - Optional - The name of the volume to attach.
  - **create_bootable_volume** (boolean) - Optional - Whether to create a bootable volume.
  - **flavor_name** (string) - Required - The name of the instance flavor.
  - **key_name** (string) - Required - The name of the key pair for SSH access.
  - **user_data** (string) - Optional - User data script to be executed on instance startup.
  - **callback_url** (string) - Optional - URL to receive notifications about profile creation status.
  - **assign_floating_ip** (boolean) - Optional - Whether to assign a floating IP address.
  - **count** (integer) - Optional - The number of instances to create.

### Request Example
```json
{
  "name": "profile-1",
  "description": "This is an example profile.",
  "data": {
    "environment_name": "Test-env",
    "image_name": "Ubuntu Server 20.04 LTS",
    "volume_name": "",
    "create_bootable_volume": "false",
    "flavor_name": "n1-cpu-medium",
    "key_name": "key pair -1",
    "user_data": "",
    "callback_url": "",
    "assign_floating_ip": "false",
    "count": "1"
  }
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the status of the operation.
- **profile** (object) - The created profile object.
  - **description** (string) - Description of the profile.
  - **id** (integer) - Unique identifier for the profile.
  - **name** (string) - Name of the profile.
  - **data** (object) - The virtual machine configuration saved as a profile.
    - **environment_name** (string) - The name of the environment.
    - **image_name** (string) - The name of the base image.
    - **volume_name** (string) - The name of the volume.
    - **create_bootable_volume** (boolean) - Whether a bootable volume was created.
    - **flavor_name** (string) - The name of the instance flavor.
    - **key_name** (string) - The name of the key pair.
    - **user_data** (string) - User data script.
    - **callback_url** (string) - Callback URL.
    - **assign_floating_ip** (boolean) - Whether a floating IP was assigned.
    - **count** (integer) - The number of instances created.
  - **created_at** (string) - The timestamp when the profile was created (ISO 8601 format).

#### Response Example
```json
{
  "status": true,
  "message": "Profile created successfully",
  "profile": {
    "description": "This is an example profile.",
    "id": 4,
    "name": "profile-1",
    "data": {
      "environment_name": "Test-env",
      "image_name": "Ubuntu Server 20.04 LTS",
      "volume_name": "",
      "create_bootable_volume": false,
      "flavor_name": "n1-cpu-medium",
      "key_name": "key pair -1",
      "user_data": "",
      "callback_url": "",
      "assign_floating_ip": false,
      "count": 1
    },
    "created_at": "2023-05-19T08:45:58"
  }
}
```
```

--------------------------------

### List Kubernetes Clusters (HTTP)

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/clusters/list-clusters

Example of how to list Kubernetes clusters using an HTTP GET request. This demonstrates the endpoint, required headers for authentication, and the expected content type.

```curl
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters" \
 -H "accept: application/json" \
 -H "api_key: YOUR API KEY"
```

--------------------------------

### Chat Completion API Endpoint

Source: https://docs.hyperstack.cloud/docs/ai-studio/getting-started

This endpoint allows you to interact with deployed models in a chat-like interface. You can send messages and receive responses, with options for streaming and various generation parameters.

```APIDOC
## POST /ai/api/v1/chat/completions

### Description
Sends a message to a specified model and receives a response. Supports streaming of responses and various generation parameters to control output.

### Method
POST

### Endpoint
/ai/api/v1/chat/completions

### Parameters
#### Headers
- **api_key** (string) - Required - Your Hyperstack API key for authentication.
- **Content-Type** (string) - Required - Must be 'application/json'.

#### Request Body
- **model** (string) - Required - The identifier of the model to use for generation (e.g., 'mistralai/Mistral-Small-24B-Instruct-2501').
- **messages** (array) - Required - An array of message objects, each with a 'role' (e.g., 'user', 'system', 'assistant') and 'content' (string).
- **stream** (boolean) - Optional - If true, the response will be streamed in chunks. Defaults to false.
- **max_tokens** (integer) - Optional - Maximum number of tokens to generate. Defaults to 100.
- **temperature** (number) - Optional - Controls randomness. Lower values (e.g., 0.1) focus output, higher values (e.g., 0.9) generate diverse responses. Defaults to 0.5.
- **top_p** (number) - Optional - Controls nucleus sampling. The model considers tokens with cumulative probability <= top_p. Defaults to 0.5.
- **top_k** (integer) - Optional - Limits token sampling to the top K most likely options. Defaults to 40.
- **presence_penalty** (number) - Optional - Penalizes tokens that have already appeared. Defaults to 0.1.
- **repetition_penalty** (number) - Optional - Penalizes repeated tokens to reduce redundancy. Defaults to 0.5.

### Request Example
```json
{
  "model": "mistralai/Mistral-Small-24B-Instruct-2501",
  "messages": [
    {"role": "user", "content": "Hi"}
  ],
  "stream": true
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the response.
- **object** (string) - Type of the object, typically 'chat.completion' or 'chat.completion.chunk'.
- **created** (integer) - Timestamp of creation.
- **model** (string) - The model used for generation.
- **choices** (array) - An array of completion choices.
  - **index** (integer) - Index of the choice.
  - **message** (object) - The message content.
    - **role** (string) - Role of the sender ('assistant').
    - **content** (string) - The generated text response.
  - **finish_reason** (string) - The reason the generation finished (e.g., 'stop', 'length').

#### Response Example (Non-streaming)
```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "mistralai/Mistral-Small-24B-Instruct-2501",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
```

#### Response Example (Streaming Chunk)
```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion.chunk",
  "created": 1677652289,
  "model": "mistralai/Mistral-Small-24B-Instruct-2501",
  "choices": [
    {
      "index": 0,
      "delta": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": null
    }
  ]
}
```
```

--------------------------------

### Create a VM

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/virtual-machines/manage-vms

Creates a new virtual machine. The VM goes through states like CREATING, BUILD, and finally ACTIVE if successful.

```APIDOC
## POST https://infrahub-api.nexgencloud.com/v1/core/virtual-machines

### Description
Creates a new virtual machine.

### Method
POST

### Endpoint
`https://infrahub-api.nexgencloud.com/v1/core/virtual-machines`

### Parameters
#### Request Body
- **configuration** (object) - Required - Specifies the VM configuration (e.g., CPU, RAM, image).
  - **cpu** (integer) - Required - Number of CPUs.
  - **ram_gb** (integer) - Required - Amount of RAM in GB.
  - **image_id** (string) - Required - The ID of the OS image to use.

### Request Example
```json
{
  "configuration": {
    "cpu": 2,
    "ram_gb": 4,
    "image_id": "ubuntu-20.04-server"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created virtual machine.
- **vm_state** (string) - The current state of the VM (e.g., CREATING, BUILD, ACTIVE, ERROR).

#### Response Example
```json
{
  "id": "vm-12345abcde",
  "vm_state": "CREATING"
}
```
```

--------------------------------

### List Policies API Request - Curl

Source: https://docs.hyperstack.cloud/docs/api-reference/auth-resources/policies

Example of how to make a GET request to the List Policies API endpoint using curl. This includes specifying the endpoint URL, the expected response format (application/json), and an authorization header.

```shell
curl -X GET "https://infrahub-api.nexgencloud.com/v1/auth/policies" \
  -H "accept: application/json" \
  -H "api_key: YOUR API KEY"
```

--------------------------------

### POST /v1/core/profiles

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/profiles/create-profile

Creates a provisioning profile by saving the configuration of a virtual machine for future use. You can specify details like the environment, OS image, flavor, SSH key, and whether to assign a public IP.

```APIDOC
## POST /v1/core/profiles

### Description
Creates a provisioning profile by saving the configuration of a virtual machine for future use. You can specify details like the environment, OS image, flavor, SSH key, and whether to assign a public IP.

### Method
POST

### Endpoint
https://infrahub-api.nexgencloud.com/v1/core/profiles

### Parameters
#### Request Body
- **name** (string) - Required - Name of the profile being created. Max length: 50 characters.
- **data** (object) - Required - The configuration of the virtual machine profile being created.
  - **environment_name** (string) - Required - Name of the environment within which your virtual machine will be created.
  - **image_name** (string) - Required - Name of the operating system image to be installed on your virtual machine. Use GET /core/images to retrieve a list of images. Optional if creating from an existing bootable volume.
  - **flavor_name** (string) - Required - Name of the flavor corresponding to the hardware configuration for your virtual machine. Use GET /core/flavors to retrieve a list of available flavors.
  - **key_name** (string) - Required - Name of the SSH keypair to be used for secure access to the virtual machine.
  - **count** (integer) - Required - Number of virtual machines to be deployed.
  - **assign_floating_ip** (boolean) - Optional - Designates whether or not to assign a public IP address to the virtual machine.
  - **create_bootable_volume** (boolean) - Optional - Specify whether to create a virtual machine from a volume with an operating system image installed. Set to true to enable creation from a bootable volume.
  - **user_data** (string) - Optional - Initialization configuration data in the form of cloud-init scripts to be executed during virtual machine deployment.
  - **callback_url** (string) - Optional - The URL where callback events will be sent whenever actions are executed on the virtual machine.
- **description** (string) - Optional - The optional description for the profile being created. Max length: 150 characters.

### Request Example
```json
{
  "name": "webserver-profile",
  "description": "Profile for deploying web servers",
  "data": {
    "environment_name": "production",
    "image_name": "ubuntu-20.04",
    "flavor_name": "medium",
    "key_name": "my-ssh-key",
    "count": 1,
    "assign_floating_ip": true,
    "create_bootable_volume": false,
    "user_data": "#!/bin/bash\necho \"Hello, World!\" > /tmp/hello.txt",
    "callback_url": "https://example.com/callback"
  }
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Specifies the status of the profile creation. `true` indicates success.
- **message** (string) - A message describing the success or failure of the request.
- **profile** (object) - An object containing the configuration of the virtual machine saved in the created profile.

#### Response Example
```json
{
  "status": true,
  "message": "Profile created successfully",
  "profile": {
    "name": "webserver-profile",
    "description": "Profile for deploying web servers",
    "data": {
      "environment_name": "production",
      "image_name": "ubuntu-20.04",
      "flavor_name": "medium",
      "key_name": "my-ssh-key",
      "count": 1,
      "assign_floating_ip": true,
      "create_bootable_volume": false,
      "user_data": "#!/bin/bash\necho \"Hello, World!\" > /tmp/hello.txt",
      "callback_url": "https://example.com/callback"
    }
  }
}
```
```

--------------------------------

### Retrieve Cluster Details API - cURL Example

Source: https://docs.hyperstack.cloud/docs/kubernetes/kubernetes-guide

This snippet demonstrates how to use the cURL command-line tool to make a GET request to the Retrieve Cluster Details API. It includes placeholders for the cluster ID and API key. The response provides the cluster's operational status and details.

```bash
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/clusters/{id}" \
 -H "accept: application/json"\
 -H "api_key: YOUR API KEY"
```

--------------------------------

### Retrieve VM Events History (cURL)

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/virtual-machines/retrieve-events-history

Example using cURL to make a GET request to the Hyperstack Cloud API to retrieve the event history for a virtual machine. This requires the virtual machine ID and an API key.

```bash
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{virtual_machine_id}/events" \
  -H "accept: application/json"\
  -H "api_key: YOUR API KEY"
```

--------------------------------

### POST /v1/instances

Source: https://docs.hyperstack.cloud/docs/libraries/go

Creates a new virtual machine instance with specified configurations.

```APIDOC
## POST /v1/instances

### Description
This endpoint allows you to create a virtual machine instance with detailed specifications, including name, environment, OS image, machine flavor, network settings, and security rules.

### Method
POST

### Endpoint
/v1/instances

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **Name** (string) - Required - The name for the virtual machine.
- **EnvironmentName** (string) - Required - The name of the environment where the VM will be created.
- **KeyName** (string) - Required - The name of the SSH key to be associated with the VM.
- **ImageName** (string) - Required - The name of the OS image to use for the VM.
- **FlavorName** (string) - Required - The machine flavor (e.g., CPU, RAM) for the VM.
- **Count** (integer) - Optional - The number of instances to create. Defaults to 1.
- **AssignFloatingIp** (boolean) - Optional - Whether to assign a floating IP address to the VM.
- **Labels** (array of strings) - Optional - Labels to apply to the VM for organization.
- **SecurityRules** (array of objects) - Optional - A list of security rules to apply to the VM.
  - **Direction** (string) - Required - 'ingress' or 'egress'.
  - **Ethertype** (string) - Required - 'IPv4' or 'IPv6'.
  - **Protocol** (string) - Required - The network protocol (e.g., 'tcp', 'udp', 'icmp').
  - **RemoteIpPrefix** (string) - Required - The source or destination IP address range.
  - **PortRangeMin** (integer) - Optional - The minimum port number for the rule.
  - **PortRangeMax** (integer) - Optional - The maximum port number for the rule.

### Request Example
```json
{
  "Name": "my-vm-2",
  "EnvironmentName": "default-CANADA-1",
  "KeyName": "canada-key-prod-040624",
  "ImageName": "Ubuntu Server 22.04 LTS (Jammy Jellyfish)",
  "FlavorName": "n1-cpu-medium",
  "Count": 1,
  "AssignFloatingIp": true,
  "Labels": ["sdk-example"],
  "SecurityRules": [
    {
      "Direction": "ingress",
      "Ethertype": "IPv4",
      "Protocol": "tcp",
      "RemoteIpPrefix": "0.0.0.0/0",
      "PortRangeMin": 22,
      "PortRangeMax": 22
    },
    {
      "Direction": "ingress",
      "Ethertype": "IPv6",
      "Protocol": "tcp",
      "RemoteIpPrefix": "::/0",
      "PortRangeMin": 22,
      "PortRangeMax": 22
    }
  ]
}
```

### Response
#### Success Response (200)
- **ID** (string) - The unique identifier of the created virtual machine.
- **Name** (string) - The name of the virtual machine.
- **Status** (string) - The current status of the virtual machine (e.g., 'BUILD', 'ACTIVE', 'ERROR').
- **IPAddress** (string) - The primary IP address assigned to the VM.
- **FloatingIPAddress** (string) - The floating IP address assigned to the VM, if requested.

#### Response Example
```json
{
  "ID": "vm-12345abcde",
  "Name": "my-vm-2",
  "Status": "BUILD",
  "IPAddress": "10.0.1.10",
  "FloatingIPAddress": "192.168.1.100"
}
```

### Error Handling
- **400 Bad Request**: Invalid request payload or parameters.
- **401 Unauthorized**: API key is missing or invalid.
- **404 Not Found**: Specified environment or image not found.
- **500 Internal Server Error**: An error occurred on the server.
```

--------------------------------

### POST /core/virtual-machines

Source: https://docs.hyperstack.cloud/docs/api-reference/getting-started-api/create-virtual-machine

Creates a new virtual machine with specified configurations. You can customize the image, hardware flavor, SSH key, and network settings.

```APIDOC
## POST /core/virtual-machines

### Description
Creates a new virtual machine with specified configurations. You can customize the image, hardware flavor, SSH key, and network settings.

### Method
POST

### Endpoint
/v1/core/virtual-machines

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API key for authentication.

#### Request Body
- **name** (string) - Required - The name of the virtual machine.
- **environment_name** (string) - Required - The name of the environment.
- **image_name** (string) - Required - Name of the image chosen from the GET `/core/images` endpoint response.
- **create_bootable_volume** (boolean) - Optional - Indicates whether to create a bootable volume. `true` creates a volume, `false` does not.
- **flavor_name** (string) - Required - Name of the flavor (hardware configuration) chosen from the GET `/core/flavors` endpoint response.
- **key_name** (string) - Required - Name of the SSH keypair used to import an SSH key.
- **user_data** (string) - Optional - Custom data or scripts to be executed during virtual machine deployment.
- **assign_floating_ip** (boolean) - Optional - Designates whether to assign a public IP address. `true` makes it publicly accessible, `false` does not.
- **count** (integer) - Required - Number of virtual machines to deploy.

### Request Example
```json
{
  "name": "dev-server",
  "environment_name": "development",
  "image_name": "Ubuntu Server 22.04 LTS",
  "create_bootable_volume": false,
  "flavor_name": "n3-RTX-A6000x1",
  "key_name": "development-key",
  "user_data": "",
  "assign_floating_ip": true,
  "count": 1
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the operation was successful.
- **message** (string) - A message confirming the successful creation of instances.
- **instances** (array) - An array of instance objects containing details of the created virtual machines.
  - **id** (integer) - The unique identifier of the virtual machine.
  - **name** (string) - The name of the virtual machine.
  - **status** (string) - The current status of the virtual machine (e.g., `CREATING`).
  - **created_at** (string) - The timestamp when the virtual machine was created.
  - **keypair** (object) - Information about the SSH keypair.
  - **environment** (object) - Information about the environment.
  - **image** (object) - Information about the image used.
  - **flavor** (object) - Information about the flavor used.

#### Response Example
```json
{
  "status": true,
  "message": "Instances are created successfully",
  "instances": [
    {
      "id": 4,
      "name": "example-vm",
      "status": "CREATING",
      "created_at": "2023-05-17T10:01:29",
      "keypair": {
        "name": "development-key"
      },
      "environment": {
        "name": "development"
      },
      "image": {
        "name": "Ubuntu Server 20.04 LTS"
      },
      "flavor": {
        "name": "n3-RTX-A6000x1"
      }
    }
  ]
}
```
```

--------------------------------

### List Node Groups using curl

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/clusters/node-groups/list-node-groups

Example request to retrieve a list of node groups for a given cluster ID using curl. This demonstrates how to make a GET request to the Hyperstack API endpoint and includes necessary headers.

```curl
curl -X GET "https://infrahub-api.nexgencloud.com/v1/clusters/123/node-groups" \
  -H "accept: application/json" \
  -H "api_key: YOUR_API_KEY"
```

--------------------------------

### JSONL File Format Example

Source: https://docs.hyperstack.cloud/docs/ai-studio/models/fine-tuning-guide

Illustrates a single entry within a JSON Lines (.jsonl) file used for training AI models. Each entry must be on a single line and contains a 'messages' object simulating a conversation with 'role' and 'content' fields.

```json
{
    "messages": [
        {
            "role": "user",
            "content": "What is Hyperstack AI Studio?"
        },
        {
            "role": "assistant",
            "content": "Hyperstack AI Studio offers a suite of services including fine-tuning, evaluation, playground, and inference to support developers in building powerful AI Studio applications."
        }
    ]
}
```

--------------------------------

### Start Virtual Machine API Request (curl)

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/virtual-machines/manage-vms/start-vm

This snippet demonstrates how to initiate the startup of a virtual machine using a curl command. It requires the virtual machine ID and an API key for authentication. The response indicates the success or failure of the operation.

```shell
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{id}/start" \
  -H "accept: application/json"\
  -H "api_key: YOUR API KEY"
```

--------------------------------

### Verify PVC and Pod Creation

Source: https://docs.hyperstack.cloud/docs/kubernetes/csi-driver

Verifies the successful creation and status of the PersistentVolumeClaim (PVC) and Pod. The 'kubectl get pvc' command shows the PVC status and its bound volume, while 'kubectl describe pod' provides detailed information about the pod, including its volume mounts.

```bash
kubectl get pvc my-pvc
kubectl describe pod my-pod
```

--------------------------------

### NFS Client Cloud-Init Script for Hyperstack

Source: https://docs.hyperstack.cloud/docs/faq

This cloud-init script configures a virtual machine to connect to an NFS share as a client. It installs required packages, mounts the remote NFS share, and makes it accessible locally. Modify the NFS server address and local mount point according to your setup.

```cloud-config
#cloud-config

packages:
    - nfs-common
package_update: true

mounts:
    - [ "10.0.0.128:/data/nfshare", "/mnt", "nfs", "defaults", "0","0" ]

runcmd:
    - mount /mnt

```

--------------------------------

### Create Virtual Machine via API (cURL)

Source: https://docs.hyperstack.cloud/docs/api-reference/core-resources/virtual-machines/vm-core/create-vms

Example cURL command to create a virtual machine. This request requires authentication via an 'api_key' header and specifies VM configuration details such as name, image, flavor, and key name. It also includes options for assigning a floating IP and enabling port randomization.

```curl
curl -X POST "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines" \
  -H "accept: application/json" \
  -H "api_key: YOUR API KEY" \
  -H "content-type: application/json" \
  -d '{ \
    "name": "example-vm", \
    "environment_name": "example-env", \
    "image_name": "Ubuntu Server 22.04 LTS R535 CUDA 12.2", \
    "flavor_name": "n3-A100x1", \
    "key_name": "example-key", \
    "assign_floating_ip": true, \
    "enable_port_randomization": true, \
    "count": 1 \
  }'
```