Get a Database Backup - Help | Developer Portal for YouTrack and Hub

Use Case

Use the REST API to get a backup of your YouTrack database.

Summary

To get a backup of the YouTrack database:

Get a list of available backups.
If required, create a new backup.
Get the URL of the new backup.

Step-by-Step

Get a list of Available Backups

To get a list of available backups, send a GET request to the database backups endpoint:

/api/admin/databaseBackup/backups

In response, you will get a JSON object containing one or more database backups.

Use the following syntax for the request:

GET /api/admin/databaseBackup/backups{?fields=<fields>}

Pay attention to the fields request parameter. It should contain a list of database backup entity attributes, that YouTrack must return in response to your request. If you do not specify any field here, you will get only the entity ID and \$type of each found database backup. Read more about fields syntax in YouTrack REST API.

Sample request

        curl -X GET \
        'https://example.youtrack.cloud/api/admin/databaseBackup/backups?fields=creationDate,file,error,link,name,size,id' \
        -H 'Accept: application/json' \
        -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7'
      

Sample response body

        [
          {
            "name": "2020-09-05-22-27-16.tar.gz",
            "size": 9291043,
            "creationDate": 1536175642000,
            "link": "backupFile/2020-09-05-22-27-16.tar.gz",
            "file": "/mnt/disk0/example/backup/2020-09-05-22-27-16.tar.gz",
            "error": null,
            "id": "2020-09-05-22-27-16.tar.gz"
          }
        ]
      

Optional: Create a Fresh Backup

If you wish to create a fresh backup, send a POST request to the following endpoint:

/api/admin/databaseBackup/settings

As the payload, send a JSON object backupStatus instructing the server to initiate the backup.

For instance, the following sample request initiates a new backup:

        curl -X POST \
          'https://example.youtrack.cloud/api/admin/databaseBackup/settings?fields=archiveFormat,availableDiskSpace,backupStatus(backupCancelled,backupError(date,errorMessage),backupInProgress,stopBackup)' \
          -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
          -H 'Content-Type: application/json' \
        -d '{
          "backupStatus": {
            "backupInProgress": true,
            "stopBackup": false
          }
        }'
      

Pay attention to the headers in the request, and you can also provide a list of attributes in the fields request parameter to specify the attributes that will help you monitor the backup in the response that the server will return.

To the sample request above, server would return the following data:

        {
          "archiveFormat": "TAR_GZ",
          "backupStatus": {
            "backupInProgress": true,
            "stopBackup": false,
            "backupError": null,
            "backupCancelled": false
          },
          "availableDiskSpace": 163739054080
        }
      

Get the link to the backup

After you created a fresh backup, you can send another GET request to read an updated list of the backups.

The most important here is to specify the following attributes in the fields request parameter: creationDate,link,id.

For example, we send the following GET request:

        curl -X GET \
        'https://example.com/youtrack/api/admin/databaseBackup/backups?fields=creationDate,link,id' \
        -H 'Accept: application/json' \
        -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7'
      

In response to such request, the server returns the follwing group of JSON objects, sorted by the creation timestamp in descending order.

        [
          {
            "creationDate": 1558523648000,
            "link": "backupFile/2020-05-22-13-14-07.tar.gz",
            "id": "2020-05-22-13-14-07.tar.gz",
            "$type": "BackupFile"
          },
          {
            "creationDate": 1558422000000,
            "link": "backupFile/2020-05-21-09-00-00.tar.gz",
            "id": "2020-05-21-09-00-00.tar.gz",
            "$type": "BackupFile"
          },
          {
            "creationDate": 1558335600000,
            "link": "backupFile/2020-05-20-09-00-00.tar.gz",
            "id": "2020-05-20-09-00-00.tar.gz",
            "$type": "BackupFile"
          }
        ]
      

So, to download the fresh backup, we how need to take the link for the first returned backup entity: "link": "backupFile/2020-05-22-13-14-07.tar.gz".

To compose the complete download URL, you need to add the link to the baseURL of your youtrack service. In our example, the baseURL for the service would be https://example.com/youtrack/. Hence, the complete download URL for the newest database backup file would be:

https://example.com/youtrack/backupFile/2020-05-22-13-14-07.tar.gz