Skip to content

Volume

List all volumes

GET /api/volumes

OAuth authorization required: project_read

Schema
  • volumes: Array
    • id: Integer
    • name: String
    • label: String
    • region_id: Integer
    • to_trash: Boolean
    • trash_after: DateTime
    • size: Decimal
    • usage: Decimal
    • usage_checked: DateTime
    • trashed_by_id: Integer
    • detached_at: DateTime
    • subscription_id: Integer
    • enable_sftp: Boolean
    • borg_enabled: Boolean
    • borg_freq: String
    • borg_strategy: String<file,mysql>
    • borg_keep_hourly: Integer
    • borg_keep_daily: Integer
    • borg_keep_weekly: Integer
    • borg_keep_monthly: Integer
    • borg_keep_annually: Integer
    • borg_pre_backup: Array<String>
    • borg_post_backup: Array<String>
    • borg_pre_restore: Array<String>
    • borg_post_restore: Array<String>
    • borg_rollback: Array<String>
    • updated_at: DateTime
    • created_at: DateTime
    • volume_maps: Array
      • id: Integer
      • mount_ro: Bool | Mount read only
      • mount_path: String
      • container_service: Object
        • id: Integer
        • csrn: String
        • name: String
        • label: String
    • template: Object
      • id: Integer
      • csrn: String
      • container_image: Object
        • id: Integer
        • csrn: String
        • label: String

View Volume

GET /api/volumes/{id}

OAuth authorization required: project_read

Schema
  • volume: Object
    • id: Integer
    • name: String
    • label: String
    • region_id: Integer
    • to_trash: Boolean
    • trash_after: DateTime
    • size: Decimal
    • usage: Decimal
    • usage_checked: DateTime
    • trashed_by_id: Integer
    • detached_at: DateTime
    • subscription_id: Integer
    • enable_sftp: Boolean
    • borg_enabled: Boolean
    • borg_freq: String
    • borg_strategy: String<file,mysql>
    • borg_keep_hourly: Integer
    • borg_keep_daily: Integer
    • borg_keep_weekly: Integer
    • borg_keep_monthly: Integer
    • borg_keep_annually: Integer
    • borg_pre_backup: Array<String>
    • borg_post_backup: Array<String>
    • borg_pre_restore: Array<String>
    • borg_post_restore: Array<String>
    • borg_rollback: Array<String>
    • updated_at: DateTime
    • created_at: DateTime
    • volume_maps: Array
      • id: Integer
      • mount_ro: Bool | Mount read only
      • mount_path: String
      • container_service: Object
        • id: Integer
        • csrn: String
        • name: String
        • label: String
    • template: Object
      • id: Integer
      • csrn: String
      • container_image: Object
        • id: Integer
        • csrn: String
        • label: String

List all backups

GET /api/volumes/{volume-id}/backups

OAuth authorization required: project_read

Schema
  • usage: Integer | Size on disk (deduplicated)
  • size: Integer | Expanded total size
  • archives: Array
    • id: String | URL-safe base64 encoded name of the backup
    • label: String
    • created: DateTime
    • export: Object | The latest download requested for this backup.
      • status: String<none,in_progress,ready,failed,expired>
      • url: String | Download URL. Only when status is ready.
      • expires_at: Integer | When url expires, as seconds since epoch. Only when status is ready.
      • size: Integer | Only when status is ready.
      • error: String | Only when status is failed.

Create a backup

POST /api/volumes/{volume-id}/backups

OAuth authorization required: project_write

Responds with 201 Created.

Schema
  • name: String | Name of backup. Must be at least 3 characters long, and should not include spaces.
  • callback: Object | Optional. Called when the backup finishes. See API callbacks.
    • url: String
    • authorization: String | Right side of the authorization header. Example: Bearer 12345 or Token 12345

Delete a backup

DELETE /api/volumes/{volume-id}/backups/{id}

OAuth authorization required: project_write

id is the backup's id from List all backups. Responds with 200 OK. A backup whose download is still being prepared can't be deleted (422). An id that can't be decoded is refused with 422 before anything is sent to the node.

Schema
  • callback: Object | Optional. Called when the deletion finishes. See API callbacks.
    • url: String
    • authorization: String | Right side of the authorization header.

Restore a backup

POST /api/volumes/{volume-id}/restore

OAuth authorization required: project_write

Responds with 202 Accepted.

Schema
  • name: String | Name of backup to restore (the id from List all backups, decoded as URL-safe base64)
  • callback: Object | Optional. Called when the restore finishes. See API callbacks.
    • url: String
    • authorization: String | Right side of the authorization header.

Download a backup

POST /api/volumes/{volume-id}/exports

OAuth authorization required: project_write

Prepares a download of a backup. Responds with 202 Accepted; the download URL is not returned here. Poll List all backups, where the backup's export object carries the status and, once ready, the url, or supply a callback to be notified when it is ready. Only one download can be prepared per volume at a time (405).

Schema
  • id: String | The backup's id from List all backups.
  • callback: Object | Optional. Called when the download is ready or has failed. See API callbacks.
    • url: String
    • authorization: String | Right side of the authorization header.

When the node is unavailable

Backups, restores, backup deletion, and downloads need the volume's node. While it is in maintenance or offline (or the volume has no node), these requests return 409 Conflict with errors, code (node_maintenance or node_offline), and node_status; they previously returned 422. The event is still recorded and failed, so a supplied callback fires with status: "failed" and the same code. See Refused and deferred actions.

While another backup operation is in progress on the volume, or before any container has mounted it, backups, restores, and deletion return 405 Method Not Allowed with errors. Other failures return 422 Unprocessable Entity with errors.