Back up and download with the REST API

Tip Back up the Collibra Platform environments on a regular basis.

In Collibra Console you can manually back up your environments at any time or set up a schedule to automatically create backups at a set interval. You can achieve the same using the /backup and /backupSchedule endpoints of the CollibraManagement Console REST API.

Important Do not include any cookies in your requests. This results in a 403 - Forbidden error.

Create a backup

Before you start, you must know the ID of the environment you want to back up. You can retrieve it through the API or get it from Collibra Console:

Retrieve a list of all environments with a GET method of the /environment endpoint:

curl -L -X GET 'https://<your_collibra_console_url>/rest/environment' \
-H 'Authorization: Basic <Base64_username:password_encoded_values>'

Response example:

[
    {
        "createdDate": 1699926678.042000000,
        "modifiedDate": 1699926678.042000000,
        "id": "a8f3ff8a-9bbd-43a2-833d-d54e96d4a798",
        "name": "Default environment",
        "serviceIdSet": [
            "3e50ee0f-d5dd-4935-9355-ad7da43a3eff",
            "13144bac-a319-45f6-b459-4e856a998488",
            "79c43e61-e51e-4f13-94f4-e27b9e94500f",
            "163342f3-4a7a-4cc8-b0c8-2b15ecfa31fa"
        ],
        "status": "RUNNING"
    }
]

In Collibra Console, go to the Environments tab and click the relevant environment to open its details. The environment ID appears in the address bar of your browser, after the colon sign.

Example https://console.collibra.com/#/environments/Environment:a8f3ff8a-9bbd-43a2-833d-d54e96d4a798

To create a backup, use the POST method of the /backup{environmentId} endpoint and provide the backup information in a JSON body:

curl -L -X POST 'https://<your_collibra_console_url>/rest/backup/<environment_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <Base64_username:password_encoded_values>' \
-d '{
    "name": "<your_backup_name>",
    "description": "<your_backup_description>",
    "dgcBackupOptions": [
        "CUSTOMIZATIONS",
        "CONFIGURATION"
    ],
    "repoBackupOptions": [
        "DATA",
        "HISTORY"
    ]
}'
import http.client
import json

