Backup vault operations

The modern capabilities of IBM Cloud® Object Storage are conveniently available through a RESTful API. Operations and methods that are used to interact with buckets (where objects are stored) are documented here.

For more information about the permissions and access, see Bucket permissions.

A note about Access/Secret Key (HMAC) authentication

When authenticating to your instance of IBM Cloud® Object Storage by using HMAC credentials, you need the information that is represented in Table 1 when constructing an HMAC signature.

HMAC signature components
Key	Value	Example
{access_key}	Access key that is assigned to your Service Credential	`cf4965cebe074720a4929759f57e1214`
{date}	The formatted date of your request (`yyyymmdd`)	`20180613`
{region}	The location code for your endpoint	`us-standard`
{signature}	The hash that is created by using the secret key, location, and date	`ffe2b6e18f9dcc41f593f4dbb39882a6bb4d26a73a04326e62a8d344e07c1a3e`
{timestamp}	The formatted date and time of your request	`20180614T001804Z`

Backup Vault Management Operations

The IBM Cloud® Object Storage Backup Vault API provides operations for creating, managing, and interacting with backup vaults. Backup vaults are used to store backups of buckets and their objects.

For more information about permissions and access, see Backup Vault permissions.

List Backup Vaults

A GET request to the /backup_vaults endpoint returns a list of backup vaults associated with the specified service instance.

Headers
Header	Type	Required?	Description
`service_instance_id`	String	Yes	The ID of the service instance to list backup vaults for.

Syntax

GET https://{endpoint}/backup_vaults

Example request

GET /backup_vaults HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com
service_instance_id: {service_instance_id}

Example response

{
  "next": {
    "token": "SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz",
    "href": "config.cloud-object-storage.cloud.ibm.com/v1/backup_vaults?token=1znNRhmyheG-pm6mlMKFsoxcKXFnW1hgBb2_6ZReqHduL3rivfeBWHeyL-OaJvtfVZjKrgRVmODtOdVeQEXkKCxDWpA5hRWuv9WgTPR2eLIN9fbEaTxqdNO4dp0sQeHh4HO-13nTgRV_1QGiR1QFzREHX3wzquLn9o_1DZZAEP-vAY2V8d6BCA1z2krhpMfswKJ8r6UynUc0W5JHSH4auwJ6jC-h8sc8NEcQpHUx2Ep4oxebmtJMaycQSjLA3J2fdcYuysKq3YIcszDnPte0zwr25x5_GmBrxlgd2oesjfyTaLHfIg1g4TD0uH9m9aEAv"
  },
  "backup_vaults": [
    "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:backup-vault:otherbackupvault",
    "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:backup-vault:somebackupvault"
  ]
}

Create a Backup Vault

A POST request to the /backup_vaults endpoint creates a new backup vault.

Headers
Header	Type	Required?	Description
`Authorization`	String	Yes	Bearer token for authentication.
`service_instance_id`	String	Yes	The ID of the service instance to list backup vaults for.

Syntax

POST https://{endpoint}/backup_vaults

Request body

{
  "backup_vault_name": "myBackupVault",
  "region": "us-south",
  "sse_kp_customer_root_key_crn": "crn:v1:bluemix:public:kms:us-south:a/123456:key/abcd1234"
}

Example request

POST /backup_vaults HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com

{
  "activity_tracking": {
    "management_events": true
  },
  "metrics_monitoring": {
    "usage_metrics_enabled": true
  },
  "backup_vault_name": "lzuuahcf7ocayou4jrr4",
  "region": "-v5W5jEUSwxnItfY583Iymb63CFvAf",
  "sse_kp_customer_root_key_crn": "u1_0eoiRRzyW.XOKVn16oKQGFtfuSPi8KzWosGFW6sIMYduswlbXuZOQtHn7D"
}

Example response

{
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:mybackupvault",
  "service_instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436::",
  "time_created": "2024-06-02T12:00:00.000Z",
  "time_updated": "2024-06-02T12:00:00.000Z",
  "bytes_used": 0,
  "region": "us-south",
  "backup_vault_name": "mybackupvault"
}

Get Backup Vault Details

A GET request to the /backup_vaults/{backup_vault_name} endpoint retrieves the config for a specific backup vault.

Path parameters
Path Parameter	Type	Required?	Description
`backup_vault_name`	String	Yes	The name of the backup vault.

Syntax

GET https://{endpoint}/backup_vaults/{backup_vault_name}

Example request

GET /backup_vaults/myBackupVault HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com

Example response

{
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:mybackupvault",
  "service_instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436::",
  "time_created": "2024-06-02T12:00:00.000Z",
  "time_updated": "2024-06-02T12:00:00.000Z",
  "bytes_used": 0,
  "region": "us-south",
  "backup_vault_name": "mybackupvault"
}

Update a Backup Vault

