> ## Documentation Index
> Fetch the complete documentation index at: https://io.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cluster Deployment using APIs

> Step-by-step guide for developers to deploy, price, and manage GPU clusters programmatically using io.net Cloud VMaaS APIs.

This page outlines the end-to-end flow for deploying a GPU cluster using [**io.net**](http://io.net) **Cloud VMaaS APIs**. It is intended to help you understand the steps you can take and API calls needed to provision, price, and manage a cluster programmatically.

### Workflow Summary

The cluster deployment process consists of the following steps:

1. **Retrieve available hardware**

   Use the [**GET Hardware List**](/reference/vmaas/get-hardware-list) endpoint to fetch all supported GPU hardware configurations, including available GPU counts, locations, and resource specifications.
2. **Select hardware and configuration**\
   From the hardware list response, select the desired hardware type, number of GPUs per VM, and deployment region.
3. **Validate deployment pricing (optional)**\
   Use the [**GET Deployment Price**](/reference/vmaas/get-deployment-price) endpoint to calculate the expected cost for the selected hardware configuration and duration.
4. **Deploy the cluster**

   Use the [**POST Deploy VM**](/reference/vmaas/deploy-vms) endpoint to provision the cluster using the selected hardware, GPU count, location, and duration.
5. **Manage the cluster lifecycle**

   After deployment, manage the cluster using one of the following endpoints:

   * [**POST Extend Cluster**](/reference/vmaas/extend-cluster) endpoint to increase the deployment duration.
   * [**DELETE Destroy Deployment**](/reference/vmaas/destroy-deployment) endpoint to terminate the cluster early.

<Note>
  The first hour of usage is non-refundable.
</Note>

<Steps>
  <Step title="Retrieving Available Hardware" titleSize="h3">
    Using the [GET Hardware List](/reference/vmaas/get-hardware-list) endpoint, retrieve all currently available GPU hardware configurations.

    **Request Example**

    ```bash theme={null}
    curl -X 'GET' \
      'https://api.io.solutions/enterprise/v1/io-cloud/vmaas/hardware' \
      -H 'accept: application/json' \
      -H 'x-api-key: <api-key>'
    ```

    <Accordion title="Response Example">
      ```json theme={null}
      {
          "data": {
              "hardware": [
                  {
                      "id": "12__2",
                      "deploy_id": 12,
                      "name": "GeForce RTX 4090",
                      "num_cards": 2,
                      "supplier": "internal",
                      "sold_out": false,
                      "price": 0.6,
                      "vram_per_card": 24,
                      "interconnect": null,
                      "nvlink": false,
                      "storage": 1000,
                      "vcpu": 39,
                      "memory": 125,
                      "location": "US"
                  },
                  {
                      "id": "12__1",
                      "deploy_id": 12,
                      "name": "GeForce RTX 4090",
                      "num_cards": 1,
                      "supplier": "internal",
                      "sold_out": false,
                      "price": 0.3,
                      "vram_per_card": 24,
                      "interconnect": null,
                      "nvlink": false,
                      "storage": 500,
                      "vcpu": 39,
                      "memory": 125,
                      "location": "US"
                  },
                  {
                      "id": "B200_sxm6x8__US",
                      "deploy_id": "B200_sxm6x8",
                      "name": "B200",
                      "num_cards": 8,
                      "supplier": "external",
                      "sold_out": false,
                      "price": 39.92,
                      "vram_per_card": 192,
                      "interconnect": "sxm6",
                      "nvlink": false,
                      "storage": 22528,
                      "vcpu": 208,
                      "memory": 2900,
                      "location": "US"
                  },
                  {
                      "id": "B200_sxm6x8__AU",
                      "deploy_id": "B200_sxm6x8",
                      "name": "B200",
                      "num_cards": 8,
                      "supplier": "external",
                      "sold_out": false,
                      "price": 39.92,
                      "vram_per_card": 192,
                      "interconnect": "sxm6",
                      "nvlink": false,
                      "storage": 22528,
                      "vcpu": 208,
                      "memory": 2900,
                      "location": "AU"
                  }
              ]       
           }
      }
      ```
    </Accordion>
  </Step>

  <Step title="Selecting your Hardware and Configuration" titleSize="h3">
    From the response of the [GET Hardware List](/reference/vmaas/get-hardware-list) endpoint, select your chosen GPU and save the following values:

    <ResponseField name="deploy_id" type="string/integer" required>
      Hardware identifier used for pricing and deployment. Can be a string or integer.
    </ResponseField>

    <ResponseField name="num_cards" type="integer" required>
      Number of GPUs per VM.
    </ResponseField>

    <ResponseField name="location" type="string" required>
      Deployment region.
    </ResponseField>
  </Step>

  <Step title="Validating your Deployment Price (Optional)" titleSize="h3">
    Using the [GET Deployment Price](/reference/vmaas/get-deployment-price) endpoint and the values you have saved, validate the price of your desired deployment before you deploy your cluster.

    **Request Example**

    ```bash theme={null}
    curl -X GET "https://api.io.solutions/enterprise/v1/io-cloud/vmaas/price" \
      -H "x-api-key: YOUR_API_KEY" \
      --data-urlencode "hardware_id=12" \
      --data-urlencode "gpus_per_vm=1" \
      --data-urlencode "replica_count=1" \
      --data-urlencode "duration_hours=1" \
      --data-urlencode "currency=usdc" \
      --data-urlencode 'location_ids=["US"]'
    ```

    Ensure that the following fields have been assigned a value:

    <ResponseField name="hardware_id" type="string/integer" required>
      Value of `deploy_id` from the Hardware List response.
    </ResponseField>

    <ResponseField name="gpus_per_vm" type="integer" required>
      Number of GPUs per VM. Value of `num_cards` from the Hardware List response.
    </ResponseField>

    <ResponseField name="duration_hours" type="integer" required>
      Duration of your deployment, in hours.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Pricing currency.

      *Example:* `usdc`
    </ResponseField>

    <ResponseField name="location_ids" type="string" required>
      URL-encoded JSON array of locations. Use `--data-urlencode`  in your cURL request if you use a plain string.

      *Example:* `%5B%22US%22%5D` = `["US"]`
    </ResponseField>
  </Step>

  <Step title="Deploying your Cluster" titleSize="h3">
    Using the POST Deploy VM enndpoint, deploy your selected hardware for the specified duration.

    **Request Example**

    ```bash theme={null}
    curl -X POST "https://api.io.solutions/enterprise/v1/io-cloud/vmaas/deploy" \
      -H "Content-Type: application/json" \
      -H 'x-api-key: <api-key>'
      -d '{
        "resource_private_name": "name of cluster",
        "duration_hours": 1,
        "gpus_per_vm": 1,
        "hardware_id": 12,
        "location_ids": ["US"],
        "ssh_keys": {
          "name of key": "<public-key>"
        }
      }'
    ```

    Ensure that the following fields have been assigned a value:

    <ResponseField name="resource_private_name" type="string" required>
      The name of your cluster.
    </ResponseField>

    <ResponseField name="duration_hours" type="integer" required>
      Duration of your deployment, in hours.
    </ResponseField>

    <ResponseField name="gpus_per_vm" type="integer" required>
      Number of GPUs per VM. Value of `num_cards` from the Hardware List response.
    </ResponseField>

    <ResponseField name="hardware_id" type="string/integer" required>
      Value of `deploy_id` from the Hardware List response.
    </ResponseField>

    <ResponseField name="location_ids" type="string" required>
      Location of your chosen GPU.
    </ResponseField>

    <ResponseField name="ssh_keys" type="object" required>
      Your public SSH key, use RSA, ECDSA, or ED25519.

      *Format:* `"name of key": "<public-key>"`
    </ResponseField>
  </Step>
</Steps>