CubeBackup API Reference

INTRODUCTION

Starting with version 4.9, CubeBackup for Google Workspace provides an API for administrators to integrate the backup service with their own systems. This powerful and flexible API can be used to set up a new CubeBackup instance, access and monitor backup status, automate backup management and license assignment, as well as many other routine tasks.

The CubeBackup for Google Workspace API is organized around REST. It has predictable resource-oriented URLs, accepts form-encoded data and JSON payloads in the HTTP request body, and returns standard HTTP response codes with human-readable or JSON-encoded responses.

The following docs will demonstrate using curl to interact with the CubeBackup API over HTTP.

AUTHENTICATION

Step 1. Enable the API feature on your CubeBackup instance

For security purposes, the CubeBackup API is disabled by default. To enable the API on your CubeBackup for Google Workspace instance, please modify the configuration file:

Open the config file config.toml on the backup server using a text editor.

Note:
Starting with version 4.7, the configuration file is located at <installation directory>/etc/config.toml for fresh installations of CubeBackup. For installations upgraded through the console, or versions prior to 4.7, the configuration file is still located at <installation directory>/bin/config.toml.
On Windows, the installation directory is located at C:\Program Files\CubeBackup4 by default.
On Linux, the installation directory is located at /opt/cubebackup by default.
In the [API] section, please change the value of Enabled to true, and remove the comment character # from the beginning of the line. If your config.toml file doesn't contain an [API] section, please add it manually at the end of your configuration file. The [API] section should be formatted like the example below after modification.
```
[API]
Enabled = true
IPWhitelist = ["192.168.10.1/24", "2001:0db8::1428:57ab"]
```
Note:
1. For security concerns, we strongly recommend that you enable the IP whitelist to restrict access to your CubeBackup API. Under the [API] section, add a list of trusted IP addresses to the IPWhitelist array, and remove the comment character # from the beginning of the line. The IPWhitelist field accepts values in the format of IPv4, IPv6, or IP ranges of your office network.
2. For even more granular settings, you can go further and add the IPWhiteList field to a specific API client in the corresponding [[API.Clients]] section after creating an API client. This will restrict API requests for this particular client to only the whitelisted IP addresses.

Step 2. Create an API client

Before interacting with the API on your CubeBackup for Google Workspace instance, you will need to create an API client. Supply a valid client name, and a unique API key will be returned after running the following command:

cbackup addAPIClient <"client_name">

Tip:
On Windows, the cbackup.exe file is located in C:\Program Files\CubeBackup4\bin directory by default.
On Linux, the cbackup file is located in /opt/cubebackup/bin directory by default.

Options

-keyOnly

Using this option, this command will only return the API key in the response, which may help automate the API client creation in your CubeBackup integration.
-admin

By default, an individual CubeBackup API client will be granted with system admin privileges. However, CubeBackup also supports creating a linked API client for an existing CubeBackup admin, with identical permissions based on the role of the CubeBackup admin .

Using this option, you only need to pass along a CubeBackup admin email address, which will be automatically be assigned as the API client name. For example:
```
cbackup addAPIClient -admin [email protected]
```

NOTE:

The API key will only be displayed once when it is created and cannot be retrieved in the future. Please be sure to save it in a secure location for future usage.
This command requires Administrator/root privilege.

If CubeBackup runs on Windows, please run this command as an Administrator.
If CubeBackup runs on Linux, please use sudo … in the bash shell.

Step 3. Authenticate requests with API key

The CubeBackup API authenticates your HTTP request using the API keys of each API client. You can pass the API key into a REST API call using the Authorization header.

EXAMPLE

curl --request POST ".../api/v1/..." \
  --header "Authorization:{API key}"

Step 4. Manage your API clients

All active API clients are listed in the configuration file config.toml on your backup server.

As in the sample, you can view the list of enabled API clients on a CubeBackup instance, and disable any API client by commenting out or deleting the corresponding record in the config.toml file.

EXAMPLE

...
[[API.Clients]]
Name = "client1"
Id = "da1c122158...ad14b3240f7"
Admin = false

[[API.Clients]]
Name = "[email protected]"
Id = "b83ffc173e...e648daa96bb"
Admin = true
...

Step 5. Keep your API keys safe

CubeBackup API keys carry many privileges and can be used to make any API call such as modifying system settings or retrieving user information. Please be sure to keep them secure and do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

ERRORS

CubeBackup uses conventional HTTP response codes to indicate the success or failure of an API request. In general,

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error, giving a brief human-readable explanation in the Message field (such as insufficient permissions, the requested resource does not exist, required parameter missing or wrong format of the form body, etc.).
Codes in the 5xx range indicate an unexpected error.

CORE RESOURCES

Setup

The API can be used to set up a new CubeBackup instance. You can use it to retrieve the initial setup status, as well as create a system admin account during the final steps of the setup process.

To grant your CubeBackup instance access to your Google Workspace data, you can also use the API to upload a GCP service account during the initial setup. Additionally, you can retrieve the service account currently on record using this API.

Related guide:

How to complete the initial configuration and add new domains to back up using CubeBackup APIs .
A sample Python script for the initial setup using CubeBackup APIs can be found in our Git repository .

ENDPOINTS

GET /api/v1/setup/status
POST /api/v1/setup/complete
POST /api/v1/google/sat
GET /api/v1/google/sat

Retrieve the setup status

Retrieve the current setup status to check if the initial setup is done.

PARAMETERS
No parameters.

RESPONSE
Returns the setup status string in the response body:

"done" if the setup is complete
"pending" if the setup is not complete

Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/setup/status

curl -L ".../api/v1/setup/status" \
  --header "Authorization:255c6...88111"

Create a system admin during initial setup

Creating a valid system admin for the CubeBackup web console is the last step of CubeBackup initial setup. This API will check the storage and service account setup status before successfully creating the system admin, and will be disabled once the initial setup is marked as done.

PARAMETERS
AdminName required
Name of the newly-created system admin.
AdminEmail required
Email address for the newly-created system admin.
Password required
Password of the newly-created system admin.

RESPONSE
Returns "OK" if the CubeBackup admin is successfully created and the initial setup is complete.
Otherwise, returns an error with a detailed Message attribute in the response body.

Tip: A common source of error is that the service account key is not yet uploaded, or the storage location is not configured yet.

POST /api/v1/setup/complete

curl -L \
  --request POST ".../api/v1/setup/complete"\
  --header "Authorization:255c6...88111" \
  --data AdminName="CubeSysAdmin" \
  --data AdminEmail="[email protected]" \
  --data Password="12...bc"

The Service account object

A valid Google Cloud Platform(GCP) Service account object contains the following attributes. All required attributes are already included in the service account key file downloaded from your GCP console. Follow the detailed instructions on how to generate a service account for CubeBackup .

Attributes
type string
project_id string
private_key_id string
private_key string
client_email string
client_id string
auth_uri string
token_uri string
auth_provider_x509_cert_url string
client_x509_cert_url string

The Service account object

{ 
  "type": "service_account", 
  "project_id": "cubebackup...test", 
  "private_key_id": "03cf6...e1165", 
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIE...v9zkg\n-----END PRIVATE KEY-----\n", 
  "client_email": "test...iam.gserviceaccount.com", 
  "client_id": "10279...82949", 
  "auth_uri": "https://accounts.google.com/o/oauth2/auth", 
  "token_uri": "https://oauth2.googleapis.com/token", 
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", 
  "client_x509_cert_url": "https://www.googleapis.com/...test.iam.gserviceaccount.com" 
}

Upload a service account

This API can help upload your GCP service account during the initial setup or update it with a new one to rotate or replace an invalid service account.

Please be sure to add the Content-Type: application/json header to this HTTP request.

PARAMETERS
The Service account object required
After generating the service account key file in GCP, you can open the JSON file using a text editor. Copy and paste the values to populate the Service account object.

RESPONSE
Returns "OK" if the service account is successfully uploaded.
Or this call returns an error code with a detailed Message attribute in the response body if the service account key or other properties are invalidly formatted, or if any other error occurs.

POST /api/v1/google/sat

curl -L \
  --request POST ".../api/v1/google/sat" \
  --header "Authorization:255c6...88111" \
  --header "Content-Type: application/json"\
  --data '{ 
    "type": "service_account", 
    "project_id": "cubebackup...test", 
    "private_key_id": "03cf6...e1165", 
    "private_key": "-----BEGIN PRIVATE KEY-----\nMIIE...v9zkg\n-----END PRIVATE KEY-----\n", 
    "client_email": "test...iam.gserviceaccount.com", 
    "client_id": "10279...82949", 
    "auth_uri": "https://accounts.google.com/o/oauth2/auth", 
    "token_uri": "https://oauth2.googleapis.com/token", 
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", 
    "client_x509_cert_url": "https://www.googleapis.com/...test.iam.gserviceaccount.com" 
  }'

