The API solution is a faster and flexible way to initiate backups and restore for Jira and Confluence. We also offer a UI-based solution that you can access by going to Settings > Data management > Backup and restore in admin.atlassian.com.

Getting started

Before you begin, make sure that you are enrolled into our EAP (Early access program) and that you are the admin of your organization. As part of this EAP, you can perform one complete backup and one complete restore every week.

Your backups are safely stored in an internal Atlassian location for 14 days, allowing you to restore from there within those 14 days. Post that period, the backup is automatically scheduled for deletion to comply with our data retention policy.

To move forward with our solution, we just need you to complete a quick authentication step in our system!

Our Backup and Restore feature is accessible via both Public APIs and our AdminHub (UI). Both routes support full backup and restore functionality. However, please note that the UI provides an additional feature: Post-operation reporting. This reporting feature is not available through the Public APIs.

Authorization

The backup management APIs use basic authentication. To complete the setup, follow the instructions on our Authorization page. Once you are authorized into the system, you are ready to use our APIs

Prerequisites

You need the CloudId and Product of your site on the organisation of which you are an admin. You can get the site name from the Products page on admin.atlassian.com. Once you have the site name, you can fetch your cloudId by either clicking on Manage Product, or by hitting the url - https://<YOUR_SITE_NAME>.atlassian.net/_edge/tenant_info
Once you have the details you can check your Product License. These APIs won’t work for products on Free plans. Currently, we offer Backup and Restore functionalities to users who have either Standard, Premium or Enterprise License. For more details on the Billing and Licensing part, see the support FAQ

Overview

Get supported regions for organisation

This API retrieves the list of regions where a storage can be created for your organisation, if you wish to use your external S3 storage.

Endpoint : POST orgs/{orgId}/storages/regions

Create/Connect your own storage

This is required when you prefer to take a backup on external cloud storage instead of using the Atlassian S3. To create a storage you need to follow these steps.

Create an AWS account or use an existing one. Read how to create and activate an AWS account.
In AWS, create an AWS S3 bucket, or use an existing one. Learn how to create an S3 bucket.
Once you have the bucket ready, you need to call the Create Storage API. Note that the storage can be created only in those regions where your cloud products reside. This can be verified by Get Supported Regions for Organisation API. This API also returns two additional fields - principalTag and roleIdentifier, which will be further used to create the Storage.

Endpoint : POST orgs/{orgId}/storages

Request body:

1
2
{
    "storageName": "<your external storage bucket name>",
    "storageRegion": "<supported region for org>",
    "storagePrefix": "<your storage prefix>",
    "storageType": "aws",
    "roleIdentifier": "<roleIdentifier",
    "principalTag": "<principalTag>",
    "cloudId": "<cloudId>"
}

Get all storages

This API retrieves the list of all the storages that exist within your organisation. This request also uses optional query params - cloudId and product if you want to retrieve the storages for a particular site or product.

Endpoint : GET orgs/{orgId}/storages

Get storage details

If you want to retrieve the details of a particular storage, then you can call this endpoint by passing the storageId in the request

Endpoint : GET /orgs/{orgId}/storages/{storageId}

Create a backup policy

Before running a backup for the first time, you need to create a backup policy for the product. The policy includes the product you choose to back up and whether to include attachments in the backup. For Confluence, the policy also includes if personal spaces are part of the backup.

While creating a backup policy you might decide to connect your own custom storage or use the existing storage provided by Atlassian to backup your data. If you choose to use an external cloud storage, you need to Create a storage of your own using the Create storage API. However if you decide to move ahead with Atlassian storage, you can avoid passing this field entirely. The operation requires a POST request, with essential parameters encapsulated within the request's body

Endpoint : POST /orgs/{orgId}/cloud/{cloudId}/policies

Request body:

1
2
{
    "product": "<product>", // JIRA or CONFLUENCE
    "storageId": "storageId" // optional field, needed only if you wish to use external cloud storage, else null
    "includeAttachments": <boolean>,
    "includePersonalSpaces": <boolean> // optional field needed only for Confluence
}

includeAttachments: A Boolean value (True/False) indicating whether attachments should be included in the backup.

includePersonalSpaces (For Confluence only): A Boolean value (True/False) determining if personal spaces are to be included in the backup.

Get all backup policies

If you need all the backup policies that have been created for different sites and products in your organisation, you can execute this API

Endpoint : GET /orgs/{orgId}/policies

Get backup policy details

Retrieve all the details of a particular backup policy using this api

Endpoint : GET /orgs/{orgId}/policies/{policyId}

Update a backup policy

This API can be used to modify the details of an existing backup policy. All the fields passed in this request are optional fields and hence the customer can send only those details which they want to update. You can also use this API to connect your storage to a backup policy if it wasn’t connected earlier

Endpoint : PUT /orgs/{orgId}/policies/{policyId}

Request body:

1
2
{
    "storageId": "storageId" // needed only if you wish to connect/change your external cloud storage to existing backup policy
    "includeAttachments": <boolean>,
    "includePersonalSpaces": <boolean> // for Confluence only
}

Run a backup

Use an existing policy to run backups for a product.

You can run a new backup 7 days after your last complete backup. To run a backup for a new product, create a new policy by following the steps in the previous section.

Each backup has one of the following statuses:

IN PROGRESS - the backup is still in progress
COMPLETE - the backup has finished running, and is complete
INCOMPLETE - the backup has finished running, and is missing some attachments in the case of Jira products, or missing some spaces in the case of Confluence
EXPIRED - it’s been over 14 days since running the backup, and the backup is no longer available
FAILED - the backup failed

