Deployments - DeployGPU

Create Deployment

Only VM providers (quantacloud, masscompute, verda, hyperstack) are supported via the API. Container providers (Vast.ai) require the dashboard, and so do templates and app links.

POST /api/v1/deployments

Starts provisioning a new GPU instance. Returns immediately with status provisioning. Poll the get endpoint to track progress.

Request Body

{
  "provider": "verda",
  "offer_id": "c0858d33-a3de-4fbd-8fee-98d009c3ec7d",
  "os_image_id": "ubuntu-22.04-cuda-12.4-docker",
  "disk_gb": 100,
  "ssh_key_ids": ["86a3a040-f052-4557-9dc5-4388661a8cfb"],
  "volume_ids": ["e6a12cc1-5d22-48c6-bda3-01fce11c9d19"]
}

Field	Type	Required	Description
`provider`	string	Yes	Provider name: `quantacloud`, `masscompute`, `verda` or `hyperstack`. Use the value from List Providers, not the `provider.slug` on an offer. They usually match, but Massed Compute’s offers report the slug `massed-compute` while the provider name here is `masscompute`.
`offer_id`	string	Yes	Offer UUID from the offers endpoint
`os_image_id`	string	No	OS image ID from the provider images endpoint. If omitted, uses the image that endpoint marks `isDefault` for the offer
`disk_gb`	int	No	Disk size in GB, between the offer’s `storageMinGB` and `storageMaxGB`. Default: 0 (provider default)
`ssh_key_ids`	string[]	No	SSH key UUIDs to inject, from List SSH Keys. Each must be one of your keys. If omitted or empty, all your keys are injected
`volume_ids`	string[]	No	Volume UUIDs to attach. Volumes must be in the same region as the offer

Response `202 Accepted`

{
  "id": "a6305686-fe03-494c-b254-9ee0a2453068",
  "status": "provisioning"
}

There is no idempotency key on this endpoint. If a request times out or the connection drops before you see a response, do not send it again immediately. List your deployments and look for one that already matches what you tried, because a second call after a timeout can create and bill a second GPU instead of returning the first one.

Errors

Code	When
`provider_not_supported`	Container providers (Vast.ai) are not supported via the API
`offer_provider_mismatch`	The offer belongs to a different provider than the `provider` in the request
`validation_error`	Invalid offer, provider, or parameters
`image_incompatible`	The OS image cannot boot on this GPU type (for example, an R535 driver image on a Blackwell B200). The message names the minimum driver
`image_not_offered`	The OS image is not in the provider catalog for this offer. The message lists the images that are
`offer_unavailable`	The offer is out of stock or was withdrawn since you fetched it
`offer_cooling_down`	A recent attempt hit provider capacity for this exact offer and location. Returned as `503 Service Unavailable` with `Retry-After` and `error.retry_after` in seconds. Choose another location or wait
`provider_maintenance`	The provider is in maintenance and new deployments on it are paused. Returned as `503 Service Unavailable` with `Retry-After`, plus `error.retry_after` (seconds), `error.provider` and, when an end is known, `error.ends_at`. Running deployments are not affected. Choose another provider, or retry after the window. See provider maintenance
`invalid_ssh_key`	An SSH key ID is malformed or not one of your keys. For example, a deleted key, or a key ID from another account
`invalid_volume`	A volume ID is malformed, duplicated, or not owned by you
`volume_unavailable`	A volume is not currently available to attach
`volume_provider_mismatch`	A volume belongs to a different provider than the offer
`volume_location_mismatch`	Volumes span locations, or the offer cannot run where the volume lives
`insufficient_balance`	Balance does not cover at least 1 hour at the offer’s rate

These are all returned before anything is created or charged. Failures that happen after the request is accepted are reported on the deployment itself. See Failure Fields.

List Deployments

GET /api/v1/deployments

Returns your deployments, newest first.

Query Parameters

Param	Type	Default	Description
`page`	int	0	Page number (0-indexed)
`size`	int	25	Page size (max 100)

Response

{
  "data": [
    {
      "id": "a6305686-fe03-494c-b254-9ee0a2453068",
      "status": "active",
      "provider": "verda",
      "region": "FIN-01",
      "gpu": {
        "type": "NVIDIA A100 SXM4 80GB",
        "count": 1
      },
      "hourly_rate": "1.4500",
      "accumulated_cost": "1.4500",
      "connection": {
        "public_ip": "135.181.63.213",
        "ssh_port": 22,
        "ssh_user": "root",
        "jupyter_url": null,
        "tunnel_id": null,
        "endpoint_url": null
      },
      "stop_reason": null,
      "failure_reason": null,
      "failure_code": null,
      "retryable": null,
      "suggested_action": null,
      "billing_iterations": 0,
      "created_at": "2026-05-10T20:12:51.596837Z",
      "activated_at": "2026-05-10T20:14:35.432129Z",
      "updated_at": "2026-05-10T20:15:03.908535Z"
    }
  ],
  "page": 0,
  "size": 25,
  "total_elements": 12
}

Get Deployment