Retrieve the current service account

Retrieve the current service account key.

PARAMETERS
No parameters.

RESPONSE
Returns the Service account object if a valid one has been successfully uploaded; otherwise, returns an error.

GET /api/v1/google/sat

curl -L ".../api/v1/google/sat" \
  --header "Authorization:255c6...88111"

Storage

The Storage object represents the backup repository of your CubeBackup instance. It contains the storage location, access credentials, and other storage settings.

Related guide:

ENDPOINTS

POST /api/v1/storage/settings
PATCH /api/v1/storage/settings
GET /api/v1/storage/settings
GET /api/v1/storage/status

The Storage object

Fields in the Storage object vary depending on the storage type. For a detailed explanation and sample of the required attributes, please click the appropriate tab below for your storage type and operating system.

Attributes
EncryptEnabled boolean
Whether or not the backup data should be encrypted.
Type enum
The storage type. LOCAL refers to Local disk.
IndexPath string
The storage location for the data index.
DataPath string
The storage location for the backup repository.

The Storage object

{ 
  "EncryptEnabled": true, 
  "Type": "LOCAL", 
  "IndexPath": "/opt/cubebackup/index", 
  "DataPath": "/var/cubebackup_data" 
}

Attributes
EncryptEnabled boolean
Whether or not the backup data should be encrypted.
Type enum
The storage type. WINS refers to Windows network location.
IndexPath string
The storage location for the data index.
WinsLocation string
The network storage location of the backup repository.
WinsUsername string
The username used to access the network location on Windows.
WinsPassword string
The password used to access the network location on Windows.

The Storage object

{
  "EncryptEnabled": true,
  "Type": "WINS",
  "IndexPath": "C:\\Program Files\\CubeBackup4\\index",
  "WinsLocation": "\\\\BACKUPNAS\\homes\\gsuitebackups",
  "WinsUsername": "BACKUPNAS\\cube",
  "WinsPassword": "12345"
}

Attributes
EncryptEnabled boolean
Whether or not the backup data should be encrypted.
Type enum
The storage type. NAS refers to Mounted Network storage.
IndexPath string
The storage location for the data index.
DataPath string
The mounted network storage location for the backup data.

The Storage object

{ 
  "EncryptEnabled": true, 
  "Type": "NAS", 
  "IndexPath": "/opt/cubebackup/index", 
  "DataPath": "/var/cubebackup_data" 
}

Attributes
EncryptEnabled boolean
Whether or not the backup data should be encrypted.
Type enum
The storage type. S3 refers to Amazon S3 storage.
IndexPath string
The storage location for the data index.
S3Bucket string
The name of the S3 bucket.
S3Region string
The region of the S3 bucket. For AWS S3 storage regions, please refer to this doc .
S3AccessKeyId string
The IAM Access key ID used to access the bucket.
S3SecretAccessKey string
The IAM Secret Access key used to access the bucket.
S3CoolStorageClass enum
The storage class for the backup data in Amazon S3.
Possible enum values:

STANDARD for Standard
STANDARD_IA for Standard-IA
ONEZONE_IA for One Zone-IA
INTELLIGENT_TIERING for Intelligent-Tiering
GLACIER_IR for Glacier Instant Retrieval

The Storage object

{
  "EncryptEnabled": true,
  "Type": "S3",
  "IndexPath": "/opt/cubebackup/index",
  "S3Bucket": "cubebackup-beta-ubuntu",
  "S3Region": "us-east-1",
  "S3AccessKeyId": "AKIAW...4YZEYUY",
  "S3SecretAccessKey": "gCA0U...pgiDX",
  "S3CoolStorageClass": "STANDARD_IA"
}

Attributes
EncryptEnabled boolean
Whether or not the backup data should be encrypted.
Type enum
The storage type. GOOGLE refers to Google Cloud storage.
IndexPath string
The storage location for the data index.
GoogleBucket string
The name of the Google Cloud Storage bucket.
GoogleCoolStorageClass enum
The storage class for the backup data in Google Cloud.
Possible enum values:

STANDARD for Standard
NEARLINE for Nearline
COLDLINE for Coldline
ARCHIVE for Archive

The Storage object

{
  "EncryptEnabled": true,
  "Type": "GOOGLE",
  "IndexPath": "/opt/cubebackup/index",
  "GoogleBucket": "cubebackup-beta",
  "GoogleCoolStorageClass": "COLDLINE"
}

Attributes
EncryptEnabled boolean
Whether or not the backup data should be encrypted.
Type enum
The storage type. AZURE refers to Microsoft Azure Blob storage.
IndexPath string
The storage location for the data index.
AzureAccountName string
The name of the Azure storage account.
AzureAccountKey string
The Access Key to the storage account.
AzureContainer string
The container in the storage account.
AzureCoolStorageClass enum
The access tier for the backup data in Azure Blob storage.
Possible enum values:

Hot for Hot
Cool for Cool
Cold for Cold

The Storage object

{ 
  "EncryptEnabled": true, 
  "Type": "AZURE",
  "IndexPath": "/opt/cubebackup/index",
  "AzureAccountName": "cube-account",
  "AzureAccountKey": "XihUF...SEYA==",
  "AzureContainer": "cube-container",
  "AzureCoolStorageClass": "Cool"
}

Attributes
EncryptEnabled boolean
Whether or not the backup data should be encrypted.
Type enum
The storage type. S3C refers to S3 compatible storage.
IndexPath string
The storage location for the data index.
S3Endpoint string
The appropriate service URL for the storage region of the bucket.
S3Bucket string
The name of the S3 compatible bucket.
S3Region string
The region of the S3 compatible bucket.
S3AccessKeyId string
The Access key ID used to access the bucket.
S3SecretAccessKey string
The Secret Access key used to access the bucket.

The Storage object

{
  "EncryptEnabled": true,
  "Type": "S3C",
  "IndexPath": "/opt/cubebackup/index",
  "S3Endpoint": "https://s3.us-west-000.backblazeb2.com",
  "S3Bucket": "cubebackup-bucket",
  "S3Region": "us-west-000",
  "S3AccessKeyId": "000b4...00007",
  "S3SecretAccessKey": "K000A...I4r7A"
}

Create the backup storage

This API can be used to configure the storage location during the initial setup of a CubeBackup instance, and will be disabled once the setup is marked as done in CubeBackup.

Please be sure to add the Content-Type: application/json header to this HTTP request.

PARAMETERS
The Storage object required
Please include all the required attributes for the storage type you have chosen.

RESPONSE
Returns the Storage object if the storage has been successfully configured.
Otherwise, returns an error with a detailed Message attribute in the response body if the storage writing test fails or any other error occurs.

POST /api/v1/storage/settings

curl -L \
  --request POST ".../api/v1/storage/settings"\
  --header "Authorization:255c6...88111" \
  --header "Content-Type: application/json"\
  --data '{
    "EncryptEnabled": true,
    "Type": "LOCAL",
    "IndexPath": "...",
    "DataPath": "..."
  }'

Update the storage settings

Update the storage settings of your current backup repository.

NOTE: This API should only be used to rename the storage location or update storage credentials. To change the backup repository location and migrate the backup data, please refer to How to migrate my Google Workspace backups to another storage location .

Please be sure to add the Content-Type: application/json header to this HTTP request.

PARAMETERS
The Storage object optional
Optional fields in the Storage object.

RESPONSE
Returns the Storage object if the storage settings have been successfully updated.
Otherwise, returns an error with a detailed Message attribute in the response body if the storage writing test fails or any other error occurs.

PATCH /api/v1/storage/settings

curl -L \
  --request PATCH ".../api/v1/storage/settings"\
  --header "Authorization:255c6...88111" \
  --header "Content-Type: application/json"\
  --data '{
    "S3AccessKeyId": "AKIAW...4YZEYUY",
    "S3SecretAccessKey": "gCA0U...pgiDX"
  }'

Retrieve the storage settings

Retrieve the storage settings of your current backup repository.

PARAMETERS
No parameters.

RESPONSE
Returns the Storage object if it has been successfully configured; otherwise, returns an error.

GET /api/v1/storage/settings

curl -L ".../api/v1/storage/settings"\
  --header "Authorization:255c6...88111"

The Storage status object

Attributes
Type enum
Possible enum values:

LOCAL for local disk
WINS for Windows network location
NAS for mounted network storage on Linux
S3 for Amazon S3
GOOGLE for Google Cloud storage
AZURE for Azure Blob storage
S3C for S3 compatible storage

Desc string
Description of the storage type.
Location string
Storage path or bucket name of cloud storage.
StorageTotal integer
The total storage space of the backup destination directory in bytes. Returns -1 for unlimited storage space of a cloud storage bucket.
StorageFree integer
The available storage space for the backup destination directory in bytes. Returns -1 for unlimited available storage space of a cloud storage bucket.
IndexPath string
Storage location of the local data index.
IndexTotal integer
The total storage space of the index directory in bytes.
IndexFree integer
The available storage space for the index directory in bytes.