conn = http.client.HTTPSConnection("<your_collibra_console_url>")
payload = json.dumps({
  "name": "<your_backup_name>",
  "description": "<your_backup_description>",
  "dgcBackupOptions": [
    "CUSTOMIZATIONS",
    "CONFIGURATION"
  ],
  "repoBackupOptions": [
    "DATA",
    "HISTORY"
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Basic <Base64_username:password_encoded_values>'
}
conn.request("POST", "/rest/backup/<environment_id>", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': '<your_collibra_console_url>',
  'path': '/rest/backup/<environment_id>',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Basic <Base64_username:password_encoded_values>'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "name": "<your_backup_name>",
  "description": "<your_backup_description>",
  "dgcBackupOptions": [
    "CUSTOMIZATIONS",
    "CONFIGURATION"
  ],
  "repoBackupOptions": [
    "DATA",
    "HISTORY"
  ]
});

req.write(postData);

req.end();
Important 

The name must not contain special characters.

description is an optional parameter.

The possible values for dgcBackupOptions are "CUSTOMIZATIONS" and "CONFIGURATION". If you select none, you must add at least one of the repoBackupOptions.

The possible values for repoBackupOptions are "DATA" and "HISTORY". If you selected "HISTORY", you must also add "DATA". If you select none, you must add at least one of the dgcBackupOptions.

Response example:

{
    "createdDate": 1699965108.223000000,
    "modifiedDate": 1699965108.223000000,
    "id": "d8c09773-f56e-49db-bfea-a2305ecbb219",
    "backupInformation": {
        "name": "<your_backup_name>",
        "description": "<your_backup_description>",
        "appVersion": "2023.11",
        "createdByEmail": "<email_address>",
        "date": 1699965108.198000000,
        "backupSpecificationId": "8eaac39e-2114-459b-9ca3-2b66b0ca5fdc",
        "environmentId": "a8f3ff8a-9bbd-43a2-833d-d54e96d4a798",
        "dgcBackupOptions": [
            "CUSTOMIZATIONS",
            "CONFIGURATION"
        ],
        "repoBackupOptions": [
            "HISTORY",
            "DATA"
        ]
    },
    "size": 0,
    "stepStateMap": {
        "REPOSITORY": {
            "status": "WAITING",
            "errorMessage": ""
        },
        "PRE_PROCESSING": {
            "status": "COMPLETED",
            "errorMessage": ""
        },
        "DGC": {
            "status": "WAITING",
            "errorMessage": ""
        },
        "POST_PROCESSING": {
            "status": "WAITING",
            "errorMessage": ""
        }
    },
    "inProgress": true
}

Download a backup

Before you start, you must know the ID of the backup you want to download. You can see the ID in the response you get after creating a backup or you can use the GET method of the /backup endpoint to retrieve a list of all the available backups:

curl -L -X GET 'https://<your_collibra_console_url>/rest/backup' \
-H 'Authorization: Basic <Base64_username:password_encoded_values>'
import http.client

conn = http.client.HTTPSConnection("<your_collibra_console_url>")
payload = ''
headers = {
  'Authorization': 'Basic <Base64_username:password_encoded_values>'
}
conn.request("GET", "/rest/backup", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'GET',
  'hostname': '<your_collibra_console_url>',
  'path': '/rest/backup',
  'headers': {
    'Authorization': 'Basic <Base64_username:password_encoded_values>'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

Response example:

[
    {
        "createdDate": 1699965108.223000000,
        "modifiedDate": 1699965133.074000000,
        "id": "d8c09773-f56e-49db-bfea-a2305ecbb219",
        "backupInformation": {
            "name": "<your_backup_name>",
            "description": "<your_backup_description>",
            "appVersion": "2023.11",
            "createdByEmail": "<email_address>",
            "date": 1699965108.198000000,
            "backupSpecificationId": "8eaac39e-2114-459b-9ca3-2b66b0ca5fdc",
            "environmentId": "a8f3ff8a-9bbd-43a2-833d-d54e96d4a798",
            "dgcBackupOptions": [
                "CUSTOMIZATIONS",
                "CONFIGURATION"
            ],
            "repoBackupOptions": [
                "HISTORY",
                "DATA"
            ]
        },
        "size": 126533796,
        "stepStateMap": {
            "REPOSITORY": {
                "status": "COMPLETED",
                "errorMessage": ""
            },
            "PRE_PROCESSING": {
                "status": "COMPLETED",
                "errorMessage": ""
            },
            "DGC": {
                "status": "COMPLETED",
                "errorMessage": ""
            },
            "POST_PROCESSING": {
                "status": "COMPLETED",
                "errorMessage": ""
            }
        },
        "inProgress": false
    }
]

To download a backup, use the POST method of the /backup/file/{id} endpoint.

Important 
  • You must include a 'Content-Type: application/x-www-form-urlencoded' header.
  • You must add a 'key=<your_password>' data option. This encrypts the download and you must provide the password when you upload the file. If you don't want to password protect the download, leave the password empty.
  • If you started using Collibra with version 2025.01 or newer, or you upgraded to version 2025.04, you benefit from integrated cloud storage. Use the GET method of the /backup/file/{id}/link endpoint to obtain a unique download link that is valid for 60 seconds. To avoid download disruptions, when using a firewall, ensure your network has access to AWS S3 and Google Cloud Storage endpoints, such as https://*.s3.amazonaws.com/*, https://*.s3.us-gov-west-1.amazonaws.com/*, or https://*.storage.googleapis.com/*.
curl -L -X POST 'https://<your_collibra_console_url>/rest/backup/file/<backup_id>' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic <Base64_username:password_encoded_values>' \
-d 'key='
-o 'backup.zip'

Tip To save the file locally, provide the -o option and the name of the file. In this example, the file is saved as backup.zip in your current directory.

import http.client

conn = http.client.HTTPSConnection("<your_collibra_console_url>")
payload = 'key='
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Authorization': 'Basic <Base64_username:password_encoded_values>'
}
conn.request("POST", "/rest/backup/file/<backup_id>", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var https = require('follow-redirects').https;
var fs = require('fs');

var qs = require('querystring');


var options = {
  'method': 'POST',
  'hostname': '<your_collibra_console_url>',
  'path': '/rest/backup/file/<backup_id>',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic <Base64_username:password_encoded_values>'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = qs.stringify({
  'key': ''
});

req.write(postData);

req.end();