Deployments

The Deployments API provides full lifecycle management for GPU instances powered by bare-metal NVIDIA GPUs.

Base URL: https://gpu.huddleapis.com/api/v1

Quick Start

# 1. Check your balance (minimum $20 required)
curl -H "X-API-Key: mk_your_key" \
  https://gpu.huddleapis.com/api/v1/billing/balance

# 2. List available GPU types
curl -H "X-API-Key: mk_your_key" \
  https://gpu.huddleapis.com/api/v1/gpus/available

# 3. List compatible OS images
curl -H "X-API-Key: mk_your_key" \
  https://gpu.huddleapis.com/api/v1/images

# 4. Deploy a GPU instance
curl -X POST -H "X-API-Key: mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cluster_type": "1A100.22V",
    "image": "e79a91e9-8750-44cb-af19-bf6ab83121ee",
    "hostname": "my-gpu-instance",
    "ssh_key_ids": ["your-ssh-key-id"],
    "location": "FIN-01"
  }' \
  https://gpu.huddleapis.com/api/v1/deployments/clusters

# 5. Check deployment status
curl -H "X-API-Key: mk_your_key" \
  https://gpu.huddleapis.com/api/v1/deployments/{deployment_id}

Deploy Request

Field	Type	Required	Description
`cluster_type`	string	Yes	GPU instance type (e.g. `1A100.22V`, `8H200.141S.176V`)
`image`	string	Yes	OS image ID from `/images` endpoint
`hostname`	string	Yes	Instance hostname (1-255 characters)
`ssh_key_ids`	string[]	Yes	At least one SSH key ID for access
`location`	string	Yes	Data center location code (e.g. `FIN-01`, `FIN-03`)
`description`	string	No	Optional description for the instance
`os_volume`	object	No	Custom boot disk configuration
`volumes`	object[]	No	Additional NVMe storage volumes

OS Volume (Boot Disk)

{
  "os_volume": {
    "name": "boot",
    "size": 100
  }
}

Default boot disk is 50 GB. You can configure up to 512 GB.

Additional Volumes

{
  "volumes": [
    {
      "name": "data",
      "size": 500,
      "type": "NVMe"
    }
  ]
}

Deploy Response

{
  "code": "OK",
  "data": {
    "id": "dep_abc123",
    "provider_id": "verda-id",
    "hostname": "my-gpu-instance",
    "cluster_type": "1A100.22V",
    "image": "e79a91e9-...",
    "os_name": "Ubuntu 24.04",
    "location": "FIN-01",
    "status": "ordered",
    "ssh_user": "ubuntu",
    "ssh_key_ids": ["key-id"],
    "specs": {
      "gpu_model": "A100",
      "gpu_count": 1,
      "gpu_vram_gb": 80,
      "total_vram_gb": 80,
      "vcpu_count": 22,
      "ram_gb": 120,
      "price_per_hr": 0.965
    },
    "volumes": [],
    "created_at": "2026-04-03T10:00:00Z",
    "updated_at": "2026-04-03T10:00:00Z"
  }
}

Deployment Lifecycle

A deployment progresses through the following states:

ordered → provisioning → running → offline → deleted
                                 → error
                       → failed_no_capacity
                                          → deleting → deleted

Status	Description	What you can do
`ordered`	Deployment request accepted, queued for provisioning	Wait for provisioning
`provisioning`	Hardware is being allocated and configured	Wait — typically 2-5 minutes
`running`	Instance is online and accessible via SSH	SSH in, run workloads, stop/delete
`offline`	Instance is stopped but can be restarted	Start or delete
`error`	Instance encountered an error	Delete and redeploy
`deleting`	Instance is being torn down	Wait for deletion to complete
`deleted`	Instance has been permanently removed	—
`failed_no_capacity`	No GPU capacity available for this type	Try a different location or type

Actions

You can perform lifecycle actions on running deployments:

# Delete a deployment
curl -X POST -H "X-API-Key: mk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "delete"}' \
  https://gpu.huddleapis.com/api/v1/deployments/{id}/actions

# Or use the DELETE endpoint directly
curl -X DELETE -H "X-API-Key: mk_your_key" \
  https://gpu.huddleapis.com/api/v1/deployments/{id}

SSH Access

Once a deployment reaches running status, you can SSH into it:

ssh ubuntu@{deployment_ip}

The SSH user is always ubuntu. The IP address is available in the deployment response once the instance is running.

Billing

Important

GPU credits are separate from platform credits. You must have at least $20 in GPU credits before deploying.

Rule	Detail
Minimum balance	$20 in GPU credits to deploy
Minimum charge	10 minutes per deployment
After 10 minutes	Billed per second
Billing interval	Deducted every 10 minutes while running

Even if you delete an instance within seconds, you are billed for the full 10-minute minimum. After 10 minutes, billing is exact to the second.

See GPU Billing for the full billing reference.

Check Availability

Before deploying, you can check if a specific instance type has capacity:

curl -H "X-API-Key: mk_your_key" \
  https://gpu.huddleapis.com/api/v1/deployments/availability/1A100.22V

{
  "code": "OK",
  "data": {
    "cluster_type": "1A100.22V",
    "is_available": true
  }
}

If is_available is false, try a different location or instance type.

Error Handling

HTTP Status	Code	Meaning
400	`BAD_REQUEST`	Invalid request body or missing required fields
401	`UNAUTHORIZED`	Invalid or missing API key
402	`INSUFFICIENT_CREDITS`	Balance below $20 minimum
404	`NOT_FOUND`	Deployment not found
409	`CONFLICT`	Instance type unavailable (no capacity)
500	`INTERNAL`	Server error — retry with an idempotency key

Idempotency

For safe retries on deploy and delete operations, pass an Idempotency-Key header:

curl -X POST -H "X-API-Key: mk_your_key" \
  -H "Idempotency-Key: unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  https://gpu.huddleapis.com/api/v1/deployments/clusters

Duplicate requests with the same idempotency key return the cached result instead of creating a new deployment.

Deployments

On this page