The Storage status object

{
  "Type": "LOCAL",
  "Desc": "Local disk",
  "Location": "/var/cubebackup_data",
  "StorageTotal": 17167265792,
  "StorageFree": 15123443712,
  "IndexPath": "/opt/cubebackup/index",
  "IndexTotal": 17167265792,
  "IndexFree": 15123443712
}

Retrieve the storage status

Retrieve the storage status of your current backup repository.

PARAMETERS
No parameters.

RESPONSE
Returns the Storage status object; otherwise, returns an error.

GET /api/v1/storage/status

curl -L ".../api/v1/storage/status" \
  --header "Authorization:255c6...88111"

License

The license object represents the currently active license for your CubeBackup instance. It allows you to retrieve the license status to track usage, or activate a license code on your CubeBackup instance.

ENDPOINTS

GET /api/v1/license
GET /api/v1/license/display
POST /api/v1/license/activate

The License object

Attributes
Stat hash
The Stat object contains data associated with the CubeBackup license usage.
Stat.DomainCount number
The number of domains currently being protected in a CubeBackup instance.
Stat.UserCount number
The number of Google Workspace users in all domains.
Stat.ProtectedUserCount number
The number of users currently being backed up in all domains.
License hash
The License object contains data associated with the CubeBackup license status.
License.UUID string
The unique ID of a CubeBackup license subscription.
License.Code string
The license code.
License.Type enum
Possible enum values:

trial for the 14-day free trial version
normal for business and enterprise organizations
edu for educational and non-profit organizations
site for other types of organizations

License.Status enum
Possible enum values:

normal for an active CubeBackup license
disabled for a disabled CubeBackup license

License.Error string
Detailed error message for a disabled license, if any.
License.CreatedTime timestamp
When the subscription was created. Measured in seconds since the Unix epoch.
License.UpdatedTime timestamp
The last time the license information was updated with the CubeBackup license server. Measured in seconds since the Unix epoch.
License.DueTime timestamp
When the current subscription expires. Measured in seconds since the Unix epoch.
License.AccountNumber integer
Number of accounts in the current CubeBackup subscription.
License.ContactEmail string
Contact Email address for the CubeBackup subscription. All renewal notifications and invoices will be sent to this email address.
License.ContactName string
Name of the contact person for the CubeBackup subscription.
IsExpired boolean
Whether or not the current license has expired.
UpdateURL string
URL for the CubeBackup customer portal.
PurchaseURL string
URL for the pricing page for CubeBackup licenses.
TrialDaysLeft integer
The number of days left in a trial license.
DueDate string
The human-readable expiration date for the CubeBackup subscription.
CodeDisplay string
A string containing the formatted license code.

The License object

{
  "Stat": {
    "DomainCount": 1,
    "UserCount": 500,
    "ProtectedUserCount": 300
  },
  "License": {
    "UUID": "ly3vv...iah2g",
    "Code": "p4c8r...sy5cc",
    "Type": "edu",
    "Status": "normal",
    "Error": "",
    "CreatedTime": 1662425706,
    "UpdatedTime": 1665963900,
    "DueTime": 1665792000,
    "AccountNumber": 500,
    "ContactEmail": "[email protected]",
    "ContactName": "admin"
  },
  "IsExpired": true,
  "UpdateURL": "https://www.cubebackup.com/subscriptions/n1tqe...7v1lx",
  "PurchaseURL": "https://www.cubebackup.com/pricing",
  "TrialDaysLeft": 0,
  "DueDate": "Oct 15, 2023",
  "CodeDisplay": "P4C8R...SY5CC"
}

Retrieve the license status

Retrieve the current license status.

PARAMETERS
No parameters.

RESPONSE
Returns the License attribute of the License object; otherwise, returns an error.

GET /api/v1/license

curl -L ".../api/v1/license" \
  --header "Authorization:255c6...88111"

Retrieve the license usage

Retrieve the current license usage.

PARAMETERS
No parameters.

RESPONSE
Returns the License object; otherwise, returns an error.

GET /api/v1/license/display

curl -L ".../api/v1/license/display" \
  --header "Authorization:255c6...88111"

Activate a CubeBackup license

Activate a CubeBackup license.

PARAMETERS
Code required
A string containing the CubeBackup license code.

RESPONSE
Returns the License attribute of the License object if the license is successfully activated.
Or this call returns an error code with a detailed Message attribute in the response body if you provide an invalid license code or any other error occurs.

POST /api/v1/license/activate

curl -L \
  --request POST ".../api/v1/license/activate" \
  --header "Authorization:255c6...88111" \
  --data Code="P4Q9...DKCC"

Domains

The domain object represents a Google Workspace domain added to your CubeBackup instance. It allows you to add and update the domain as well as retrieve the backup status and summary.

Related guide:

ENDPOINTS

GET /api/v1/domains
POST /api/v1/domains
PATCH /api/v1/domains/{{domainName}}
GET /api/v1/domains/{{domainName}}/summary
GET /api/v1/domains/{{domainName}}/settings
PATCH /api/v1/domains/{{domainName}}/settings

The Domain object

Attributes
Name string
A Google Workspace domain name.
AdminEmail string
Email address of the Google Workspace domain admin.
TotalDataSize integer
The total data size of the domain data in bytes.
StorageSize integer
The size of the domain backup data in bytes.
IndexSize integer
The size of the domain data index in bytes.
Status enum
Possible enum values:

created: the domain has just been added to the domain list, and will not be displayed in the CubeBackup web console.
active: the domain has been activated and listed in the CubeBackup web console.

The Domain object

{
  "Name": "mydomain.com",
  "AdminEmail": "[email protected]",
  "TotalDataSize": 0,
  "StorageSize": 0,
  "IndexSize": 0,
  "Status": "created"
}

Add a domain

Add a Google Workspace domain to be backed up, and test on the access permissions of this domain.

NOTE: The domain will be added with created status. To proceed and manage the domain in the CubeBackup web console, please update the domain status to active.

PARAMETERS
DomainName required
Name of a valid Google Workspace domain.
AdminEmail required
Email address in the Google Workspace domain admin.

RESPONSE
Returns the Domain object if the domain is successfully added.
Or this call returns an error code with a detailed Message attribute in the response body if the permission testing fails or any other error occurs.

POST /api/v1/domains

curl -L \
  --request POST ".../api/v1/domains" \
  --header "Authorization:255c6...88111" \
  --data DomainName="mydomain.com" \
  --data AdminEmail="[email protected]"

Update a domain

Update the Google Workspace admin email address on file, or update the domain status.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

NOTE:
1. This API call will not test the access permissions for your CubeBackup instance. Please be careful when you input the new admin email address.
2. The domain will only be displayed in the CubeBackup web console when the status is active.

PARAMETERS
Status optional
The possible status value is either created or active.
AdminEmail optional
Email address of the Google Workspace domain admin.

RESPONSE
Returns the Domain object if the domain has been successfully updated.
Otherwise, returns an error with a detailed Message attribute in the response body.

PATCH /api/v1/domains/{{domainName}}

curl -L \
  --request PATCH ".../api/v1/domains/mydomain.com" \
  --header "Authorization:255c6...88111" \
  --data AdminEmail="[email protected]" \
  --data Status="active"

List all domains

Retrieve a list of all domains in a CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns an array of the Domain object.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains

curl -L ".../api/v1/domains" \
  --header "Authorization:255c6...88111"

The Domain summary object

Attributes
Name string
A Google Workspace domain name.
UserCount integer
Number of users in the domain.
UserBackupedCount integer
Number of users that are currently being backed up for the domain.
SharedDriveCount integer
Number of Shared drives in the domain.
SharedDriveBackupedCount integer
Number of Shared drives that are currently being backed up for the domain.
DriveIndexSize integer
Total size in bytes of the data index for Google Drive backups for the domain.
DriveStorageSize integer
Total size in bytes of the backup data for Google Drive backups for the domain.
GmailIndexSize integer
Total size in bytes of the data index for Gmail backups for the domain.
GmailStorageSize integer
Total size in bytes of the backup data for Gmail backups for the domain.
CalendarIndexSize integer
Total size in bytes of the data index for Google Calendar backups for the domain.
CalendarStorageSize integer
Total size in bytes of the backup data for Google Calendar backups for the domain.
ContactsIndexSize integer
Total size in bytes of the data index for Google Contacts backups for the domain.
ContactsStorageSize integer
Total size in bytes of the backup data for Google Contacts backups for the domain.
SitesIndexSize integer
Total size in bytes of the data index for Google Sites backups for the domain.
SitesStorageSize integer
Total size in bytes of the backup data for Google Sites backups for the domain.
SharedDriveIndexSize integer
Total size in bytes of the data index for Shared drive backups for the domain.
SharedDriveStorageSize integer
Total size in bytes of the backup data for Shared drive backups for the domain.

