POST /backup_and_restore/backups

Submits a request to the Backup and Restore Engine to create a new backup.

To check the status of a backup please use the following endpoint: /api/backup_and_restore/backups/{id}

Table 1. POST /backup_and_restore/backups resource details
MIME Type

application/json

Table 2. POST /backup_and_restore/backups request parameter details
Parameter Type Optionality Data Type MIME Type Description

backup_type

header

Required

String

text/plain

Required. The desired type of backup (CONFIG or DATA).

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.
Table 3. POST /backup_and_restore/backups request body details
Parameter Data Type MIME Type Description Sample

backup

Object

application/json
Required. A single backup object has the following modifiable fields:
  • name - Required - String - The name of the backup.
  • configuration_id - Required - Long - The ID of the configuration. Must be the ID of a deployed backup configuration. For more information, see the following Backup Configuration API:
    • api/config/backup_and_restore/scheduled_backup_configurations
  • description - Optional - String - An optional description for the backup.
  • host_id - Optional - Long - The host that corresponds with the backup (defaults to the Console).
Any other set fields will be ignored.

{ "name": "nightly", "description": "nightly_backup", "configuration_id": 1 }
Table 4. POST /backup_and_restore/backups response codes
HTTP Response Code Unique Code Description

201

The backup was created.

409

1005

The 'name' parameter value must be unique.

409

1011

An undeployed configuration change has been detected. Deploy staged changes then try again.

409

1015

A backup is already in progress on the host.

409

1016

A restore is currently in progress. No new backup or restore processes can be initiated while the current process is running.

422

1002

The 'name' parameter value cannot be null or empty.

422

1003

The 'name' parameter value must not exceed 100 characters.

422

1004

The 'name' parameter must contain only alphanumerics and '_', '-' or '.'.

422

1006

The 'configuration_id' parameter value cannot be null or empty.

422

1007

The backup configuration does not exist.

422

1008

The 'description' parameter value must not exceed 255 characters.

422

1009

The backup host does not exist.

422

1010

The provided host_id corresponds to a host that is currently not active. For more information, see the following Hosts API: api/config/deployment/hosts

422

1012

The provided host_id corresponds to a host that is not the console and the backup type is CONFIG. A config backup can only take place on the console.

422

1013

Data backups can only be done on hosts that store ariel data. For more information, see the following Hosts API: api/config/deployment/hosts

422

1014

The host is not configured for data backups. See the Backup Configuration API for more information: api/config/backup_and_restore/scheduled_backup_configurations

500

1000

An error occurred during the attempt to create the backup.

Response Description

The created backup object containing the following fields:
  • id - Long - The ID of the backup.
  • configuration_id - Long - The ID of the configuration. This will always be 1. See the Backup Configuration APIs for more information:
    • api/config/backup_and_restore/scheduled_backup_configurations
    • api/staged_config/backup_and_restore/scheduled_backup_configurations
  • host_id - Long - The host that corresponds with the backup. For more information, see the following Hosts API:
    • api/config/deployment/hosts
  • name - String - The name of the backup.
  • description - String - An optional description of the backup.
  • type - Enumeration - The backup type. The following values are available: CONFIG, DATA.
  • version - String - The QRadar version that corresponds to the backup.
  • time_initiated - Long - The number of milliseconds since epoch when the backup was started.
  • time_completed - Long - The number of milliseconds since epoch when the backup completed.
  • initiated_by - String - The user or authorized service that started the backup.
  • status - Enumeration - The status of the backup. The following values are available: INITIALIZING, IN_PROGRESS, FAILED, SUCCESS, CANCELLING, DELETING, MISSING.
    • INITIALIZING: The initial state of the backup when it is created. In this state a backup object is created and a request to the Backup and Restore Engine is sent.
    • IN_PROGRESS: When the backup request is received by the Backup and Restore Engine, the status is updated IN_PROGRESS.
    • FAILED: If the backup has completed with errors, the status is updated to FAILED.
    • SUCCESS: If the backup has completed without errors, the status is updated to SUCCESS.
    • CANCELLING: CANCELLING: If a request is sent from the API to delete a backup that is in progress, after the request is received by the Backup and Restore Engine, the backup status is updated to CANCELLING.
    • DELETING: If a request is sent to delete a backup, after the request is received by the Backup and Restore Engine the backup status is updated to DELETING. The backup record, along with the backup file, is deleted.
    • MISSING: If the backup file for a backup record is moved or deleted outside of the control of the Backup and Restore Engine, the status of that record is updated to MISSING.
  • size_on_disk - Long - The size of the backup in bytes.
  • content_file_path - String - The file path that corresponds to the backup contents.
  • is_valid - Boolean - If the associated backup file, backup manifest and its properties are all in working order, the condition is set to 'true'; otherwise, the condition is set to 'false'.  Some examples as to why the backup might not be valid are as follows:
    • The backup manifest is missing properties.
    • Unable to retrieve the backup manifest.
    • The backup from a non-HA standby system cannot be restored on a Console that is configured as a HA standby system.
    • The backup and the host product names do not match.
    • The backup and the host appliance names do not match.
    • The backup uses the current Console IP address for the non-Console managed host.
  • is_version_compatible - Boolean - If the associated backup version is compatible with the system the condition is set to 'true'; otherwise, the condition is set to 'false'.

Response Sample


{
    "build_version": "String",
    "configuration_id": 42,
    "content_file_path": "String",
    "description": "String",
    "host_id": 42,
    "id": 42,
    "intiated_by": "String",
    "is_valid": true,
    "is_version_compatible": true,
    "name": "String",
    "size_on_disk": 42,
    "status": "String",
    "time_completed": 42,
    "time_initiated": 42,
    "type": "String",
    "version": "String"
}