---
title: "Backup - REST"
canonical: "https://docs.getxray.app/space/XRAYCLOUD/44566657/Backup%20-%20REST"
format: markdown
---
There are three endpoints regarding backups of Xray information.


|  |  |
| --- | --- |
| Generate a Backup | <span style="color: #FF9900">**/api/v1/backup**</span> |
| Check backup job status | <span style="color: #FF9900">**/api/v1/backup/{jobId}/status**</span> |
| Get backup file | <span style="color: #FF9900">**/api/v1/backup/file**</span> |
| Get attachment backup file | <span style="color: #FF9900">**/api/v1/backup/file/attachment**</span> |


The first endpoint is an asynchronous call to generate a backup. Whenever this endpoint is called, a job is queued to create the backup and its id is returned. The second endpoint can be used to check the status of this job.

## Generate a Backup

When importing tests, you can use the following endpoint:

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> > ℹ️ Create a job to generate a backup.
> > ℹ️ 
> > ℹ️ <span style="color: #003366">**Request**</span>
> > ℹ️ 
> > ℹ️   
> > ℹ️ In the body of the request the following fields can be used:
> > ℹ️ 
> > ℹ️ - **projectIds **(optional): This field determines which projects to backup. This field is optional, if omitted, the backup will contain Xray information of all projects containing it.
> > ℹ️ - **modifiedSince **(optional): This field can hold a date in order for a partial backup to be generated containing only entities that were change from that date until now. This field is optional, if not supplied a full backup will be generated.
> > ℹ️ - **withAttachment** (optional): It determines if the a zip file with the attachments should also be generated.
> > ℹ️ 
> > ℹ️ ###### <span style="color: #003366">**Example 1:**</span>
> > ℹ️ 
> > ℹ️   
> > ℹ️ **Example Input**
> > ℹ️ 
> > ℹ️ > Macro (legacy-content)
> > ℹ️ 
> > ℹ️ > Macro (legacy-content)
> > ℹ️ 
> > ℹ️ ### <span style="color: #003366">**Responses**</span>
> > ℹ️ 
> > ℹ️ <span style="color: #FFFFFF">200 OK</span> : **application/json** : Successful. The backup job was created successfully and the Job Id is provided.  
> > ℹ️ **Example Output**
> > ℹ️ 
> > ℹ️ > Macro (legacy-content)
> > ℹ️ 
> > ℹ️ 
> > ℹ️ <span style="color: #FFFFFF">400 BAD_REQUEST</span> : **application/json**** ****:**** **No backup job was created.** **Another backup job is still running or was completed not long ago.  
> > ℹ️ **Example Output**
> > ℹ️ 
> > ℹ️ > Macro (legacy-content)
> > ℹ️ 
> > ℹ️   
> > ℹ️   
> > ℹ️ <span style="color: #FFFFFF">**401 UNAUTHORIZED**</span>**: application/json: **The API token is invalid.

## Check a Backup Status

When importing tests, you can use the following endpoint:

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> |  |
> | --- |
> | Get a backup job status.<br><span style="color: #003366">**Request**</span>** **<br>###### <span style="color: #003366">**PATH **</span><span style="color: #003366">**PARAMETERS**</span><br>> Macro (nested-table)<br>> ✅ **Example Request**
> > ✅ 
> > ✅ curl -H "Content-Type: application/json" -X GET -H "Authorization: Bearer $token" https://xray.cloud.getxray.app/api/v1/backup/34a4106b1d0948d1aae1170cc8df3bb4/status<br>### <span style="color: #003366">**Responses**</span>** **<br>200 OK : **application/json** : The status of the backup job is returned.<br>##### **Example Output 1**<br>```
> {
>   "status": "working",
>   "progressValue": "10%"
> }
> ```<br>##### **Example Output 2**<br>```
> {
>   "status": "successful",
>   "fileUrl": "https://xray.cloud.getxray.app/api/v1/backup/file",
>   "attachmentUrl": "https://xray.cloud.getxray.app/api/v1/backup/file/attachment"
> }
> ```<br>404 BAD_REQUEST : **application/json ****: **No backup job with the given id was found.<br>##### **Example Output**<br>```javascript
> {
>   "error": "job not found."
> }
> ```<br>401 UNAUTHORIZED : **application/json** : The API token is not valid. |

## Download the backup file

> ℹ️ To download large backup files, please use [version 2 of the REST API](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44578092).

To download the backup file, you can use the following endpoint:

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> |  |
> | --- |
> | Download the backup file.<br><span style="color: #003366">**Request**</span>** **<br>> ✅ **Example Request**
> > ✅ 
> > ✅ curl -H "Content-Type: application/json" -X GET -H "Authorization: Bearer $token" https://xray.cloud.getxray.app/api/v1/backup/file<br>### <span style="color: #003366">**Responses**</span>** **<br>200 OK : **application/octet-stream**: The backup file is downloaded.<br>404 NOT_FOUND : **application/json ****: **A backup file is not available.<br>##### **Example Output**<br>```javascript
> {
>   "error": "Backup file is not available."
> }
> ```<br>401 UNAUTHORIZED : **application/json** : The API token is not valid. |

<span style="color: #172B4D">Download the attachment backup file</span>

> ℹ️ To download large backup files, please use [version 2 of the REST API](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44578092).

To download the attachment backup file, you can use the following endpoint:

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> |  |
> | --- |
> | Download the backup file.<br><span style="color: #003366">**Request**</span>** **<br>> ✅ **Example Request**
> > ✅ 
> > ✅ curl -H "Content-Type: application/json" -X GET -H "Authorization: Bearer $token" [https://xray.cloud.getxray.app/api/v1/backup/file/attachment](https://xray.cloud.xpand-it.com/api/v1/backup/file/attachment)<br>### <span style="color: #003366">**Responses**</span>** **<br>200 OK : **application/octet-stream**: The backup file is downloaded.<br>404 NOT_FOUND : **application/json ****: **A backup file is not available.<br>##### **Example Output**<br>```javascript
> {
>   "error": "Backup file is not available."
> }
> ```<br>401 UNAUTHORIZED : **application/json** : The API token is not valid. |