The Domain summary object

{
  "Name": "mydomain.com",
  "UserCount": 3,
  "UserBackupedCount": 3,
  "SharedDriveCount": 50,
  "SharedDriveBackupedCount": 50,
  "DriveIndexSize": 0,
  "DriveStorageSize": 0,
  "GmailIndexSize": 0,
  "GmailStorageSize": 0,
  "CalendarIndexSize": 0,
  "CalendarStorageSize": 0,
  "ContactsIndexSize": 0,
  "ContactsStorageSize": 0,
  "SitesIndexSize": 0,
  "SitesStorageSize": 0,
  "SharedDriveIndexSize": 0,
  "SharedDriveStorageSize": 0
}

Retrieve domain summary status

Retrieve the domain usage summary.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns the Domain summary object.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/summary

curl -L ".../api/v1/domains/mydomain.com/summary" \
  --header "Authorization:255c6...88111"

The Domain settings object

Attributes
Gmail hash
Gmail backup settings for the domain.
Gmail.Backup boolean
Whether or not backups are enabled for Gmail.
Drive hash
Google Drive backup settings for the domain.
Drive.Backup boolean
Whether or not backups are enabled for Google Drive.
Drive.BackupFilesSharedWithMe boolean
Whether or not the "Backup files shared with me" option is enabled.
Drive.DisableAutoBackupNewSharedDrive boolean
Whether or not CubeBackup automatically backs up newly created Shared drives.
Drive.ExcludeRule string
String representing the file exclusion rules for Google Drive backups.
Calendar hash
Google Calendar backup settings for the domain.
Calendar.Backup boolean
Whether or not backups are enabled for Google Calendar.
Contacts hash
Google Contacts backup settings for the domain.
Contacts.Backup boolean
Whether or not backups are enabled for Google Contacts.
Sites hash
Google Sites backup settings for the domain.
Sites.Backup boolean
Whether or not backups are enabled for Google Sites.
Backup hash
Domain backup settings.
Backup.DataRetentionMaxDays integer
Backup retention policy settings for this domain. 0 represents the default CubeBackup retention policy with unlimited versions. A positive integer represents the number of days for which the oldest version histories will be preserved.

The Domain settings object

{
  "Gmail": {
    "Backup": true
  },
  "Drive": {
    "Backup": true,
    "BackupFileSharedWithMe": false,
    "DisableAutoBackupNewSharedDrives": false,
    "ExcludeRule": "size>10GB"
  },
  "Calendar": {
    "Backup": true
  },
  "Contacts": {
    "Backup": true
  },
  "Sites": {
    "Backup": false
  },
  "Backup": {
    "DataRetentionMaxDays": 365
  }
}

Retrieve domain settings

Retrieve the domain backup settings.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns the Domain settings object.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/settings

curl -L ".../api/v1/domains/mydomain.com/settings" \
  --header "Authorization:255c6...88111"

Update domain settings

Update the domain backup settings.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

Please be sure to add the Content-Type: application/json header to this HTTP request.

PARAMETERS
The Domain settings object optional
Optional fields in the Domain settings object.

RESPONSE
Returns the Domain object if the domain is successfully updated.
Otherwise, returns an error with a detailed Message attribute in the response body.

PATCH /api/v1/domains/{{domainName}}/settings

curl -L \
  --request PATCH ".../api/v1/domains/mydomain.com/settings" \
  --header "Authorization:255c6...88111" \
  --header "Content-Type: application/json"\
  --data '{
    "Gmail": {
      "Backup": false
    },
    "Drive": {
      "BackupFileSharedWithMe": false,
      "DisableAutoBackupNewSharedDrives": false,
      "ExcludeRule": "size>10GB"
    }
  }'

Organization Units

The Organization Unit object represents an Organization Unit in your Google Workspace domain. It allows you to batch update the auto-backup status as well as retrieve the OU list for the domain.

ENDPOINTS

GET /api/v1/domains/{{domainName}}/ous
POST /api/v1/domains/{{domainName}}/ous/batch-update-auto-backup-status

The Organization Unit object

Attributes
Name string
Name of an Organization Unit.
Description string
An arbitrary string used to describe an Organization Unit.
AutoEnableBackup boolean
Whether or not new users in this Organization Unit are automatically backed up.
OrgUnitPath string
Full path for an Organization Unit.
ParentOrgUnitPath string
Full path for the parental unit of an Organization Unit.

The Organization Unit object

{
  "Name": "Financial",
  "Description": "",
  "AutoEnableBackup": true,
  "OrgUnitPath": "/Departments/Financial",
  "ParentOrgUnitPath": "/Departments"
}

List all Organization Units

Retrieve a list of all Organization Units in the domain.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns an array of the Organization Unit object.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/ous

curl -L ".../api/v1/domains/mydomain.com/ous" \
  --header "Authorization:255c6...88111"

Batch update OU auto-backup status

Update the auto-backup option of Organization Units in the domain.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

Please be sure to add the Content-Type: application/json header to this HTTP request.

PARAMETERS
EnabledUnitPaths optional
An array of the Organization Unit full paths to be enabled. DisabledUnitPaths optional
An array of the Organization Unit full paths to be disabled.

RESPONSE
Returns "OK" if the Organization Unit backup status has been successfully updated.
Otherwise, returns an error with a detailed Message attribute in the response body.

POST /api/v1/domains/{{domainName}}/ous/batch-update-auto-backup-status

curl -L \
  --request POST ".../api/v1/domains" \
  --header "Authorization:255c6...88111" \
  --header "Content-Type: application/json"\
  --data '{
    "EnabledUnitPaths":["/Department/OUa",...],
    "DisabledUnitPaths":["/Department/OUb",...]
  }'

Users

The user object represents a user in your Google Workspace. It allows you to batch update the backup status of multiple users, as well as retrieve the backup status summary for a specific user.

Related guide:

ENDPOINTS

GET /api/v1/domains/{{domainName}}/users
GET /api/v1/domains/{{domainName}}/users/{{userId}}
GET /api/v1/domains/{{domainName}}/users/{{userId}}/photo
POST /api/v1/domains/{{domainName}}/users/sync
POST /api/v1/domains/{{domainName}}/users/batch-update-backup-status

The User object

Attributes
Id string
ID of the Google Workspace user.
PrimaryEmail string
Primary email address of the Google Workspace user.
FullName string
Full name of the Google Workspace user.
OrgUnitPath string
Full path of the organization unit to which the user is assigned.
IsAdmin boolean
Whether or not the user has Google Workspace Super Admin privileges or not.
Suspended boolean
Whether or not a user is suspended in Google Workspace.
Deleted boolean
Whether or not a user has been deleted in Google Workspace.
TotalDataSize integer
Total size in bytes for backups for the user.
TotalStorageSize integer
Size in bytes of the backup data for the user.
TotalIndexSize integer
Size in bytes of the data index for the user.
DriveIndexSize integer
Size in bytes of the data index for Google Drive backups for the user.
DriveStorageSize integer
Size in bytes of the backup data for Google Drive backups for the user.
GmailIndexSize integer
Size in bytes of the data index for Gmail backups for the user.
GmailStorageSize integer
Size in bytes of the backup data for Gmail backups for the user.
CalendarIndexSize integer
Size in bytes of the data index for Google Calendar backups for the user.
CalendarStorageSize integer
Size in bytes of the backup data for Google Calendar backups for the user.
ContactsIndexSize integer
Size in bytes of the data index for Google Contacts backups for the user.
ContactsStorageSize integer
Size in bytes of the backup data for Google Contacts backups for the user.
SitesIndexSize integer
Size in bytes of the data index for Google Sites backups for the user.
SitesStorageSize integer
Size in bytes of the backup data for Google Sites backups in a user.
BackupEnabled boolean
Whether or not a user is part of the active backup set.

The User object

{
  "Id": "11386...68194",
  "PrimaryEmail": "[email protected]",
  "FullName": "user A",
  "OrgUnitPath": "/Departments/Financial",
  "IsAdmin": false,
  "Suspended": false,
  "Deleted": false,
  "TotalDataSize": 0,
  "TotalIndexSize": 0,
  "TotalStorageSize": 0,
  "DriveStorageSize": 0,
  "DriveIndexSize": 0,
  "GmailStorageSize": 0,
  "GmailIndexSize": 0,
  "CalendarStorageSize": 0,
  "CalendarIndexSize": 0,
  "ContactsStorageSize": 0,
  "ContactsIndexSize": 0,
  "SitesStorageSize": 0,
  "SitesIndexSize": 0,
  "BackupEnabled": true
}

