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

# Elastic Deployment API

> GPUhub Elastic Deployment API: A simple, token-authenticated REST API that lets any user programmatically create, scale, monitor, and manage pay-per-second GPU containers for AI/ML workloads.

<Warning>
  Note: API operations are not supported for on-demand GPU instances. All API features are designed for Elastic Deployment only.
</Warning>

## 1. List Private Images

### → Request

```
POST /api/v1/dev/image/private/list
```

```json Request Body theme={null}
{
  "page_index": 1,
  "page_size": 10
}
```

### ← Response

Response Parameters

| Parameter   | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| `code`      | String | Response status. `Success` on success |
| `msg`       | String | Error message. Empty when successful  |
| `data.list` | List   | List of image objects                 |

`response` Object Fields

| Parameter    | Type   | Description                                 |
| ------------ | ------ | ------------------------------------------- |
| `id`         | Int    | Image ID                                    |
| `image_name` | String | Image name                                  |
| `image_uuid` | String | Image UUID (used when creating deployments) |

```json Response (on success) theme={null}
{
    "code": "Success",
    "msg": ""
    "data": {
        "list": [
            {
                "id": 111,
                "created_at": "2022-01-20T18:34:08+08:00",
                "updated_at": "2022-01-20T18:34:08+08:00",
                "image_uuid": "image-db8346e037",
                "image_name": "image name",
                "status": "finished",
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "max_page": 1,
        "offset": 0,
    },
}
```

```python Python theme={null}
import requests
headers = {
    "Authorization": "your token",
    "Content-Type": "application/json"
}
url = "https://api.gpuhub.com/api/v1/dev/image/private/list"
body = {
    "page_index": 1,
    "page_size": 10,
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())
```

## 2. Create Deployment

### → Request

```
POST /api/v1/dev/deployment
```

Place all parameters in the request body. Details are as follows:

| Parameter                    | Type             | Required                      | Description                                                                                    |
| ---------------------------- | ---------------- | ----------------------------- | ---------------------------------------------------------------------------------------------- |
| `name`                       | String           | Yes                           | Deployment name                                                                                |
| `deployment_type`            | String           | Yes                           | Deployment type: `ReplicaSet`, `Job`, or `Container`                                           |
| `replica_num`                | Int              | Required for ReplicaSet & Job | Desired number of container replicas                                                           |
| `parallelism_num`            | Int              | Required for Job only         | Max number of containers running in parallel (for Job type)                                    |
| `reuse_container`            | Bool             | No                            | Whether to reuse stopped containers (significantly speeds up creation). Default: `false`       |
| `reuse_container_scope`      | String           | No                            | Scope of reuse: `all` (account-wide) or `deployment` (current deployment only). Default: `all` |
| `service_6006_port_protocol` | String           | No                            | Protocol for port 6006 mapping: `http` or `tcp.` Default: `http`                               |
| `service_6008_port_protocol` | String           | No                            | Protocol for port 6008 mapping: `http` or `tcp.` Default: `http`                               |
| `container_template`         | Container Object | Yes                           | Container template (see below)                                                                 |

`container_template` Object

| Parameter                             | Type           | Required | Description                                                                        |
| ------------------------------------- | -------------- | -------- | ---------------------------------------------------------------------------------- |
| `dc_list`                             | `list<String>` | Yes      | List of available regions (data centers). See Appendix for values                  |
| `cuda_v_from`                         | Int            | Yes      | Minimum CUDA version supported by driver (e.g., `118` = CUDA 11.8). See Appendix   |
| `cuda_v_to`                           | Int            | Yes      | Maximum CUDA version (higher versions are backward compatible)                     |
| `gpu_name_set`                        | `list<String>` | Yes      | Allowed GPU models (e.g., `["RTX 5090", "RTX Pro 6000"]`)                          |
| `gpu_num`                             | Int            | Yes      | Number of GPUs per container                                                       |
| `cpu_num_from` / `cpu_num_to`         | Int            | Yes      | CPU core range (1 vCPU units)                                                      |
| `memory_size_from` / `memory_size_to` | Int            | Yes      | Memory range in GB                                                                 |
| `price_from` / `price_to`             | Int            | Yes      | Price range in USD \* 1000 (e.g., USD0.10/hr → `100`, USD9.00/hr → `9000`)         |
| `image_uuid`                          | String         | Yes      | UUID of your private image or public base image                                    |
| `cmd`                                 | String         | Yes      | Startup command (executed when container starts)                                   |
| `cmd_before_shutdown`                 | String         | No       | Command executed before container stops (5-second timeout; forced stop on timeout) |

