GPU Servers API

List GPU servers

GET /api/v1/gpu-servers

const { data: servers } = await puchify.gpuServers.list({ status: "running" })

servers = puchify.gpu_servers.list(status="running")

servers, err := client.GPUServers.List(ctx, &puchify.GPUServerListParams{
  Status: puchify.String("running"),
})

puchify gpu list --status running

curl https://api.puchify.com/api/v1/gpu-servers \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Query parameters:

Parameter	Type	Description
`cursor`	string	Pagination cursor
`limit`	integer (1-100)	Results per page (default 50)
`status`	string	Filter by status (`creating`, `running`, `stopped`, `destroyed`)
`gpu_type`	string	Filter by GPU type (`a100`, `h100`, `l40s`, `a10`)
`sort`	`name` \| `created_at`	Sort field
`order`	`asc` \| `desc`	Sort direction

Create a GPU server

POST /api/v1/gpu-servers

const { data: server } = await puchify.gpuServers.create({
  name: "ml-train-01",
  plan: "gpu-h100-1",
  region: "us-east",
  gpu_type: "h100",
  image: "ubuntu-24.04-cuda",
})

server = puchify.gpu_servers.create(
  name="ml-train-01",
  plan="gpu-h100-1",
  region="us-east",
  gpu_type="h100",
  image="ubuntu-24.04-cuda",
)

server, err := client.GPUServers.Create(ctx, &puchify.CreateGPUServerInput{
  Name: "ml-train-01", Plan: "gpu-h100-1", Region: "us-east",
  GPUType: puchify.String("h100"), Image: puchify.String("ubuntu-24.04-cuda"),
})

puchify gpu create --name ml-train-01 --plan gpu-h100-1 --region us-east --gpu-type h100

curl -X POST https://api.puchify.com/api/v1/gpu-servers \
  -H "Authorization: Bearer $PUCHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"ml-train-01","plan":"gpu-h100-1","region":"us-east","gpu_type":"h100","image":"ubuntu-24.04-cuda"}'

Request body:

Field	Type	Required	Description
`name`	string	yes	GPU server name (2-40 chars, lowercase alphanumeric + dashes)
`plan`	string	yes	GPU plan ID (determines GPU count and vCPU/RAM)
`region`	string	yes	Region ID
`gpu_type`	string	no	GPU type (`a100`, `h100`, `l40s`, `a10`; inferred from plan if omitted)
`image`	string	no	OS image (default: `ubuntu-24.04-cuda`)
`ssh_keys`	string[]	no	SSH key IDs to inject

Get a GPU server

GET /api/v1/gpu-servers/{id}

const { data: server } = await puchify.gpuServers.get("gpu_abc123")

server = puchify.gpu_servers.get("gpu_abc123")

server, err := client.GPUServers.Get(ctx, "gpu_abc123")

puchify gpu get gpu_abc123

curl https://api.puchify.com/api/v1/gpu-servers/gpu_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Update a GPU server

PATCH /api/v1/gpu-servers/{id}

const { data: server } = await puchify.gpuServers.update("gpu_abc123", {
  plan: "gpu-h100-4",
})

server = puchify.gpu_servers.update("gpu_abc123", plan="gpu-h100-4")

server, err := client.GPUServers.Update(ctx, "gpu_abc123", &puchify.UpdateGPUServerInput{
  Plan: puchify.String("gpu-h100-4"),
})

puchify gpu update gpu_abc123 --plan gpu-h100-4

curl -X PATCH https://api.puchify.com/api/v1/gpu-servers/gpu_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"gpu-h100-4"}'

Request body:

Field	Type	Required	Description
`plan`	string	no	New GPU plan ID (triggers resize)

Delete a GPU server

DELETE /api/v1/gpu-servers/{id}

await puchify.gpuServers.delete("gpu_abc123")

puchify.gpu_servers.delete("gpu_abc123")

err := client.GPUServers.Delete(ctx, "gpu_abc123")

puchify gpu delete gpu_abc123

curl -X DELETE https://api.puchify.com/api/v1/gpu-servers/gpu_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Restart a GPU server

POST /api/v1/gpu-servers/{id}/restart

const { data: server } = await puchify.gpuServers.restart("gpu_abc123")

server = puchify.gpu_servers.restart("gpu_abc123")

server, err := client.GPUServers.Restart(ctx, "gpu_abc123")

puchify gpu restart gpu_abc123

curl -X POST https://api.puchify.com/api/v1/gpu-servers/gpu_abc123/restart \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Destroy a GPU server

POST /api/v1/gpu-servers/{id}/destroy

await puchify.gpuServers.destroy("gpu_abc123")

puchify.gpu_servers.destroy("gpu_abc123")

err := client.GPUServers.Destroy(ctx, "gpu_abc123")

puchify gpu destroy gpu_abc123

curl -X POST https://api.puchify.com/api/v1/gpu-servers/gpu_abc123/destroy \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Permanently destroys the GPU server and releases all GPU resources. This action cannot be undone.

Polling for readiness

const server = await puchify.gpuServers.waitFor("gpu_abc123", "running", {
  timeout: 600_000,    // 10 minutes (GPU provisioning can be slow)
  pollInterval: 10_000,
})

server = puchify.gpu_servers.wait_for("gpu_abc123", "running", timeout=600)

server, err := puchify.WaitFor(ctx, client.GPUServers.Get, "gpu_abc123", "running",
  puchify.WithTimeout(10*time.Minute),
)

Response shape

{
  "data": {
    "id": "gpu_abc123",
    "name": "ml-train-01",
    "status": "running",       // creating | running | stopped | destroyed
    "plan": "gpu-h100-1",
    "gpu_type": "h100",
    "gpu_count": 1,
    "region": "us-east",
    "image": "ubuntu-24.04-cuda",
    "ipv4": "203.0.113.42",
    "ipv6": null,
    "gpu_utilization": null,
    "memory_utilization": null,
    "created_at": "2026-05-28T10:30:00Z",
    "updated_at": "2026-05-28T10:32:00Z"
  },
  "meta": {
    "persistence": "synced",
    "provider": "connected"
  }
}

Error codes

Code	Description
`402`	Insufficient GPU quota — upgrade your plan or reduce GPU count
`404`	GPU server not found
`409`	Conflict — server is in a transient state
`422`	Invalid GPU type/plan/region combination

GPU Servers API

On this page