List all users

Retrieve a list of all users in the domain.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS

The following parameters are optional and should be added as URL queries in this API call.

IncludeDeleted optional boolean
Whether or not to include deleted users in the list. Set to false by default.
IncludeSuspended optional boolean
Whether or not to include suspended users in the list. Set to false by default.
IncludeArchived optional boolean
Whether or not to include archived users in the list. Set to false by default.

RESPONSE
Returns an array of the User object.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/users

curl -L ".../api/v1/domains/mydomain.com/users?IncludeDeleted=true&IncludeSuspended=true&IncludeArchived=true" \
  --header "Authorization:255c6...88111"

Retrieve user details

Retrieves the details for a user. Supply the unique {{userId}} that was returned from your previous request, and CubeBackup will return the corresponding user information and backup status.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns the User object.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/users/{{userId}}

curl -L ".../api/v1/domains/mydomain.com/users/11386...68194" \
  --header "Authorization:255c6...88111"

Retrieve user photo

Retrieves the Google profile photo for the user. Supply the unique {{userId}} that was returned from your previous request, and CubeBackup will return the corresponding user profile photo.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns the user profile photo in PNG format.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/users/{{userId}}/photo

curl -L ".../api/v1/domains/mydomain.com/users/11386...68194/photo" \
  --header "Authorization:255c6...88111"

Sync user list with Google

Update the user list to sync the latest changes from Google Workspace for the domain into your CubeBackup instance.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns "OK" if the user list is successfully updated.
Otherwise, returns an error with a detailed Message attribute in the response body.

POST /api/v1/domains/{{domainName}}/users/sync

curl -L \
  --request POST ".../api/v1/domains/mydomain.com/users/sync" \
  --header "Authorization:255c6...88111"

Batch update user backup status

Include or exclude a list of users from the backup for the domain.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

Please be sure to add the Content-Type: application/json header to this HTTP request.

You can also update the user backup status using a list of email addresses in CSV format. A sample Python script can be found in our Git repository .

PARAMETERS
EnabledUserIds optional
An array of the user IDs to be enabled.
DisabledUserIds optional
An array of the user IDs to be disabled.

RESPONSE
Returns "OK" if the user backup status is successfully updated.
Otherwise, returns an error.

POST /api/v1/domains/{{domainName}}/users/batch-update-backup-status

curl -L \
  --request POST ".../api/v1/domains/mydomain.com/users/batch-update-backup-status" \
  --header "Authorization:255c6...88111" \
  --header "Content-Type: application/json"\
  --data '{
    "EnabledUserIds":["11386...68194",...],
    "DisabledUserIds":["18326...42981",...]
  }'

Shared drives

The Shared drive object represents a Shared drive in your Google Workspace for the domain. It allows you to batch update the backup status of multiple Shared drives or retrieve the backup status summary for a specific Shared drive.

Related guide:

ENDPOINTS

GET /api/v1/domains/{{domainName}}/shareddrives
GET /api/v1/domains/{{domainName}}/shareddrives/{{sharedDriveId}}
POST /api/v1/domains/{{domainName}}/shareddrives/sync
POST /api/v1/domains/{{domainName}}/shareddrives/batch-update-backup-status

The Shared drive object

Attributes
Id string
Unique ID of a Google Workspace Shared drive.
Name string
Name of a Google Workspace Shared drive.
BackgroundImageLink string
The publicly accessible URL of the Shared drive background image.
TotalDataSize integer
Total size in bytes for backups for the Shared drive.
IndexSize integer
Size in bytes of the data index for the Shared drive.
StorageSize integer
Size in bytes of the backup data for the Shared drive.
Deleted boolean
Whether or not the Shared drive has been deleted in Google Workspace.
BackupEnabled boolean
Whether or not the Shared drive is part of the active backup list.

The Shared drive object

{
  "Id": "0ANE...9PVA",
  "Name": "MySharedDrive",
  "BackgroundImageLink": "https://ssl.gstatic.com/...jpg",
  "TotalDataSize": 0,
  "IndexSize": 0,
  "StorageSize": 0,
  "Deleted": false,
  "BackupEnabled": true
}

List all Shared drives

Retrieve a list of all Shared drives in the domain.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS

The following parameters are optional and should be added as URL queries in this API call.

IncludeDeleted optional boolean
Whether or not to include deleted Shared drives in the list. Set to false by default.

RESPONSE
Returns an array of the Shared drive object.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/shareddrives

curl -L ".../api/v1/domains/mydomain.com/shareddrives?includeDeleted=true" \
  --header "Authorization:255c6...88111"

Retrieve Shared drive details

Retrieves the details for a Shared drive. Supply the unique {{sharedDriveId}} that was returned from your previous request, and CubeBackup will return the corresponding Shared drive information and backup status.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns the Shared drive object.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/shareddrives/{{sharedDriveId}}

curl -L ".../api/v1/domains/mydomain.com/shareddrives/0ANE...9PVA" \
  --header "Authorization:0ANEw...k9PVA"

Sync Shared drive list with Google

Update the Shared drive list to sync the latest changes from Google Workspace for the domain into your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns "OK" if the Shared drive list is successfully updated.
Otherwise, returns an error with a detailed Message attribute in the response body.

POST /api/v1/domains/{{domainName}}/shareddrives/sync

curl -L \
  --request POST ".../api/v1/domains/mydomain.com/shareddrives/sync" \
  --header "Authorization:255c6...88111"

Batch update Shared drive backup status

Include or exclude a list of Shared drives from the backup for the domain.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

Please be sure to add the Content-Type: application/json header to this HTTP request.

PARAMETERS
EnabledSharedDriveIds optional
An array of Shared drive IDs to be enabled.
DisabledSharedDriveIds optional
An array of Shared drive IDs to be disabled.

RESPONSE
Returns "OK" if the Shared drive backup status is successfully updated.
Otherwise, returns an error.

POST /api/v1/domains/{{domainName}}/shareddrives/batch-update-backup-status

curl -L \
  --request POST ".../api/v1/domains/mydomain.com/shareddrives/batch-update-backup-status" \
  --header "Authorization:255c6...88111" \
  --header "Content-Type: application/json" \
  --data '{
    "EnabledSharedDriveIds":["0ANM...9PVA",...],
    "DisabledSharedDriveIds":["03VE...AEV1",...]
  }'

Backup

The Backup object represent the backup status and settings for one domain, and can also help automate backup management by allowing you to trigger or stop a backup process on demand.

Related guide:

ENDPOINTS

GET /api/v1/domains/{{domainName}}/backup/status
POST /api/v1/domains/{{domainName}}/backup/start
POST /api/v1/domains/{{domainName}}/backup/cancel
GET /api/v1/domains/{{domainName}}/backup/tasks
GET /api/v1/domains/{{domainName}}/backup/tasks.csv
GET /api/v1/domains/{{domainName}}/backup/tasks/{{BackupId}}/errors
GET /api/v1/domains/{{domainName}}/backup/tasks/{{BackupId}}/errors.csv

The backup status object

Attributes
Status enum
The current backup status of the domain.
Possible enum values:

notask: No ongoing backup process.
doing: A backup process is currently underway.

RXBandwidth integer
The current download speed in bps of the CubeBackup service from Google's servers.
TXBandwidth integer
The current upload speed in bps of the CubeBackup service to cloud storage. This attribute is not returned for local storage.
NextBackupStartIn integer
Time in seconds until the next automatic backup will start. This attribute is only returned if the Status is notask. CompletedSharedDriveCount integer
The number of Shared drives which have been successfully completed in the currently running backup job.
CompletedUserCount integer
The number of users which have been successfully completed in the currently running backup job.
SharedDriveCount number
The number of Shared drives in the active backup list.
UserCount number
The number of users in the active backup list.
Detail array of ongoing backup status for each user / Shared drive
List of objects currently being backed up with up-to-date backup progress details.
Detail.Id string
ID of the user or Shared drive currently being backed up.
Detail.DisplayName string
Name of the user or Shared drive currently being backed up.
Detail.GmailItem string
Subject of the Gmail message currently being backed up.
Detail.DriveItem string
Name of the Drive file currently being backed up.
Detail.CalendarItem string
Name of the Calendar event currently being backed up.
Detail.ContactsItem string
Name of the contact currently being backed up.
Detail.SitesItem string
Name of the Sites file currently being backed up.

The backup status object