```json Request Body theme={null}
{
 "name": "api-auto-created",
 "deployment_type": "ReplicaSet",
 "replica_num": 2,
 "reuse_container": true,
 "container_template": {
   "dc_list": ["Singpore-A", "Singapore-B"],
   "gpu_name_set": ["RTX 5090", "RTX Pro 6000"],
   "cuda_v_from": 130,
   "cuda_v_to": 999,
   "gpu_num": 1,
   "cpu_num_from": 4,
   "cpu_num_to": 64,
   "memory_size_from": 16,
   "memory_size_to": 256,
   "cmd": "python main.py",
   "price_from": 100,    // base price: $0.10/hr
   "price_to": 9000,     // base price: $9.00/hr
   "image_uuid": "base-image-ec1e9vdbd3"
 }
}

```

### ← Response

```json Response (on success) theme={null}
{
   "code": "Success",
   "msg": "",
   "data": {
       "deployment_uuid": "833f1cd5a764fa3"
   }
}
```

```python Python theme={null}
import requests

headers = {
    "Authorization": "your token",
    "Content-Type": "application/json"
}

url = "https://api.gpuhub.com/api/v1/dev/deployment"

# Example 1: Create a ReplicaSet deployment (auto-scaling)
body = {
    "name": "my-inference-service",
    "deployment_type": "ReplicaSet",
    "replica_num": 2,
    "reuse_container": True,
    "container_template": {
        "dc_list": ["Singpore-A", "Singapore-B"],
        "gpu_name_set": ["RTX 5090", "RTX Pro 6000"],
        "gpu_num": 1,
        "cuda_v_from": 118,
        "cuda_v_to": 128,
        "cpu_num_from": 4,
        "cpu_num_to": 64,
        "memory_size_from": 16,
        "memory_size_to": 256,
        "cmd": "python main.py",
        "price_from": 100,   # $0.10/hr (price × 1000)
        "price_to": 9000,    # $9.00/hr (price × 1000)
        "image_uuid": "image-xxxxxxxx"
    }
}

response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

# Example 2: Create a Job deployment (batch processing)
{
    "name": "batch-training-job",
    "deployment_type": "Job",
    "replica_num": 4,
    "parallelism_num": 1,
    "reuse_container": True,
    "container_template": {
        "dc_list": ["Singpore-A"],
        "gpu_name_set": ["RTX 5090"],
        "gpu_num": 1,
        "cuda_v_from": 118,
        "cuda_v_to": 128,
        "cpu_num_from": 8,
        "cpu_num_to": 64,
        "memory_size_from": 32,
        "memory_size_to": 256,
        "cmd": "python train.py",
        "price_from": 100,
        "price_to": 9000,
        "image_uuid": "image-xxxxxxxx"
    }
}

# Example 3: Create a single Container deployment
{
    "name": "debug-container",
    "deployment_type": "Container",
    "reuse_container": True,
    "container_template": {
        "dc_list": ["Singpore-A"],
        "gpu_name_set": ["RTX 5090"],
        "gpu_num": 1,
        "cuda_v": 118,
        "cpu_num_from": 4,
        "cpu_num_to": 32,
        "memory_size_from": 16,
        "memory_size_to": 128,
        "cmd": "sleep infinity",
        "price_from": 100,
        "price_to": 9000,
        "image_uuid": "image-xxxxxxxx"
    }
}
```

## 3. List Deployments

### → Request

```
POST /api/v1/dev/deployment/list
```

Place the following parameters in the request body:

| Parameter         | Type   | Required | Description                                                                                                             |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `page_index`      | Int    | Yes      | Page number (starting from 1)                                                                                           |
| `page_size`       | Int    | Yes      | Number of items per page                                                                                                |
| `name`            | String | No       | Filter by exact deployment name (exact match only, no fuzzy search)                                                     |
| `status`          | String | No       | Filter by deployment status: `running` → active deployments `stopped` → stopped deployments → leave empty to return all |
| `deployment_uuid` | String | No       | Filter by specific deployment UUID                                                                                      |

```json Request Body theme={null}
{
  "page_index": 1,
  "page_size": 10,
  "name": "my-api",           // optional: filter by exact deployment name
  "status": "running",        // optional: "running" | "stopped" | empty (all)
  "deployment_uuid": "xxx"    // optional: filter by deployment UUID
}
```

### ← Response

The fields returned in each deployment object have the same meaning as the parameters used when creating the deployment.