GET /api/v1/deployments/{id}

Returns a single deployment by ID. Same shape as items in the list response.

Deployment Status

Status	Description
`provisioning`	Instance is being created at the provider (typically 1 to 3 minutes)
`connecting`	Instance created. For a template deployment, the platform is waiting for the application inside the container to answer its health check. Nothing here waits on SSH
`active`	Allocated and billed. A Verda or Hyperstack VM can be powered off while its deployment remains active; use Get Power State to check
`stopping`	Permanent teardown in progress
`interrupted`	Provider terminated the instance (preemption or a failed health check)
`terminated`	Permanently terminated. Cannot be started or resumed
`failed`	Provisioning failed. See Failure Fields for why

Failure Fields

When status is failed, these fields explain the failure and the next step. Internal service details are replaced with a generic customer message.

Field	Description
`failure_reason`	A customer-facing explanation. Internal service issues use a generic message, and diagnostic details are kept internally
`failure_code`	A stable code you can branch on (table below)
`retryable`	`true` if retrying the same request later is sensible, `false` if something in the request must change first
`suggested_action`	One sentence: what to do about it

`failure_code`	Retryable	Meaning
`PROVIDER_CAPACITY`	yes	The provider had no capacity for this offer and location. Retry in a few minutes or choose another offer
`PROVIDER_MAINTENANCE`	yes	The provider went into maintenance just after the request was accepted, so nothing was started there. Retry after the maintenance window, or choose another provider
`VOLUME_LOCATION_PINNED`	yes	An attached volume pinned the deployment to one location, and that location had no capacity. Recreate the volume elsewhere, or retry later
`VOLUME_LOCATION_MISMATCH`	no	The attached volume is in a different location from the instance
`IMAGE_INCOMPATIBLE`	no	The OS image cannot run on this GPU type or is not offered for it
`OFFER_NOT_VM_CAPABLE`	no	A VM template was launched on a host without VM support
`SSH_KEY_REJECTED`	yes	The provider rejected the SSH key material. Re-upload the key if it persists
`SSH_KEY_MISSING`	no	No SSH key the provider accepts was sent. For example, only ECDSA keys were selected, and the provider takes only RSA or Ed25519. Deploy with an RSA or Ed25519 key
`INVALID_DISK_SIZE`	no	The disk is below the provider minimum
`INSUFFICIENT_BALANCE`	no	The first hour could not be reserved
`PROVIDER_INSTANCE_FAILED`	yes	The instance was created but the provider reported it failed. A retry usually lands on a different host
`INSTANCE_BOOT_TIMEOUT`	yes	The instance never became ready within the wait window
`TUNNEL_NEVER_REGISTERED`	yes	The instance booted but its tunnel client never reached our tunnel server
`APP_HEALTH_TIMEOUT`	yes	The tunnel connected, but the application never passed its health check. Common with large images that take longer than the window to pull
`USER_CANCELLED`	yes	The deployment was stopped while provisioning
`WORKER_INTERRUPTED`	yes	A platform worker restarted mid-provision. Not caused by you or the provider
`PLATFORM_PROVIDER_ISSUE`	yes	A temporary service issue. Choose another provider or contact support before retrying
`DUPLICATE_REQUEST`	no	An internal request key was reused on the provider’s side of a retry. This is not related to any header or idempotency key you control, since the API accepts none from you. Contact support if you see it repeatedly
`UNKNOWN`	yes	The failure could not be classified. Contact support with the deployment ID

retryable describes whether a new request may succeed later. It does not mean that the current request will be retried automatically. A reserved first hour is always refunded when provisioning fails, whatever the code.

Connection Fields

Connection info is null until the deployment reaches active status:

Field	Description
`public_ip`	Instance IP address
`ssh_port`	SSH port (usually 22)
`ssh_user`	SSH username (for example, `root`, `Ubuntu`)
`jupyter_url`	Always `null` on API-created deployments. The API does not launch templates, and this field is only ever set for a dashboard template deployment
`tunnel_id`	The subdomain of a template’s private application link, or `null`. Not a bastion: the bastion feature this field once referred to no longer exists. Always `null` on API-created deployments, since the API does not launch templates
`endpoint_url`	The full private application link for a template deployment (`https://<tunnel_id>.app.deploygpu.ai`), or `null`. Always `null` on API-created deployments

Errors

404 not_found: the deployment does not exist, or is not owned by you.

Shutdown and Start

Shutdown keeps the same VM and disks, and full compute billing continues. It does not pause billing or preserve running processes or GPU memory. Normal insufficient-balance teardown still applies. To end compute charges and permanently delete the instance disk, use Stop Deployment.

These API-only operations are supported for Verda and Hyperstack deployments whose deployment status is active. They do not change the deployment’s ID, billing period, or deployment status. Other providers return 400 provider_not_supported. Application startup after powering on depends on the services configured inside the VM.

# Gracefully power off, retaining the VM and disks
curl -X POST https://api.deploygpu.ai/api/v1/deployments/DEPLOYMENT_ID/shutdown \
  -H "Authorization: Bearer gpu_live_YOUR_KEY"