Endpoint : POST /orgs/{orgId}/backups

Request body:

1
2
{
    "policyId": "<policyId>",
    "cloudId": "<cloudId>"
}

Limitations -

Is there a size limit to the backups?

Atlassian storage:

Jira: 40GB + 500GB attachments
Confluence: 30GB + 800GB attachments

Get all backups for a backup policy

Use this API to get the list of backups that were taken for a particular backup policy id

Endpoint : GET /orgs/{orgId}/policies/{policyId}/backups

Get backup details

Used to fetch the details of a specific backupId

Endpoint : GET /orgs/{orgId}/backups/{backupId}

Export product data to your own s3

This feature enables you to export backup data from Atlassian’s Storage to their personal S3 bucket after establishing a successful connection between the backup policy and storage. This API can trigger export of multiple backups at one time.

Endpoint : POST /orgs/{orgId}/exports

Request body:

1
2
[
    {
        "product": "<product>", //JIRA or CONFLUENCE
        "cloudId": "<cloudId>",
        "backupId": "<backupId>"
    }
]

Get all exports for an organisation

Used to fetch the exports within an organisation. This API also filters the result on the basis of productType if specified as a request param

Endpoint : GET /orgs/{orgId}/exports

Get export details

Used to fetch the details of a particular exportId and cloudId

Endpoint : GET orgs/{orgId}/cloud/{cloudId}/exports/{exportId}

Import product data from your own S3

This functionality is used to facilitate the import of previously exported backup data from an external cloud storage to Atlassian storage. Import is possible only when you have an external storage connected to your backup policy and which has some backed up data which as exported earlier in the past. Import is usually followed by the initiation of a restore request. This API can import multiple backups at one time.

Endpoint : POST /orgs/{orgId}/imports

Request body:

1
2
[
    {
        "product": "<product>", //JIRA or CONFLUENCE
        "cloudId": "<cloudId>",
        "backupId": "<backupId>"
    }
]

Get import details

Used to fetch the details of a particular importId and cloudId

Endpoint : GET orgs/{orgId}/cloud/{cloudId}/imports/{importId}

Restore product data from backup

Perform a restore whenever you need to recover lost or damaged data in Jira or Confluence. You can restore backups from Atlassian's storage, provided they were taken within the last 14 days.

Firstly, we recommend you restore only COMPLETE backups, although INCOMPLETE backups can also be restored. Backups that are IN PROGRESS, EXPIRED, or FAILED can’t be restored.

The customer has the ability to generate restores using unique backupIds assigned to each backup.

When it comes to restoration, the customer is presented with two options:

The first option is to make use of the backup stored in Atlassian’s S3 bucket. You can restore backups from Atlassian's storage, provided they were taken within the last 14 days. Here the cloudId specified in the request should be another site within the same organization.

Endpoint : POST /orgs/{orgId}/cloud/{destCloudId}/restores Request body:

1
2
{
 "backupId": "<backupId>",
 "includeAttachments": <boolean>, // true only if attachments were also backed up,
 "includeUsersAndGroups": <boolean>, // Set this to false to exclude users and groups from being restored in the new site
 "product": "<product>" // JIRA or CONFLUENCE
 }

The second option involves importing the backup data from the customer’s connected external storage, where the data was originally exported by calling the Import API. Restore can be initiated once you import the data from your external storage to Atlassian storage.

Limitations-

You can restore backed up Jira and Confluence product data at any time until the backup expires. You have 14 days from backup to restore your data. You can restore a specific backup once in 7 days.

For a more detailed list of limitations, go through our Backup and restore limitations page

Revalidate restore

Once the create request API is triggered with the necessary fields, it initiates validation procedures that specifically verify the following:

If some spaces or projects already exist on the destination. If there are duplicate spaces on destination and backup, those spaces will be skipped during restore. The version of the destination site will remain.
Groups with same name already exist. We’ll merge user groups with same names. Users may get unwanted permissions, as they will be granted permissions of the groups they are added to.
If destination product is not on a free plan and is on the same plan as the backed up site. Upgrade the site to at least the same license level as the backed up site.
Backups should be restored on the same shard
The site is not on a free trial. Backup and restore is currently available only to a standard, premium or enterprise license site. If the site is on a free trial, then upgrade the site to proceed with restoration

In case any of these validations fail, the user will receive a unique error code. More details on how to troubleshoot this issue can be found here.

Endpoint : POST /orgs/{orgId}/cloud/{destCloudId}/restores/revalidate

Request body:

1
2
{
    "restoreId": "<restoreId>", // restoreId received from create restore request
    "consent": ["<failingCheck1>", "<failingCheck2>".....]
}

The value that has to be passed in consent can be any 1 or more from the below checks depending on warnings received in the create restore API.

"Consent_Conflicting_Space_Check"
"Consent_Conflicting_Group_Check"
"Consent_Product_License_Check"
"Consent_TDP_Shard_Check"
"Consent_Site_License_Check"
"Accept_Custom_Group_Check"
"Deny_Custom_Group_Check"

Get all restores

Use this API to get the list of restores that were taken for a particular cloudId and product, both of which are optional params. If these values are not specified, the serve will respond will all the restores taken in that organisation

Endpoint : GET /orgs/{orgId}/restores

Get restore details

Fetch the details of a particular restoreId

Endpoint : GET /orgs/{orgId}/restores/{restoreId}

Get post operation report

Use this API to fetch the URL of the post-operation report of a migration.

Endpoint: GET /orgs/{orgId}/cloud/{cloudId}/migration/{migrationId}/postOpReport