```json Response (on success) theme={null}
{
  "code": "Success",
  "msg": "",
  "data": {
    "list": [
      {
        "id": 214,
        "uuid": "53a677bb3e281b8",
        "name": "xxxx",
        "deployment_type": "Container",
        "status": "stopped",
        "replica_num": 1,
        "parallelism_num": 1,
        "reuse_container": true,
        "starting_num": 0,
        "running_num": 0,
        "finished_num": 2,
        "image_uuid": "image-db8346e037",
        "template": {
          "dc_list": ["Singpore-A", "Singapore-B"],
          "gpu_name_set": ["RTX 5090"],
          "gpu_num": 1,
          "cpu_num_from": 1,
          "cpu_num_to": 100,
          "memory_size_from": 1073741824,
          "memory_size_to": 274877906944,
          "price_from": 100,
          "price_to": 9000,
          "cuda_v_from": 118,
          "cuda_v_to": 128,
          "cmd": "sleep 100"
        },
        "price_estimates": 0,
        "created_at": "2023-01-05T20:34:07+08:00",
        "updated_at": "2023-01-05T20:34:07+08:00",
        "stopped_at": null
      }
    ],
    "page_index": 1,
    "page_size": 10,
    "offset": 0,
    "max_page": 1,
    "result_total": 3
  }
}
```

## 4. Scale Replicas (ReplicaSet only)

### → Request

```
PUT /api/v1/dev/deployment/replica_num
```

Place the following parameters in the request body:

| Parameter         | Type   | Required | Description                                         |
| ----------------- | ------ | -------- | --------------------------------------------------- |
| `deployment_uuid` | String | Yes      | UUID of the deployment to scale replicas for        |
| `replica_num`     | Int    | Yes      | Desired number of replicas (must be greater than 0) |

```json Request Body theme={null}
{
  "deployment_uuid": "53a677bb3e281b8",
  "replica_num": 3
}
```

### ← Response

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `code`    | String | Response status. `Success` on success |
| `msg`     | String | Error message. Empty when successful  |
| `data`    | null   | No data returned                      |

```json Response (on success) theme={null}
{
  "code": "Success",
  "msg": "",
  "data": null
}
```

```python Python theme={null}
import requests

headers = {
    "Authorization": "your token",
    "Content-Type": "application/json"
}

url = "https://api.gpuhub.com/api/v1/dev/deployment/replica_num"

body = {
    "deployment_uuid": "5be3045703152b9",
    "replica_num": 16
}

response = requests.put(url, json=body, headers=headers)
print(response.json())
```

## 5. Stop Entire Deployment

### → Request

```
PUT /api/v1/dev/deployment/operate
```

Place the following parameters in the request body:

| Parameter         | Type   | Required | Description                                                                         |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `deployment_uuid` | String | Yes      | UUID of the deployment to operate                                                   |
| `operation`       | String | Yes      | Operation to perform: `stop` → stop the deployment `delete` → delete the deployment |

```json Request Body theme={null}
{
  "deployment_uuid": "53a677bb3e281b8",
  "operation": "stop"
}
```

### ← Response

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `code`    | String | Response status. `Success` on success |
| `msg`     | String | Error message. Empty when successful  |
| `data`    | null   | No data returned                      |

```json Response (on success) theme={null}
{
  "code": "Success",
  "msg": "",
  "data": null
}
```

```python Python theme={null}

import requests
headers = {
    "Authorization": "your token",
    "Content-Type": "application/json"
}
url = "https://api.gpuhub.com/api/v1/dev/deployment/operate"
body = {
    "deployment_uuid": "5be3045703152b9",
    "operate": "stop"
}
response = requests.put(url, json=body, headers=headers)
print(response.content.decode())
```

## 6. Delete Entire Deployment

### → Request

If the deployment is still running, the system will automatically stop it first, then delete it completely (including all containers and associated resources).

```
DELETE /api/v1/dev/deployment
```

```json Request Body theme={null}
JSON{
  "deployment_uuid": "xxx"
}
```

### ← Response

| Parameter | Type   | Description           |
| --------- | ------ | --------------------- |
| `code`    | String | `Success` on success  |
| `msg`     | String | Empty when successful |
| `data`    | null   | No data returned      |

```json Response (on success) theme={null}
JSON{
  "code": "Success",
  "msg": "",
  "data": null
}
```

```python Python theme={null}
import requests
headers = {
    "Authorization": "your_token_here",
    "Content-Type": "application/json"
}

url = "https://api.gpuhub.com/api/v1/dev/deployment"
body = {"deployment_uuid": "5be3045703152b9"}

response = requests.delete(url, json=body, headers=headers)
print(response.json())
```

## 7. List Container Events

### → Request