{
  "Status": "doing",
  "RXBandwidth": 1048660,
  "TXBandwidth": 883,
  "CompletedSharedDriveCount": 6,
  "CompletedUserCount": 0,
  "UserCount": 0,
  "SharedDriveCount": 6,
  "Detail": [
     {
       "Id": "[email protected]",
       "DisplayName": "[email protected]",
       "GmailItem": "Done",
       "DriveItem": "GoogleSpreadsheet",
       "CalendarItem": "Done",
       "ContactsItem": "-",
       "SitesItem": "-"
     },
    {
       "Id": "[email protected]",
       "DisplayName": "[email protected]",
       "GmailItem": "Email from admin",
       "DriveItem": "Movie",
       "CalendarItem": "Done",
       "ContactsItem": "-",
       "SitesItem": "-"
     },
  ]
}

Retrieve the current backup task status

Retrieve the status of the ongoing backup process, or the scheduled time of the next backup for the domain.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns the backup status object.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/backup/status

curl -L ".../api/v1/domains/mydomain.com/backup/status" \
  --header "Authorization:255c6...88111"

Start a backup

Trigger a backup event for the domain.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns "OK" if the backup successfully starts or there is already an ongoing backup process.
Otherwise, returns an error with a detailed Message attribute in the response body.

POST /api/v1/domains/{{domainName}}/backup/start

curl -L \
  --request POST ".../api/v1/domains/mydomain.com/backup/start" \
  --header "Authorization:255c6...88111"

Stop a backup

Stop the current backup process for the domain.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns "OK" if the backup stops or there is no ongoing backup process.
Otherwise, returns an error with a detailed Message attribute in the response body.

POST /api/v1/domains/{{domainName}}/backup/cancel

curl -L \
  --request POST ".../api/v1/domains/mydomain.com/backup/cancel" \
  --header "Authorization:255c6...88111"

The backup event object

Attributes
Id string
ID of the backup event.
StartTime timestamp
Backup start time. Measured in seconds since the Unix epoch.
Duration number
Backup duration in seconds.
Status enum
The status of the backup event.
Possible enum values:

success: The backup event completed successfully.
finishedWithErrors: The backup event finished with errors.
failed: The backup event failed with errors.
canceled: The backup event was canceled.

UserCount number
The number of users in the backup.
CompletedUserCount number
The number of users which were successfully backed up.
SharedDriveCount number
The number of Shared drives in the backup.
CompletedSharedDriveCount number
The number of Shared drives which were successfully backed up.
MailCount number
The number of Gmail messages backed up in the backup event.
MailTotalSize number
The Gmail backup size in bytes for the backup event.
DriveFileCount number
The number of Google Drive files backed up in the backup event.
DriveTotalSize number
The Google Drive backup size in bytes for the backup event.
CalendarEventsCount number
The number of Google Calendar events backed up in the backup event.
CalendarTotalSize number
The Google Calendar backup size in bytes for the backup event.
ContactsCount number
The number of contacts backed up in the backup event.
ContactsTotalSize number
The Google Contacts backup size in bytes for the backup event.
SitesFileCount number
The number of Google Sites files backed up in the backup event.
SitesTotalSize number
The Google Sites backup size in bytes for the backup event.
TotalFileCount number
The total number of items backed up in the backup event.
TotalFileSize number
The total backup size in bytes for the backup event.
ErrorCount number
The number of errors for the backup event.

The backup event object

{
  "Id": 43,
  "StartTime": 1665735604,
  "Duration": 6,
  "Status": "success",
  "UserCount": 0,
  "CompletedUserCount": 0,
  "SharedDriveCount": 0,
  "CompletedSharedDriveCount": 0,
  "DriveFileCount": 0,
  "DriveTotalSize": 0,
  "MailCount": 0,
  "MailTotalSize": 0,
  "CalendarEventsCount": 0,
  "CalendarTotalSize": 0,
  "ContactsCount": 0,
  "ContactsTotalSize": 0,
  "SitesFileCount": 0,
  "SitesTotalSize": 0,
  "TotalFileCount": 0,
  "TotalFileSize": 0,
  "ErrorCount": 0
}

Retrieve the backup history

Retrieve a list of backup histories for the domain.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS

The following parameters are optional and should be added as URL queries in this API call.

FailedOnly optional boolean
Whether or not to only retrieve failed backup events in the response. Set to false by default.
StartDate optional timestamp
Time of the earliest backup event to be retrieved. Measured in seconds since the Unix epoch.
EndDate optional timestamp
Time of the latest backup event to be retrieved. Measured in seconds since the Unix epoch.
Limit optional
The number of objects to be displayed on a single page in the response. Set to 20 by default.
PageNum optional
The current page number to display out of the total result list. Set to 1 by default.
SortBy optional
Return the backup history sorted by the specific attribute. Set to StartTime by default.
Possible enum values:

StartTime: Sort the backup events by start time.
Duration: Sort the backup events by duration.
ErrorCount: Sort the backup events by number of errors.
MailTotalSize: Sort the backup events by total backup size for Gmail.
DriveTotalSize: Sort the backup events by total backup size for Google Drive.
CalendarTotalSize: Sort the backup events by total backup size for Google Calendar.
ContactsTotalSize: Sort the backup events by total backup size for Google Contacts.
SitesTotalSize: Sort the backup events by total backup size for Google Sites.
TotalFileSize: Sort the backup events by total backup size.

SortOrder optional
Define whether the list should be sorted in ascending or descending order. Set to desc by default.
Possible enum values:

asc: Return the backup event list in ascending order.
desc: Return the backup event list in descending order.

GET /api/v1/domains/{{domainName}}/backup/tasks

curl -L ".../api/v1/domains/myDomain.com/backup/tasks?FailedOnly=true" \
  --header "Authorization:255c6...88111"

RESPONSE
Returns a dictionary with a List property that contains a sorted array of backup event objects, using pages containing up to Limit number of objects, beginning at page PageNum. The total number of matching backup events is returned in the ItemCount property.
Otherwise, returns an error with a detailed Message attribute in the response body.

EXAMPLE

{
  "ItemCount": 43,
  "PageNum": 1,
  "Limit": 20,
  "List": [
    {
    "Id": 43,
    "StartTime": 1665735604,
    "Duration": 6,
    "Status": "success"
    ...
    },
    ...
  ]
}

Retrieve backup history in CSV format

Retrieve a list of backup histories for the domain in CSV format.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS

The following parameters are optional and should be added as URL queries in this API call.

FailedOnly optional boolean
Whether or not to only retrieve failed backup events in the response. Set to false by default.
StartDate optional timestamp
Time of the earliest backup event to be retrieved. Measured in seconds since the Unix epoch.
EndDate optional timestamp
Time of the latest backup event to be retrieved. Measured in seconds since the Unix epoch.

RESPONSE
Returns a CSV file containing a filtered array of backup event objects.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/backup/tasks.csv

curl -L ".../api/v1/domains/myDomain.com/backup/tasks.csv?FailedOnly=true&StartDate=0&EndDate=16...93"
  --header "Authorization:255c6...88111"

The backup error object

Attributes
Id string
The unique ID of this error.
BackupId string
The ID of the backup event.
OwnerId string
The unique ID of a Google Workspace user or Shared drive which is the owner of the item being processed when the error occurred.
OwnerType enum
Whether the error occurred when backing up an item for a user or Shared drive.
Possible enum values:

user: User
shareddrive: Shared drive

OwnerName string
The name of the user or Shared drive.
App enum
The application type for which this backup error occurred.

common: A general service error.
drive: Google Drive backup error.
gmail: Gmail backup error.
contact: Google Contacts backup error.
calendar: Google Calendar backup error.
site: Google Sites backup error.

HttpCode number
The HTTP code returned from the CubeBackup server.
Message string
The error message.
Detail string
A human-readable message providing more details about the error.
CreatedTime timestamp
Time the error occurred. Measured in seconds since the Unix epoch.

The backup error object

{
  "Id": 6,
  "BackupId": 6,
  "OwnerId": "",
  "OwnerType": "",
  "OwnerName": "",
  "App": "common",
  "HttpCode": 0,
  "Message": "ListGSuiteDomainsByAdminEmail(...) failed:": \"Not a valid email or user ID.\"\n}",
  "Detail": "loadAllDomains() failed",
  "CreatedTime": 1665643332
}

Retrieve backup event errors

Retrieve details of a backup event error. Supply the unique {{BackupId}} that was returned from your previous request, and CubeBackup will return the error details for a failed event or finishedWithErrors event.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS

The following parameters are optional and should be added as URL queries in this API call.

Limit optional
The number of objects to be displayed on a single page in the response. Set to 20 by default.
PageNum optional
The current page number to display out of the total result list. Set to 1 by default.

GET /api/v1/domains/{{domainName}}/backup/tasks/{{BackupId}}/errors

curl -L ".../api/v1/domains/myDomain.com/backup/tasks/6/errors?Limit=20&PageNum=2" \
  --header "Authorization:255c6...88111"

RESPONSE
Returns a dictionary with a List property that contains an array of backup error objects, using pages containing up to Limit number of objects, beginning at page PageNum. The total number of backup errors is returned in the ItemCount property.
Otherwise, returns an error with a detailed Message attribute in the response body.