A PATCH request to the /backup_vaults/{backup_vault_name} endpoint updates the config on a specific backup vault.

Path parameters
Path Parameter	Type	Required?	Description
`backup_vault_name`	String	Yes	The name of the backup vault.

Syntax

PATCH https://{endpoint}/backup_vaults/{backup_vault_name}

Example request

GET /backup_vaults/myBackupVault HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com

{
  "activity_tracking": {
    "management_events": true
  },
  "metrics_monitoring": {
    "usage_metrics_enabled": true
  }
}

Example response

{
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:mybackupvault",
  "service_instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436::",
  "time_created": "2024-06-02T12:00:00.000Z",
  "time_updated": "2024-06-02T12:00:00.000Z",
  "bytes_used": 0,
  "region": "us-south",
  "backup_vault_name": "mybackupvault"
}

Delete a Backup Vault

A DELETE request to the /backup_vaults/{backup_vault_name} endpoint deletes a backup vault. The vault must be empty before deletion.

Path parameters
Path Parameter	Type	Required?	Description
`backup_vault_name`	String	Yes	The name of the backup vault.

Syntax

DELETE https://{endpoint}/backup_vaults/{backup_vault_name}

Example request

DELETE /backup_vaults/myBackupVault HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com

Example response

HTTP/1.1 204 No Content

For more information about backup vault operations, see Backup vault management.

Recovery Range operations

The IBM Cloud® Object Storage Recovery Range API provides operations for listing and retrieving recovery ranges. Recovery ranges represent the time intervals during which data in a backup vault can be restored.

For more information about permissions and access, see Recovery Range permissions.

List Recovery Ranges

A GET request to the /backup_vaults/{backup_vault_name}/recovery_ranges endpoint retrieves all recovery ranges for a specific backup vault.

Path parameters
Path Parameter	Type	Required?	Description
`backup_vault_name`	String	Yes	The name of the backup vault.

Query parameters
Query Parameter	Type	Required?	Description
`source_resource_crn`	String	No	Filters recovery ranges by the source resource CRN.
`token`	String	No	Continuation token for paginated results.

Syntax

GET https://{endpoint}/backup_vaults/{backup_vault_name}/recovery_ranges

Example request

GET /backup_vaults/myBackupVault/recovery_ranges HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com

Example response

{
  "next": {
    "token": "SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz",
    "href": "config.cloud-object-storage.cloud.ibm.com/v1/backup_vaults/mybackupvault/recovery_ranges?token=1znNRhmyheG-pm6mlMKFsoxcKXFnW1hgBb2_6ZReqHduL3rivfeBWHeyL-OaJvtfVZjKrgRVmODtOdVeQEXkKCxDWpA5hRWuv9WgTPR2eLIN9fbEaTxqdNO4dp0sQeHh4HO-13nTgRV_1QGiR1QFzREHX3wzquLn9o_1DZZAEP-vAY2V8d6BCA1z2krhpMfswKJ8r6UynUc0W5JHSH4auwJ6jC-h8sc8NEcQpHUx2Ep4oxebmtJMaycQSjLA3J2fdcYuysKq3YIcszDnPte0zwr25x5_GmBrxlgd2oesjfyTaLHfIg1g4TD0uH9m9aEAv"
  },
  "recovery_ranges": [
    {
      "recovery_range_id": "44d3dd41-d616-4d25-911a-9ef7fbf28aef",
      "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
      "backup_policy_name": "myBackupPolicy",
      "range_start_time": "2024-06-02T12:00:00.000Z",
      "range_end_time": "2024-06-03T12:00:00.000Z",
      "range_create_time": "2024-06-02T12:00:00.000Z",
      "retention": {
        "delete_after_days": 100
      }
    },
    {
      "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
      "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
      "backup_policy_name": "myBackupPolicy",
      "range_start_time": "2024-06-04T12:00:00.000Z",
      "range_end_time": "2024-06-05T12:00:00.000Z",
      "range_create_time": "2024-06-04T12:00:00.000Z",
      "retention": {
        "delete_after_days": 100
      }
    }
  ]
}

Get Recovery Range Details

A GET request to the /backup_vaults/{backup_vault_name}/recovery_ranges/{recovery_range_id} endpoint retrieves details about a specific recovery range.

Path parameters
Path Parameter	Type	Required?	Description
`backup_vault_name`	String	Yes	The name of the backup vault.
`recovery_range_id`	String	Yes	The ID of the recovery range.

Syntax

GET https://{endpoint}/backup_vaults/{backup_vault_name}/recovery_ranges/{recovery_range_id}

Example request

GET /backup_vaults/myBackupVault/recovery_ranges/44d3dd41-d616-4d25-911a-9ef7fbf28aef HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com

Example response