```
POST /api/v1/dev/deployment/container/event/list
```

Place the following parameters in the request body:

| Parameter                   | Type   | Required | Description                                   |
| --------------------------- | ------ | -------- | --------------------------------------------- |
| `deployment_uuid`           | String | Yes      | Deployment UUID                               |
| `deployment_container_uuid` | String | No       | Specific container UUID (leave empty for all) |
| `page_index`                | Int    | Yes      | Page number (starting from 1)                 |
| `page_size`                 | Int    | Yes      | Number of items per page                      |
| `offset`                    | Int    | No       | Starting offset (used for polling new events) |

```json Request Body theme={null}
{
  "deployment_uuid": "da497aea1eb8343", 
  "deployment_container_uuid": "", 
  "page_index": 1, 
  "page_size": 10,
  "offset": 0
}
```

### ← Response

Response Parameters

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `code`    | String | Response status. `Success` on success |
| `msg`     | String | Error message. Empty when successful  |
| `data`    | Object | Container event data                  |

Event Object Fields

| Parameter                   | Type   | Description                                                                            |
| --------------------------- | ------ | -------------------------------------------------------------------------------------- |
| `deployment_container_uuid` | String | UUID of the container                                                                  |
| `status`                    | String | Container state (e.g., `creating`, `starting`, `running`, `shutting_down`, `shutdown`) |
| `created_at`                | String | Timestamp when the state change occurred                                               |

```json Response (on success) theme={null}
{
    "code": "Success",
    "data": {
        "list": [
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "shutdown",
                "created_at": "2022-12-13T16:42:45+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "shutting_down",
                "created_at": "2022-12-13T16:42:40+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "running",
                "created_at": "2022-12-13T16:34:57+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "oss_merged",
                "created_at": "2022-12-13T16:34:55+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "starting",
                "created_at": "2022-12-13T16:34:55+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "created",
                "created_at": "2022-12-13T16:34:54+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "creating",
                "created_at": "2022-12-13T16:34:47+08:00"
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "offset": 0,
        "max_page": 1,
    },
    "msg": ""
}
```

```python Python theme={null}
import requests
headers = {
    "Authorization": "your_token_here",
    "Content-Type": "application/json"
}

url = "https://api.gpuhub.com/api/v1/dev/deployment/container/event/list"
body = {
    "deployment_uuid": "da497aea1eb8343", 
    "deployment_container_uuid": "", 
    "page_index": 1, 
    "page_size": 10,
    "offset": 0
}

response = requests.post(url, json=body, headers=headers)
print(response.json())
```

## 8. List Containers

### → Request

Inside the container, you can get the current container's UUID via the environment variable: `AutoDLContainerUUID`

```
POST /api/v1/dev/deployment/container/list
```

Request Body Parameters

| Parameter               | Type           | Required | Description                             |
| ----------------------- | -------------- | -------- | --------------------------------------- |
| `deployment_uuid`       | String         | Yes      | Deployment UUID                         |
| `container_uuid`        | String         | No       | Filter by specific container UUID       |
| `date_from` / `date_to` | String         | No       | Filter by container creation time range |
| `gpu_name`              | String         | No       | Filter by GPU model                     |
| `cpu_num_from/to`       | Int            | No       | CPU core range                          |
| `memory_size_from/to`   | Int            | No       | Memory range (bytes)                    |
| `price_from/to`         | Float          | No       | Base price range (USD × 1000)           |
| `released`              | Boolean        | No       | Include released containers?            |
| `status`                | `List<String>` | No       | Filter by status: e.g., `["running"]`   |
| `page_index`            | Int            | Yes      | Page number (default: 1)                |
| `page_size`             | Int            | Yes      | Items per page (default: 10)            |
| `offset`                | Int            | No       | Starting offset                         |

```json Request Body theme={null}
{
    "deployment_uuid": "da497aea1eb8343", 
    "page_index": 1, 
    "page_size": 10
}
```

### ← Response

Response Fields

| Parameter   | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| `code`      | String | Response status. `Success` on success |
| `msg`       | String | Error message. Empty when successful  |
| `data.list` | Array  | List of container objects             |

Container Object

