Skip to navigation

Restore a GPU VM backup

Restores a GPU VM backup recovery point by replacing the VM, creating a new GPU VM, or restoring a single volume. Asynchronous: the response carries restore_id; poll the restore status read until status is succeeded, failed or cancelled. If your client times out, read the status; never resubmit. Requires scope: vm.write.

# Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first).
# VM_ID: Virtual machine ID
curl -X POST "https://api.ibee.ai/v1/compute/gpu-vms/$VM_ID/backups/actions/restore?workspace_id=$WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"recovery_point_id": "<recovery_point_id>"}'

Authentication

AuthorizationBearer

IBEE platform API token. Production tokens start with ibee_prod_key_; development tokens start with ibee_dev_key_. Use a token only with its matching gateway environment.

Path parameters

vm_idstringRequired
Virtual machine ID.

Query parameters

workspace_idstringRequiredformat: "^[1-9][0-9]*$">=1 character

The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected.

Request

This endpoint expects an object.
recovery_point_idstringRequired>=1 character

Recovery point to restore: the recovery_point_id of a succeeded backup run.

target_modeenumOptionalDefaults to replace

Where to restore.

  • replace: onto the source VM, replacing its current disks (default).
  • new_vm: into a new VM described by the target_* fields.
  • volume_only: only the volume named in selected_volume_id.
Allowed values:
target_vm_namestring or nullOptional1-255 characters

Name for the new VM (new_vm mode).

target_cpuinteger or nullOptional1-256

vCPUs for the new VM (1-256).

target_ram_mbinteger or nullOptional512-2097152

RAM for the new VM in MB (512-2097152).

target_disk_gbinteger or nullOptional10-10000

Root disk for the new VM in GB (10-10000).

target_plan_idstring or nullOptional1-255 characters

Compute plan for the new VM, from GET /compute/plans.

target_gpu_modelstring or nullOptional1-255 characters

GPU model for a new GPU VM, for example A100.

target_gpu_countinteger or nullOptional0-16

Number of GPUs for a new GPU VM (0-16).

target_site_idstring or nullOptional1-255 characters

Site for the new VM, from GET /compute/sites.

target_volume_namesmap from strings to stringsOptional
Names for the restored volumes, keyed by the source volume id. Volumes not listed keep their source name.
selected_volume_idstring or nullOptional>=1 character

Volume to restore in volume_only mode.

auto_startbooleanOptionalDefaults to true
Start the VM once the restore completes. Default true.

Response

Backup restore started successfully.
organization_idstring
ID of the organization that owns the VM.
workspace_idstring
ID of the workspace the VM belongs to.
restore_idstring
Unique ID of the restore job.
source_vm_idstring
VM the recovery point was taken from.
target_modeenum
  • replace: restored onto the source VM.
  • new_vm: restored into a new VM.
  • volume_only: a single volume was restored.
Allowed values:
recovery_point_idstring
Recovery point that was restored.
statusenum

Lifecycle status of a backup run, snapshot set or restore.

  • queued: accepted and waiting to start.
  • running: in progress.
  • succeeded: finished; the recovery point is usable.
  • failed: stopped with an error (see error_message).
  • cancelled: stopped before it completed.
  • deleting: remote backup deletion is in progress; the run becomes unavailable after cleanup.
organization_namestring or nullOptional
Display name of the owning organization, when the service has it.
workspace_namestring or nullOptional
Display name of the workspace, when the service has it.
target_vm_idstring or nullOptional

VM that received the restore: the source VM for replace, the new VM for new_vm.

target_vm_namestring or nullOptional
Display name of the target VM.
recovery_point_typeenumOptional
  • backup: the recovery point is a backup run.
  • snapshot: the recovery point is a snapshot set.
Allowed values:
started_atdatetime or nullOptional

When the restore started (ISO 8601); null while queued.

completed_atdatetime or nullOptional

When the restore finished (ISO 8601); null until it does.

error_messagestring or nullOptional

Error detail when status is failed.

metadatamap from strings to anyOptional

Additional service-specific key-value data.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
413
Content Too Large Error
422
Unprocessable Entity Error
423
Locked Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error
504
Gateway Timeout Error