{
  "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
  "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
  "backup_policy_name": "myBackupPolicy",
  "range_start_time": "2024-06-04T12:00:00.000Z",
  "range_end_time": "2024-06-05T12:00:00.000Z",
  "range_create_time": "2024-06-04T12:00:00.000Z",
  "retention": {
    "delete_after_days": 100
  }
}

Update Recovery Range Detail

A PATCH request to the /backup_vaults/{backup_vault_name}/recovery_ranges/{recovery_range_id} endpoint updates details for a specific recovery range.

Path parameters
Path Parameter	Type	Required?	Description
`backup_vault_name`	String	Yes	The name of the backup vault.
`recovery_range_id`	String	Yes	The ID of the recovery range.

Syntax

PATCH https://{endpoint}/backup_vaults/{backup_vault_name}/recovery_ranges/{recovery_range_id}

Example request

GET /backup_vaults/myBackupVault/recovery_ranges/44d3dd41-d616-4d25-911a-9ef7fbf28aef HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com

{
  "retention": {
    "delete_after_days": 10
  }
}

Example response

{
  "retention": {
    "delete_after_days": 200
  }
}

For more information about recovery range operations, see Backup vault management.

Restore operations

The IBM Cloud® Object Storage Restore API provides operations for initiating and managing restore operations. Restore operations allow you to recover data from a backup vault to a target bucket.

For more information about permissions and access, see Restore permissions.

Initiate a Restore

A POST request to the /backup_vaults/{backup_vault_name}/restores endpoint initiates a restore operation.

Path parameters
Path Parameter	Type	Required?	Description
`backup_vault_name`	String	Yes	The name of the backup vault to restore from.

Syntax

POST https://{endpoint}/backup_vaults/{backup_vault_name}/restores

Request body

{
  "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
  "restore_point_in_time": "2024-06-04T12:12:00.000Z",
  "restore_type": "in_place",
  "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket"
}

Example request

POST /backup_vaults/myBackupVault/restores HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com

{
  "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
  "restore_point_in_time": "2024-06-04T12:12:00.000Z",
  "restore_type": "in_place",
  "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket"
}

Example response

{
  "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
  "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
  "restore_point_in_time": "2024-06-04T12:12:00.000Z",
  "restore_type": "in_place",
  "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket",
  "restore_id": "b0bcb32b-0fa9-423c-b10b-9d4328e5fc63",
  "restore_status": "initializing",
  "init_time": "2024-06-10T12:12:00.000Z"
}

List Restores

A GET request to the /backup_vaults/{backup_vault_name}/restores endpoint retrieves all restore operations for a specific backup vault.

Path parameters
Path Parameter	Type	Required?	Description
`backup_vault_name`	String	Yes	The name of the backup vault.

Syntax

GET https://{endpoint}/backup_vaults/{backup_vault_name}/restores

Example request

GET /backup_vaults/myBackupVault/restores HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com

Example response

{
  "next": {
    "token": "SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz",
    "href": "config.cloud-object-storage.cloud.ibm.com/v1/backup_vaults/mybackupvault/restores?Token=SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz"
  },
  "restores": [
    {
      "restore_id": "b0bcb32b-0fa9-423c-b10b-9d4328e5fc63",
      "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
      "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
      "restore_point_in_time": "2024-06-04T12:12:00.000Z",
      "restore_type": "in_place",
      "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket",
      "restore_status": "running",
      "restore_percent_progress": 50,
      "init_time": "2024-06-10T12:12:00.000Z"
    },
    {
      "restore_id": "3deefef0-3ed7-492c-8828-00fb33e64f88",
      "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
      "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
      "restore_point_in_time": "2024-06-04T12:12:00.000Z",
      "restore_type": "in_place",
      "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:othertargetbucket",
      "restore_status": "initializing",
      "init_time": "2024-06-10T12:24:00.000Z"
    }
  ]
}

Get Restore Details

A GET request to the /backup_vaults/{backup_vault_name}/restores/{restore_id} endpoint retrieves details about a specific restore operation.

Path parameters
Path Parameter	Type	Required?	Description
`backup_vault_name`	String	Yes	The name of the backup vault.
`restore_id`	String	Yes	The ID of the restore operation.

Syntax

GET https://{endpoint}/backup_vaults/{backup_vault_name}/restores/{restore_id}

Example request

GET /backup_vaults/myBackupVault/restores/b0bcb32b-0fa9-423c-b10b-9d4328e5fc63 HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
Host: config.cloud-object-storage.cloud.ibm.com

Example response

{
  "restore_id": "b0bcb32b-0fa9-423c-b10b-9d4328e5fc63",
  "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
  "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
  "restore_point_in_time": "2024-06-04T12:12:00.000Z",
  "restore_type": "in_place",
  "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket",
  "restore_status": "running",
  "restore_percent_progress": 50,
  "init_time": "2024-06-10T12:12:00.000Z"
}

For more information about restore operations, see Backup vault management.