| Field             | Type   | Description                                                               |
| ----------------- | ------ | ------------------------------------------------------------------------- |
| `uuid`            | String | Container UUID                                                            |
| `version`         | String | Container version (auto-generated or user-specified on deployment update) |
| `data_center`     | String | Region / data center code (e.g., `Singpore-A`)                            |
| `deployment_uuid` | String | Parent deployment UUID                                                    |
| `machine_id`      | String | Physical host ID                                                          |
| `status`          | String | Current status (`running`, `stopped`, `starting`, etc.)                   |
| `gpu_name`        | String | GPU model (e.g., `RTX 5090`)                                              |
| `gpu_num`         | Int    | Number of GPUs allocated                                                  |
| `cpu_num`         | Int    | Number of CPU cores                                                       |
| `memory_size`     | Int    | Memory size in **bytes**                                                  |
| `image_uuid`      | String | Image UUID                                                                |
| `price`           | Float  | Base price in **USD × 1000** (e.g., 1600 = \$1.60/hr)                     |
| `info`            | Object | Connection details (see below)                                            |
| `started_at`      | String | Time when container started running                                       |
| `stopped_at`      | String | Time when container stopped (null if running)                             |
| `created_at`      | String | Creation timestamp                                                        |
| `updated_at`      | String | Last update timestamp                                                     |

`info` Object (Connection Details)

| Field                                      | Type   | Description                                     |
| ------------------------------------------ | ------ | ----------------------------------------------- |
| `ssh_command`                              | String | Full SSH login command                          |
| `root_password`                            | String | Root password for SSH                           |
| `service_6006_port_url`                    | String | Public HTTPS URL for port 6006                  |
| `service_6008_port_url`                    | String | Public HTTP URL for port 6008                   |
| `service_url`, `proxy_host`, `custom_port` | —      | **Deprecated** — use the two service URLs above |

```json Response (on success) theme={null}
{
  "code": "Success",
  "msg": "",
  "data": {
    "list": [
      {
        "uuid": "53a677bb3e281b8-f94411a60c-63c24009",
        "data_center": "Singpore-A",
        "deployment_uuid": "da497aea1eb8343",
        "status": "running",
        "gpu_name": "RTX 5090",
        "gpu_num": 1,
        "cpu_num": 16,
        "memory_size": 68719476736,
        "image_uuid": "image-xxxxxxxx",
        "price": 1600,
        "info": {
          "ssh_command": "ssh -p 22345 root@singpore-a.gpuhub.com",
          "root_password": "xxxxxxxxxx",
          "service_6006_port_url": "https://singpore-a.gpuhub.com:22346",
          "service_6008_port_url": "http://singpore-a.gpuhub.com:22348"
        },
        "started_at": "2025-11-19T10:43:03+08:00",
        "created_at": "2025-11-19T10:42:50+08:00"
      }
    ],
    "page_index": 1,
    "page_size": 10,
    "max_page": 1
  }
}
```

```python Python theme={null}
import requests

headers = {
    "Authorization": "your_token_here",
    "Content-Type": "application/json"
}

url = "https://api.gpuhub.com/api/v1/dev/deployment/container/list"

body = {
    "deployment_uuid": "da497aea1eb8343",
    "status": ["running"],
    "page_index": 1,
    "page_size": 10
}

response = requests.post(url, json=body, headers=headers)
print(response.json())

```

## 9. Stop a Container

### → Request

```
PUT /api/v1/dev/deployment/container/stop
```

Place the following parameters in the request body:

| Parameter                   | Type    | Required | Description                                                                                                                                                               |
| --------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deployment_container_uuid` | String  | Yes      | UUID of the container to stop                                                                                                                                             |
| `decrease_one_replica_num`  | Boolean | No       | **ReplicaSet only**: if `true`, decreases the desired replica count by 1 after stopping (default: `false`)                                                                |
| `no_cache`                  | Boolean | No       | If `true`, prevents the stopped container from being cached for reuse (default: `false`)                                                                                  |
| `cmd_before_shutdown`       | String  | No       | Command to run before shutdown (5-second timeout; force-kills on timeout). Overrides any `cmd_before_shutdown` set during deployment creation (very rare chance both run) |

```json Request Body theme={null}
{
     "deployment_container_uuid": "da497aea1eb8343-f94411a60c-a394fb30",
     "decrease_one_replica_num": false,
     "no_cache": false,
     "cmd_before_shutdown": "sleep 5"
}

```

### ← Response

Response Parameters

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `code`    | String | Response status. `Success` on success |
| `msg`     | String | Error message. Empty when successful  |
| `data`    | null   | No data returned                      |

```json Response (on success) theme={null}
{
    "code": "Success",
    "msg": "",
    "data": null
}
```

```python Python theme={null}
import requests
headers = {
    "Authorization": "your token",
    "Content-Type": "application/json"
}

url = "https://api.gpuhub.com/api/v1/dev/deployment/container/event/stop"
body = {
    "deployment_container_uuid": "da497aea1eb8343-f94411a60c-a394fb30",
    "decrease_one_replica_num": false,
    "no_cache": false,
    "cmd_before_shutdown": "sleep 5"
}