# Power the same VM back on
curl -X POST https://api.deploygpu.ai/api/v1/deployments/DEPLOYMENT_ID/start \
  -H "Authorization: Bearer gpu_live_YOUR_KEY"

Shutdown requires a running power state; start requires stopped. If the VM is already at the requested target, the endpoint returns 200 OK with action_submitted: false. Otherwise, the provider accepting the request returns 202 Accepted:

While the provider is in maintenance, both endpoints return 503 provider_maintenance, even when the VM is already at the requested target. A VM that is powered off then stays off, and is billed, until the maintenance ends, so start it before the window begins. Check the HTTP status of each call in a script: a loop that waits for stopped or running after a refused request never finishes.

{
  "id": "a6305686-fe03-494c-b254-9ee0a2453068",
  "status": "active",
  "power_state": "running",
  "billing_continues": true,
  "requested_action": "shutdown",
  "action_submitted": true
}

power_state is the provider observation before submitting the action, not confirmation that it has finished. Poll the power endpoint until it reports stopped for shutdown or running for start. On Hyperstack, power_state reads unknown for about 20 to 30 seconds while the VM is changing state. That is expected, so keep polling; a /shutdown or /start sent in that window returns 400 validation_error. Wait for the first action to finish before sending the opposite action, and do not resend the same action until /power reflects it. SSH and applications can take longer to become ready after the VM is running: expect a few minutes. On Hyperstack, the network can take up to 10 minutes to reach the VM again after a start, even though it has already booted.

If the VM stopped responding

A shutdown or reboot run inside the VM is not visible to the provider, so power_state can stay running while the VM is down. On Verda, confidential-computing machines (the B200, B300 and RTX PRO 6000 types) cannot reboot from inside at all: reboot or shutdown -r leaves them down until they are powered off and on again. To bring the VM back, call /shutdown, poll /power until it reports stopped, then call /start. /start on a VM reported as running returns 200 OK without sending a start: Verda’s start action reboots a running VM, and Hyperstack refuses it.

Get Power State

curl https://api.deploygpu.ai/api/v1/deployments/DEPLOYMENT_ID/power \
  -H "Authorization: Bearer gpu_live_YOUR_KEY"

Returns 200 OK with the same fields, requested_action: null, and action_submitted: false. The power_state is read from the provider on each request: running, stopped (powered off, billing continues), pending (being created or validated), stopping (being deleted, reported by Verda only), terminated, failed, or unknown (no clear answer from the provider, or a Hyperstack VM in the middle of a shutdown or start). terminated and failed mean the VM is gone; the health check reconciles the deployment within a few minutes, or once the provider’s maintenance has ended if it is in maintenance. This endpoint also requires an active Verda or Hyperstack deployment.

Power Control Errors

HTTP / Code	Meaning
`401 unauthorized`	Authentication is required
`404 not_found`	Deployment does not exist or belongs to another account
`400 provider_not_supported`	Deployment is not on Verda or Hyperstack
`400 validation_error`	Deployment is not active, or the provider power state does not allow the action
`503 provider_maintenance`	The provider is in maintenance, so shutdown and start are paused. Returned with `Retry-After`. Reading the power state still works. See provider maintenance
`502 provider_error`	Could not confirm the provider operation. Poll the power endpoint before retrying; the request may already have reached the provider

Stop Deployment

Stop permanently terminates the VM and deletes its instance disk. It cannot be started or resumed afterward. Copy off any files you need before calling this endpoint. To run again, create a new deployment.

POST /api/v1/deployments/{id}/stop
DELETE /api/v1/deployments/{id}

Both endpoints start the same teardown flow. The instance is terminated and billing stops. Both return 200 OK with the updated deployment object, and the deployment’s history is retained rather than deleted. Stopping also works while the provider is in maintenance. Billing ends when the request is accepted, and the instance is removed as soon as the provider accepts the delete. Until then the deployment shows stopping. Attached persistent volumes are detached and retained. They continue to incur storage charges until deleted and can be attached to a new compatible deployment. Retaining a volume or deployment history does not preserve a restartable VM.

Response

{
  "id": "a6305686-fe03-494c-b254-9ee0a2453068",
  "status": "stopping",
  "stop_reason": "USER_REQUESTED",
  ...
}

Errors

Code	When
`not_found`	Deployment not found
`validation_error`	Cannot stop (already stopping, terminated, or failed)

​Create Deployment

​Request Body

​Response 202 Accepted

​Errors

​List Deployments

​Query Parameters

​Response

​Get Deployment

​Deployment Status

​Failure Fields

​Connection Fields

​Errors

​Shutdown and Start

​If the VM stopped responding

​Get Power State

​Power Control Errors

​Stop Deployment

​Response

​Errors

Create Deployment

Request Body

Response `202 Accepted`

Errors

List Deployments

Query Parameters

Response

Get Deployment

Deployment Status

Failure Fields

Connection Fields

Errors

Shutdown and Start

If the VM stopped responding

Get Power State

Power Control Errors

Stop Deployment

Response

Errors