EXAMPLE

{
  "ItemCount": 3,
  "PageNum": 1,
  "Limit": 20,
  "List": [
    {
    "Id": 6,
    "App": "common",
    "HttpCode": 0,
    "Message": "ListGSuiteDomainsByAdminEmail([email protected]) failed:Get ... "Not a valid email or user ID.\"\n}",
    "Detail": "loadAllDomains() failed",
    ...
    },
    ...
  ]
}

Retrieve backup errors in CSV format

Retrieve error details for the backup event in CSV format. Supply the unique {{BackupId}} that was returned from your previous request, and CubeBackup will return the error details for a failed event or finishedWithErrors event.

Please replace the {{domainName}} in the URL with a valid domain name that was previously added to your CubeBackup instance.

PARAMETERS
No parameters.

RESPONSE
Returns a CSV file containing an array of backup error objects.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/domains/{{domainName}}/backup/tasks/{{BackupId}}/errors.csv

curl -L ".../api/v1/domains/myDomain.com/backup/tasks/6/errors.csv" \
  --header "Authorization:255c6...88111"

System

The System settings object represents the global settings for all domains in your CubeBackup instance. It allows you to retrieve the current system settings, as well as update the backup interval, throttle settings, and backup email report settings.

The audit log object captures detailed information about specific events within the system. It is designed to help administrators monitor and trace actions for auditing and troubleshooting purposes.

ENDPOINTS

GET /api/v1/system/settings
PATCH /api/v1/system/settings
GET /api/v1/system/auditlogs
GET /api/v1/system/auditlogs.csv

The System settings object

Attributes

- Throttling settings
NetworkBandwidthLimitWorkHoursEnabled boolean
Whether or not to enable throttling during work hours.
NetworkBandwidthLimitWorkHoursRate integer
Throttle CubeBackup to this speed in Mbps during work hours.
NetworkBandwidthLimitNonWorkHoursEnabled boolean
Whether or not to enable throttling during non-work hours.
NetworkBandwidthLimitNonWorkHoursRate integer
Throttle CubeBackup to this speed in Mbps during non-work hours.
NetworkBandwidthLimitWorkHoursBegin integer
Start time for work hours in 24-hour format.
NetworkBandwidthLimitWorkHoursEnd integer
End time for work hours in 24-hour format.
NetworkBandwidthLimitDay array of integer values
Days of the week when work hour throttling will be applied.(Sunday = 0, Monday = 1)

- Email reports settings
SummaryEmailNotificationFrequency enum
Frequency of CubeBackup email reports.
Possible enum values:

0: Disable email reports
1: Daily email reports
2: Weekly email reports
3: Monthly email reports

SummaryEmailReceiver string
A list of email addresses to receive CubeBackup email reports. Separate multiple email addresses with commas.
SmtpEnabled boolean
Whether or not to enable the custom SMTP settings.
SmtpHost string
Custom SMTP host address.
SmtpPort integer
Custom SMTP host port number.
SmtpFrom string
Email address listed as sender for the custom SMTP service.
SmtpUsername string
Username for the custom SMTP service.
SmtpPassword string
Password for the custom SMTP service.
SmtpSkipVerifyTLS boolean
Whether or not to skip TLS verification for the SMTP server. Set to false by default.

- Backup interval settings
BackupInterval integer
Interval between scheduled backups in minutes. Set to 60 by default.

The System settings object

{
  "NetworkBandwidthLimitWorkHoursEnabled": true,
  "NetworkBandwidthLimitWorkHoursRate": 50,
  "NetworkBandwidthLimitNonWorkHoursEnabled": false,
  "NetworkBandwidthLimitNonWorkHoursRate": 300,
  "NetworkBandwidthLimitWorkHoursBegin": 9,
  "NetworkBandwidthLimitWorkHoursEnd": 17,
  "NetworkBandwidthLimitDays": [1,2,3,4,5],
  "SummaryEmailNotificationFrequency": 2,
  "SummaryEmailReceiver": "[email protected]",
  "SmtpEnabled": true,
  "SmtpHost": "smtp-relay.gmail.com",
  "SmtpPort": 587,
  "SmtpFrom": "[email protected]",
  "SmtpUsername": "[email protected]",
  "SmtpPassword": "",
  "SmtpSkipVerifyTLS": false,
  "BackupInterval": 60
}

Retrieve the current system settings

Retrieve the CubeBackup system settings.

PARAMETERS
No parameters.

RESPONSE
Returns the System settings object.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/system/settings

curl -L ".../api/v1/system/settings" \
  --header "Authorization:255c6...88111"

Update the system settings

Update the CubeBackup system settings.

Please be sure to add the Content-Type: application/json header to this HTTP request.

PARAMETERS
The System settings object optional
Optional fields in the System settings object.

RESPONSE
Returns the System settings object if the system settings have been successfully updated.
Otherwise, returns an error with a detailed Message attribute in the response body.

curl -L \
  --request PATCH ".../api/v1/system/settings" \
  --header "Authorization:255c6...88111" \
  --header "Content-Type: application/json"\
  --data '{
    "SummaryEmailNotificationFrequency": 2,
    "SummaryEmailReceiver": "[email protected]",
    "BackupInterval": 120
  }'

The audit log object