response = requests.put(url, json=body, headers=headers)
print(response.content.decode())
```

## 10. Host Blacklist

### → Request

To avoid bad machines: if a container experiences unknown issues (e.g., slow startup, crashes), you can blacklist its host to prevent future scheduling on that machine.

```
POST /api/v1/dev/deployment/blacklist
```

| Parameter                   | Type   | Required | Description                                                                           |
| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `deployment_container_uuid` | String | Yes      | UUID of the problematic container                                                     |
| `expire_in_minutes`         | Int    | No       | Blacklist duration in minutes. Default: **1440** (24 hours). Max: **43200** (30 days) |
| `comment`                   | String | No       | Optional note (e.g., "Slow boot")                                                     |

```json Request Body theme={null}
{
  "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
  "expire_in_minutes": 1440,
  "comment": "Slow startup — avoid this host"
}
```

### ← Response

Response Parameters

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `code`    | String | Response status. `Success` on success |
| `msg`     | String | Error message. Empty when successful  |
| `data`    | null   | No data returned                      |

```json Response (on success) theme={null}
{
    "code": "Success",
    "msg": "",
    "data": null
}
```

```python Python theme={null}
import requests

headers = {"Authorization": "your token", "Content-Type": "application/json"}
url = "https://api.gpuhub.com/api/v1/dev/deployment/blacklist"

body = {
    "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
    "expire_in_minutes": 1440,
    "comment": "Slow startup — avoid this host"
}

response = requests.post(url, json=body, headers=headers)
print(response.json())

```

## 11. Get Active Blacklist

### → Request

```
GET /api/v1/dev/deployment/blacklist
```

No body required.

### ← Response

Response Parameters

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `code`    | String | Response status. `Success` on success |
| `msg`     | String | Error message. Empty when successful  |
| `data`    | List   | List of active blacklist entries      |

Blacklist Entry Object

| Field          | Type   | Description                                                         |
| -------------- | ------ | ------------------------------------------------------------------- |
| `created_at`   | String | Timestamp when the blacklist was first created                      |
| `updated_at`   | String | Timestamp of the last update (updates when expiry time is extended) |
| `data_center`  | String | Region / data center code (e.g., `Singpore-A`)                      |
| `expired_time` | String | Timestamp when the blacklist entry will automatically expire        |
| `machine_id`   | String | Physical host ID that is blacklisted                                |
| `msg`          | String | Optional comment provided when creating the blacklist               |

```json Success Response theme={null}
{
  "code": "Success",
  "msg": "",
  "data": [
    {
      "created_at": "2025-03-25T17:42:55+08:00",
      "updated_at": "2025-03-25T17:48:11+08:00",
      "data_center": "Singpore-A",
      "machine_id": "24fb4ca36a",
      "expired_time": "2025-03-26T17:48:11+08:00",
      "msg": "Slow startup — avoid this host"
    }
  ]
}
```

```python Python theme={null}
import requests

headers = {"Authorization": "your token"}
url = "https://api.gpuhub.com/api/v1/dev/deployment/blacklist"

response = requests.get(url, headers=headers)
print(response.json())
```

## 12. Real-time GPU Stock by Region

### → Request

```
POST /api/v1/dev/machine/region/gpu_stock

```

Use this endpoint before creating deployments to check real-time availability and avoid scheduling failures. Stock is calculated assuming 1 GPU per container. Even if a host has 2 idle GPUs, they may be on different machines — a container requiring 2 GPUs might still fail to schedule.

Request Body Parameters

| Parameter          | Type           | Required | Description                                              |
| ------------------ | -------------- | -------- | -------------------------------------------------------- |
| `region_sign`      | String         | Yes      | Region code (see Appendix)                               |
| `cuda_v_from`      | Int            | No       | Minimum supported CUDA version (e.g., `118` = CUDA 11.8) |
| `cuda_v_to`        | Int            | No       | Maximum supported CUDA version                           |
| `gpu_name_set`     | `List<String>` | No       | Filter by specific GPU models                            |
| `memory_size_from` | Int            | No       | Minimum memory size in GB                                |
| `memory_size_to`   | Int            | No       | Maximum memory size in GB                                |
| `cpu_num_from`     | Int            | No       | Minimum CPU cores                                        |
| `cpu_num_to`       | Int            | No       | Maximum CPU cores                                        |
| `price_from`       | Int            | No       | Minimum price (USD \* 1000, e.g., \$0.10/hr → `100`)     |
| `price_to`         | Int            | No       | Maximum price (USD \* 1000)                              |

```json Request Body theme={null}
{
  "region_sign": "Singpore-A",
  "cuda_v_from": 118,
  "cuda_v_to": 128
}

```

### ← Response

Response Parameters

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `code`    | String | Response status. `Success` on success |
| `msg`     | String | Error message. Empty when successful  |
| `data`    | List   | List of GPU inventory objects         |

GPU Inventory Object

| Field           | Type   | Description                   |
| --------------- | ------ | ----------------------------- |
| `{GPU_MODEL}`   | Object | Key is the GPU model name     |
| `idle_gpu_num`  | Int    | Number of currently idle GPUs |
| `total_gpu_num` | Int    | Total number of GPUs          |

```json Response (on success) theme={null}
{
  "code": "Success",
  "msg": "",
  "data": [
    {
      "RTX 5090": {
        "idle_gpu_num": 312,
        "total_gpu_num": 2850
      }
    },
    {
      "RTX Pro 6000": {
        "idle_gpu_num": 48,
        "total_gpu_num": 640
      }
    }
  ]
}
```

```python Python theme={null}
import requests

headers = {
    "Authorization": "your_token_here",
    "Content-Type": "application/json"
}

url = "https://api.gpuhub.com/api/v1/dev/machine/region/gpu_stock"

body = {
    "region_sign": "Singpore-A",
    "cuda_v_from": 118,
    "cuda_v_to": 138
}

response = requests.post(url, json=body, headers=headers)
print(response.json())
```

## 13. Check Duration Package Balance

### → Request

```
GET /api/v1/dev/deployment/ddp/overview
```

Request Parameters (Query String)

| Parameter         | Type   | Required | Description            |
| ----------------- | ------ | -------- | ---------------------- |
| `deployment_uuid` | String | Yes      | UUID of the deployment |

### ← Response

Response Parameters

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `code`    | String | Response status. `Success` on success |
| `msg`     | String | Error message. Empty when successful  |
| `data`    | List   | List of prepaid package objects       |

Prepaid Package Object

| Field      | Type   | Description                                                                                  |
| ---------- | ------ | -------------------------------------------------------------------------------------------- |
| `gpu_type` | String | GPU model (e.g., `RTX 5090`)                                                                 |
| `total`    | Int    | Total remaining seconds across all **unused** prepaid packages (seconds)                     |
| `balance`  | Int    | Currently remaining seconds from **unused** packages (seconds)                               |
| `dc_list`  | String | Regions covered by the package (comma-separated if multiple, e.g., `singpore-a,singapore-b`) |

### ← Response

```json Response (on success) theme={null}
{
    "code": "Success",
    "data": [
        {
            "gpu_type": "RTX 5090",
            "total": 86400,
            "balance": 83829,
            "dc_list": "Singpore-A,Singapore-B"
        }
    ],
    "msg": ""
}
```

```python Python theme={null}
import requests

headers = {"Authorization": "your_token_here"}
url = "https://api.gpuhub.com/api/v1/dev/deployment/ddp/overview"
params = {"deployment_uuid": "your_deployment_uuid_here"}

response = requests.get(url, params=params, headers=headers)
print(response.json())