Attributes
Id number
ID of the audit log entry`.
CreatedTime timestamp
Timestamp indicating when the event was created. Measured in seconds since the Unix epoch.
Desc string
A description string for the event.
Domain string
Domain name where the event occurred. The field is empty for global events.
Op string
Email address of the operator responsible for the event.
NewValue string
The new value after a modification, if applicable.
OldValue string
The previous value before the modification, if applicable.
Event enum
Type of event that occurred in the audit log.
Possible enum values:

1: Login.
2: Change password.
3: Manual backup.
4: Stop backup.
5: Restore.
6: Abort restore.
7: Export.
8: Abort export.
9: Download.
10: Edit domain settings.
11: Edit system settings.
12: Create account.
13: Edit account.
14: Delete account.
15: Upgrade.
16: Migrate data.
17: Abort migration.
18: Edit user settings.
19: Edit organization settings.
20: Edit shared drive settings.
21: Edit storage configuration.
22: Add domain.

The audit log object

{
  "Id" = 1688,
  "CreatedTime" = 1713171593,
  "Desc" = "Login from 192.***.***.182.",
  "Domain" = "",
  "Op" = "c:[email protected]"
  "NewValue" = "",
  "OldValue" = "",
  "Event" = 1,
}

Retrieve the audit logs

Retrieve a list of audit logs for the CubeBackup instance.

PARAMETERS

The following parameters are optional and should be added as URL queries in this API call.

DomainName optional string
Domain name where the event occurred.
Operator optional string
Email address of the operator responsible for the event.
EventType optional number
Type of event that occurred.
StartDate optional timestamp
Time of the earliest event to be retrieved. Measured in seconds since the Unix epoch.
EndDate optional timestamp
Time of the latest event to be retrieved. Measured in seconds since the Unix epoch.
Limit optional
The number of objects to be displayed on a single page in the response. Set to 20 by default.
PageNum optional
The current page number to display out of the total result list. Set to 1 by default.
SortBy optional
Return the audit logs sorted by the specific attribute. Set to CreatedTime by default.
Possible enum values:

CreatedTime: Sort the events by created time.

SortOrder optional
Define whether the list should be sorted in ascending or descending order. Set to desc by default.
Possible enum values:

asc: Return the audit logs in ascending order.
desc: Return the audit logs in descending order.

GET /api/v1/system/auditlogs

curl -L ".../api/v1/auditlogs/tasks?StartDate=0&EndDate=17..." \
  --header "Authorization:255c6...88111"

RESPONSE
Returns a dictionary with a List property that contains a sorted array of audit log objects, using pages containing up to Limit number of objects, beginning at page PageNum. The total number of matching audit logs is returned in the ItemCount property.
Otherwise, returns an error with a detailed Message attribute in the response body.

EXAMPLE

{
  "ItemCount": 43,
  "PageNum": 1,
  "Limit": 20,
  "List": [
    {
    "Id": 43,
    "CreatedTime": 1665735604,
    "Desc": "Login from 192.***.***.182.",
    "Domain": ""
    ...
    },
    ...
  ]
}

Retrieve audit logs in CSV format

Retrieve a list of audit logs in CSV format.

PARAMETERS

The following parameters are optional and should be added as URL queries in this API call.

DomainName optional string
Domain name where the event occurred.
Operator optional string
Email address of the operator responsible for the event.
EventType optional number
Type of event that occurred.
StartDate optional timestamp
Time of the earliest event to be retrieved. Measured in seconds since the Unix epoch.
EndDate optional timestamp
Time of the latest event to be retrieved. Measured in seconds since the Unix epoch.
SortBy optional
Return the audit logs sorted by the specific attribute. Set to CreatedTime by default.
Possible enum values:

CreatedTime: Sort the events by created time.

SortOrder optional
Define whether the list should be sorted in ascending or descending order. Set to desc by default.
Possible enum values:

asc: Return the audit logs in ascending order.
desc: Return the audit logs in descending order.

RESPONSE
Returns a CSV file containing a filtered array of audit log objects.
Otherwise, returns an error with a detailed Message attribute in the response body.

GET /api/v1/system/auditlogs.csv

curl -L ".../api/v1/system/auditlogs.csv?StartDate=0&EndDate=16...93"
  --header "Authorization:255c6...88111"

Admins

CubeBackup administrators can be created with different roles and granular access levels to manage the backups and other settings of CubeBackup. You can create, manage and delete CubeBackup administrators programmatically using the API.

ENDPOINTS

GET /api/v1/system/admins
POST /api/v1/system/admins
PATCH /api/v1/system/admins/{{adminId}}
DELETE /api/v1/system/admins/{{adminId}}

The CubeBackup admin object

Attributes
Id integer
ID of the CubeBackup admin
Name string
Name of the CubeBackup admin
Email string
Email address of the CubeBackup admin
Role enum
A CubeBackup admin is granted granular level permissions according to the the assigned CubeBackup Role .
Possible enum values:

cubeSuperAdmin: System admin
cubeDomainAdmin: Domain admin
cubeDomainOperator: Domain operator

Comment string
An arbitrary description string for the CubeBackup administrator.
Domains string
A list of domains that the admin can access. Multiple domains should be separated by commas.
Status enum
The current status of the CubeBackup admin.
Possible enum values:

0: Normal
1: Disabled

The CubeBackup admin object

{
  "Id": 10,
  "Name": "Cube Admin",
  "Email": "[email protected]",
  "Role": "cubeDomainAdmin",
  "Comment": "My CubeBackup domain admin",
  "Domains": "domain.com, subdomain.com",
  "Status": 0
}

List all CubeBackup admins

Retrieve a list of CubeBackup administrators.

PARAMETERS

The following parameters are optional and should be added as URL queries in this API call.

Limit optional
The number of admin objects to be displayed on a single page in the response. Set to 20 by default.
PageNum optional
The current page number to display out of the total result list. Set to 1 by default.

GET /api/v1/system/admins

curl -L ".../api/v1/system/admins?Limit=20&PageNum=1" \
  --header "Authorization:255c6...88111"

RESPONSE
Returns a dictionary with a List property that contains an array of CubeBackup admin objects, using pages containing up to Limit number of objects, beginning at page PageNum. The total number of CubeBackup admins is returned in the ItemCount property.
Otherwise, returns an error with a detailed Message attribute in the response body.

EXAMPLE

{
  "ItemCount": 6,
  "PageNum": 1,
  "Limit": 10,
  "List": [
    {
      "Id": 6,
      "Name": "My domain operator",
      "Email": "[email protected]",
      "Role": "cubeDomainOperator",
      "Comment": "test operator",
      "Domains": "testdomain.com",
      "Status": 0
    },
    ...
  ]
}

Create a CubeBackup administrator

Create an administrator for the CubeBackup web console.

Please be sure to add the Content-Type: application/json header to this HTTP request.

PARAMETERS
Name required
Name of the new CubeBackup admin.
Email required
Email address of the new CubeBackup admin.
Password required
Password for the new CubeBackup admin.
Role required
A CubeBackup admin is granted granular level permissions according to the assigned CubeBackup Role .
Possible enum values:

cubeSuperAdmin: CubeBackup System admin.
cubeDomainAdmin: CubeBackup Domain admin.
cubeDomainOperator: CubeBackup Domain operator.

Comment optional
An arbitrary description string for the CubeBackup administrator.
Domains optional
A list of domains that the admin can access. Multiple domains are separated by commas. This field is required for Domain admin and Domain operator.

RESPONSE
Returns the CubeBackup admin object if the admin has been successfully created.
Otherwise, returns an error with a detailed Message attribute in the response body.

POST /api/v1/system/admins

curl -L \
  --request POST ".../api/v1/system/admins" \
  --header "Authorization:255c6...88111" \
  --data Name="Sample Admin" \
  --data Email="[email protected]" \
  --data Password="myPassword" \
  --data Role="cubeDomainAdmin" \
  --data Comment="admin comment" \
  --data Domains="mydomain.com, mydomain2.com"

Update an administrator

Update the settings for CubeBackup administrator. Supply the unique {{adminId}} that was returned from your previous request, and set the updated values of the parameters passed.

PARAMETERS
Name optional
Updated name of the CubeBackup admin.
Email optional
Updated email address of the CubeBackup admin.
Password optional
Updated password for the CubeBackup admin.
Status optional
The possible status value is either 0 or 1.
Possible enum values:

0: Normal.
1: Disabled.

Role optional
A CubeBackup admin is granted granular level permissions according to the assigned CubeBackup Role .
Possible enum values:

cubeSuperAdmin: CubeBackup System admin.
cubeDomainAdmin: CubeBackup Domain admin.
cubeDomainOperator: CubeBackup Domain operator.

Comment optional
An arbitrary description string for the CubeBackup administrator.
Domains optional
A list of domains that the admin can access. Multiple domains are separated by commas.

RESPONSE
Returns "OK" if the CubeBackup admin has been successfully updated.
Otherwise, returns an error with a detailed Message attribute in the response body.

PATCH /api/v1/system/admins/{{adminId}}

curl -L \
  --request PATCH ".../api/v1/system/admins" \
  --header "Authorization:255c6...88111" \
  --data Password="myPassword" \
  --data Status=1 \
  --data Domains="mydomain.com, newDomain.com"

Delete an administrator

You can delete a CubeBackup admin using the API. Supply the unique {{adminId}} that was returned from your previous request, and CubeBackup will delete the admin and revoke the permissions of corresponding API clients.

Please note that the deletion is PERMANENT and the administrator cannot be re-enabled. To temporarily disable a CubeBackup admin, please use the Update an administrator API.

PARAMETERS
No parameters.

RESPONSE
Returns "OK" if the CubeBackup admin has been successfully deleted.
Otherwise, returns an error with a detailed Message attribute in the response body.

DELETE /api/v1/system/admins/{{adminId}}

curl -L \
  --request DELETE ".../api/v1/system/admins/5" \
  --header "Authorization:255c6...88111"

Keep track of API requests

All POST/PATCH requests after the initial setup are continually recorded in CubeBackup's immutable audit log, along with the API client name, the time the action occurred, and a detailed description of the affected object. You can view the audit log by logging in to the CubeBackup for Google Workspace web console as a system admin, and navigating to the SETTINGS > Audit Log page. You may search by the specific API client name or operation type, and even export the results as a CSV file.

USE CASES

The CubeBackup for Google Workspace APIs can be used by administrators to initiate, manage and monitor their backups programmatically. The following articles may provide insight on how to integrate CubeBackup with other systems and combine multiple requests to handle individual use cases:

In This Guide:

Need more help?

CubeBackup API Reference

INTRODUCTION

AUTHENTICATION

Step 1. Enable the API feature on your CubeBackup instance

Step 2. Create an API client

Step 3. Authenticate requests with API key

Step 4. Manage your API clients

Step 5. Keep your API keys safe

ERRORS

CORE RESOURCES

Setup

Retrieve the setup status

Create a system admin during initial setup

The Service account object

Upload a service account

Retrieve the current service account

Storage

The Storage object

Create the backup storage

Update the storage settings

Retrieve the storage settings

The Storage status object

Retrieve the storage status

License

The License object

Retrieve the license status

Retrieve the license usage

Activate a CubeBackup license

Domains

The Domain object

Add a domain

Update a domain

List all domains

The Domain summary object

Retrieve domain summary status

The Domain settings object

Retrieve domain settings

Update domain settings

Organization Units

The Organization Unit object

List all Organization Units

Batch update OU auto-backup status

Users

The User object

List all users

Retrieve user details

Retrieve user photo

Sync user list with Google

Batch update user backup status

Shared drives

The Shared drive object

List all Shared drives

Retrieve Shared drive details

Sync Shared drive list with Google

Batch update Shared drive backup status

Backup

The backup status object

Retrieve the current backup task status

Start a backup

Stop a backup

The backup event object

Retrieve the backup history

Retrieve backup history in CSV format

The backup error object

Retrieve backup event errors

Retrieve backup errors in CSV format

System

The System settings object

Retrieve the current system settings

Update the system settings

The audit log object

Retrieve the audit logs

Retrieve audit logs in CSV format

Admins

The CubeBackup admin object

List all CubeBackup admins

Create a CubeBackup administrator

Update an administrator