```

## 14. Appendix

### region\_sign & dc\_list

Values for dc\_list (preferred) or the deprecated region\_sign parameter when creating a deployment, After a container starts, the current region is also available inside the container via the environment variable.

| Region Name | `dc_list` Value | Old `region_sign` |
| ----------- | --------------- | ----------------- |
| Singapore-B | `Singpore-A`    | `Singpore-A`      |
| Singapore-A | `Singapore-B`   | `Singapore-B`     |

### Public Image UUID

| Framework  | Framework Version | Image UUID              | Description                      |
| ---------- | ----------------- | ----------------------- | -------------------------------- |
| PyTorch    | 2.8.0 (Blackwell) | `base-image-ec1e9vdbd3` | CUDA 12.8 · Ubuntu 22.04         |
| PyTorch    | 2.7.0             | `base-image-d13e3vu5d3` | CUDA 12.8 · Ubuntu 22.04         |
| PyTorch    | 2.5.1             | `base-image-b2343du52k` | CUDA 12.4 · Ubuntu 22.04         |
| PyTorch    | 2.5.1             | `base-image-c1333ve5d3` | CUDA 8.1.rc1 · Ubuntu 22.04      |
| PyTorch    | 2.3.0             | `base-image-321232d5d4` | CUDA 12.1 · Ubuntu 22.04         |
| PyTorch    | 2.1.2             | `base-image-lbdbb183fk` | CUDA 11.8 · Ubuntu 22.04         |
| PyTorch    | 2.1.0             | `base-image-323d32u534` | CUDA 12.1 · Ubuntu 22.04         |
| PyTorch    | 2.1.0             | `base-image-pi743du52k` | CUDA 8.0 · Ubuntu 22.04          |
| PyTorch    | 2.0.0             | `base-image-l2t43iu6uk` | CUDA 11.8 · Ubuntu 20.04         |
| PyTorch    | 1.11.0            | `base-image-l374uiucui` | CUDA 11.3 · Ubuntu 20.04         |
| PyTorch    | 1.10.0            | `base-image-tbk3g58lhs` | CUDA 11.3 · Ubuntu 20.04         |
| PyTorch    | 1.9.0             | `base-image-12be412037` | CUDA 11.1 · Ubuntu 18.04         |
| PyTorch    | 1.8.1             | `base-image-db83412037` | CUDA 11.1 · Ubuntu 18.04         |
| PyTorch    | 1.7.0             | `base-image-db8346e037` | CUDA 11 · Ubuntu 18.04           |
| PyTorch    | 1.6.0             | `base-image-ldnbxc4by8` | CUDA 10.1 · Ubuntu 18.04         |
| PyTorch    | 1.5.1             | `base-image-qyil80d3s4` | CUDA 10.1 · Ubuntu 18.04         |
| PyTorch    | 1.1.0             | `base-image-0x7zgbw1ji` | CUDA 10 · Ubuntu 18.04           |
| TensorFlow | 2.9.0             | `base-image-uxeklgirir` | CUDA 11.2 · Ubuntu 20.04         |
| TensorFlow | 2.5.0             | `base-image-0gxqmciyth` | CUDA 11.2 · Ubuntu 18.04         |
| TensorFlow | 1.15.5            | `base-image-4bpg0tt88l` | CUDA 11.4 · Ubuntu 20.04         |
| Miniconda  | —                 | `base-image-8hkyyugih5` | CUDA 11.8 · Ubuntu 22.04         |
| Miniconda  | —                 | `base-image-m26c71lgul` | CUDA 11.8 · Ubuntu 20.04         |
| Miniconda  | —                 | `base-image-mbr2n4urrc` | CUDA 11.6 · Ubuntu 20.04         |
| Miniconda  | —                 | `base-image-zsd8dwuwus` | CUDA 11.3(cudagl) · Ubuntu 20.04 |
| Miniconda  | —                 | `base-image-7bn8iqhkb5` | CUDA 11.3 · Ubuntu 18.04         |
| Miniconda  | —                 | `base-image-h041hn36yt` | CUDA 11.1 · Ubuntu 18.04         |
| Miniconda  | —                 | `base-image-hek323ev8b` | CUDA 10.1 · Ubuntu 18.04         |
| Miniconda  | —                 | `base-image-qkkhitpik5` | CUDA 10.2 · Ubuntu 18.04         |
| Miniconda  | —                 | `base-image-1e5uf433g1` | CUDA 10 · Ubuntu 18.04           |
| Miniconda  | —                 | `base-image-k0vep6kyq8` | CUDA 9 · Ubuntu 16.04            |
| Miniconda  | —                 | `base-image-b23jugu52k` | CUDA 8.0 · Ubuntu 22.04          |
| TensorRT   | 8.6.1             | `base-image-l2193iu12k` | CUDA 11.8 · Ubuntu 20.04         |
| TensorRT   | 8.5.1             | `base-image-l2843iu23k` | CUDA 11.8 · Ubuntu 20.04         |

More images are added regularly: contact support for the latest list or request a custom base image.

### CUDA Version values

| CUDA Version | Value to use in `cuda_v_from` / `cuda_v_to` |
| ------------ | ------------------------------------------- |
| 11.8         | `118`                                       |
| 12.0         | `120`                                       |
| 12.1         | `121`                                       |
| 12.2         | `122`                                       |

If your framework needs CUDA 11.5 (or any unlisted version), choose the lowest available version ≥ your requirement (e.g., 11.8 → `118`).

Higher drivers are backward-compatible, but picking a version that's too high reduces available GPUs.

Always select the smallest compatible value to maximize scheduling success.

### Container Environment Variables

| Variable Name        | ODescription                       |
| -------------------- | ---------------------------------- |
| AutoDLContainerUUID  | Unique ID of the current container |
| AutoDLDeploymentUUID | UUID of the parent deployment      |
| AutoDLDataCenter     | Current region / data center code  |