---
title: "REST API: Configuration Manager"
canonical: "https://support.appfire.com/space/CMJ/197955929/REST%20API%3A%20Configuration%20Manager"
format: markdown
---
> Macro (aura-html)
> 📝 **For details and examples, take a look at the REST API reference:**
> 📝
> 📝 Documentation for [REST API 1.7](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/2506653789) - available with Configuration Manager 9.0.0 or later.
## URI structure
Configuration Manager's REST API provides means to manage snapshots via URI paths. URIs for Configuration Manager's REST API resource have the following structure:
```
http://host:port/context/rest/configuration-manager/api/api-version/resource-name
```
The **current API version** is 1.7.
For example, you would use the following path to access the snapshots' API on a locally run instance of Jira with a context path of /jira:
```
http://localhost:2990/jira/rest/configuration-manager/api/1.7/snapshots
```
> ℹ️ **Context Path**
> ℹ️
> ℹ️ The example above specifies a context path of “/jira”. Keep in mind that **the context path may be different or not present** for your installation of Jira.
## Step-by-step guide for using the API
---
---
This snapshot endpoint creates a new snapshot.
**Request**
QUERY PARAMETERS
> ℹ️ The query parameters vary based on the value of the **"scope" parameter. **
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| **PARAMETERS FOR ALL SCOPES** |
| name | *string*
**Required** | The name of the snapshot. |
| scope | *string*
**Required** | **Accepted values**: `"system"`, `"project"` or `"projectWithIssues"`. |
| description | *string*
Optional | The description of the snapshot. |
| **PARAMETERS FOR SCOPES: PROJECT, PROJECT WITH ISSUES** |
| projectKey | *array of strings*
**Required** | Includes one or more selected projects.
**Example**:
For single-project snapshots:
```
"projectKey" : "PRJ"
```
For multi-project snapshots:
```json
"projectKey" : [
"PRJA",
"PRJB"
]
``` |
| filters | *array of objects*
Optional | Includes the filters that match the provided `"filterId"`.
**Example**:
```json
"filters" : [{
"filterId" : 1
}]
``` |
| includeProjectFilters | *boolean*
Optional
Default value: *false* | Includes all filters referenced by the projects in the snapshot.
[Learn more](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/198117100). |
| agileBoards | *array of objects*
Optional | Includes the agile boards that match the provided `"boardId"`.
**Example**:
```json
"agileBoards" : [{
"boardId" : 1
}]
``` |
| includeProjectBoards | *boolean*
Optional
Default value: *false* | Includes all boards of the projects exported with the snapshot.
[Learn more](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/198247358). |
| includeProjectAutomationRules | *boolean*
Default value:
*false*
Optional | Includes all automation rules associated with the selected projects.
[Learn more](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/2192608406). |
| includeGlobalAutomationRules | *boolean*
Default value:
*false*
Optional | Includes all global automation rules.
[Learn more](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/2192608406). |
| dashboards | *array of objects*
Optional | Includes the dashboards that match the provided `"dashboardId"`.
**Example**:
```json
"dashboards" : [{
"dashboardId" : 1
}]
``` |
| appsWithGlobalData | *array of objects*
Optional | Includes the global configuration and/or data objects of all specified Jira apps integrated with the respective Service Provider Interface (SPI) integration points. [Learn more](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/198279999).
**Available objects**:
- `"key" `- specifies the app's key;
- `"includeGlobalConfiguration"` -* *includes the global app configuration settings of the app specified by the `"key"` parameter. The app must be integrated with CMJ via the SPI [global configuration integration point](https://appfire.atlassian.net/wiki/spaces/AppIn/pages/197858762).
- `"appDataIds"` - includes custom functionality of an app that extends standard Jira functions. The selected app must be integrated with CMJ via the SPI [app data integration point](https://appfire.atlassian.net/wiki/spaces/AppIn/pages/197924825).
- `"typeId"` - specifies the app's selected types of objects (functionality);
- `"objectIds"` - includes specific app data objects of the selected types.
**Example**:
```json
"appsWithGlobalData" : [
{
"key": "com.botronsoft.jira.rollout.spi-test-plugin",
"includeGlobalConfiguration": "true",
"appDataIds": [
{
"typeId" : "typeOneId",
"objectIds" : ["id1", "id2", "id3"]
},
{
"typeId" : "typeTwoId",
"objectIds" : ["id3"]
}
]
}
]
``` |
| filter
***Only applicable to the Project with issues scope.*** | *string*
Optional | Includes only issues filtered by a JQL query.
**Example**:
```json
"filter":"issueType = Bug"
``` |
| includeOnlyArchivedIssues | *boolean*
Optional
Default value: *false* | Includes only archived issues. |
| options | *object*
Optional | Specifies additional data that can be included in the snapshot.
**Available options**:
- `"includeAttachmentFiles"` (***only applicable to project with issues scope***) - includes issue attachment files for the selected projects. If the value is *false*, during snapshot deployment there's an option to provide the path where the attachment files reside on the target system.
- `"checkCustomFieldValues"` (***only applicable to project scope***)- includes custom fields with value in at least one issue in the project. If the value is *false*, only custom fields referenced by the project configuration will be included.
The default value of both options is *false *if not else specified* *or if the `"options"` parameter is not used.
**Example**:
```json
"options" : {
"includeAttachmentFiles" : true,
"checkCustomFieldValues" : true
}
``` |
| **PARAMETERS FOR SCOPE: SYSTEM** |
| includeGlobalAppData | *boolean*
Default value: *false*
Optional | Includes the global configuration data of all Jira apps integrated with CMJ. |
| includeAllFilters | *boolean*
Default value: *false*
Optional | Includes all filters. |
| includeAllBoards | *boolean*
Default value: *false*
Optional | Includes all agile boards. |
| includeAllDashboards | *boolean*
Default value: *false*
Optional | Includes all dashboards. |
| includeAllAutomationRules | *boolean*
Default value:
*false*
Optional | Includes all automation rules. |
**Unix/macOS request **
EXAMPLE
```json
curl -u admin:admin -i -H "Content-Type: application/json" -X POST /rest/configuration-manager/api/1.7/snapshots -d '
{
"name" : "My snapshot",
"description" : "Very nice snapshot",
"scope" : "system"
}
'
```
**Windows request**
EXAMPLE
> ℹ️ **Note** that on Windows machines, single quotes around JSON might not work. Try escaping them like: "{\"name\":\"My snapshot\"...
```
curl -u admin:admin -i -H "Content-Type: application/json" -X POST /rest/configuration-manager/api/1.7/snapshots -d^
"{^
\"name\" : \"My snapshot\",^
\"description\" : \"Very nice snapshot\",^
\"scope\" : \"system\"^
}"
```
**Responses**
BY STATUS CODE
**STATUS 201** *application/json - *Returns a JSON representation of snapshot metadata (includes the *id* of the new snapshot and the *count of objects*).
The** Location** header contains the URI pointing to the newly created snapshot.
```json
HTTP/1.1 201 Created
...
Location: /rest/configuration-manager/api/1.7/snapshots/1
Content-Type: application/json;charset=UTF-8
...
{
"id" : 1,
"objectCount" : 86
}
```
**STATUS 400 **- Returned if a required parameter is not provided or a snapshot with the same name already exists.
**STATUS 403 **- Returned if the user does not have permissions to create a snapshot.
---
---
This snapshot endpoint returns all snapshots' metadata attributes (i.e., no actual snapshot files, just the snapshot metadata).
**Request**
REQUEST EXAMPLE
```json
curl -u admin:admin -H "Content-Type: application/json" -X GET /rest/configuration-manager/api/1.7/snapshots
```
**Responses**
BY STATUS CODE
**STATUS 200 ***application/json* - Metadata successfully fetched.
**STATUS 400** - Returned if the request is invalid.
**STATUS 403** - Returned if the user does not have the necessary permissions to get all snapshots' metadata.
---
---
This snapshot endpoint returns a specified snapshot as a ZIP containing a snapshot file in a binary format.
**Request**
QUERY PARAMETERS
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| id | *integer*
**Required** | The id of the snapshot to be returned as a ZIP. |
REQUEST EXAMPLE
```json
curl -u admin:admin -H "Content-Type: application/json" -X GET /rest/configuration-manager/api/1.7/snapshots/1 > snapshot.zip
```
**Responses**
BY STATUS CODE
**STATUS 200 ***application/octet-stream - *Returns as a ZIP containing a snapshot file in a binary format:
```xml
HTTP/1.1 200 OK
...
Content-Type: application/octet-stream
...
...
```
**STATUS 400** - Returned if the request is invalid.
**STATUS 401 **- Returned if authentication credentials are missing.
**STATUS 403** - Returned if the user does not have permissions to create a snapshot.
**STATUS 404** - Returned if no snapshot with the given id is found.
**STATUS 405 **- Returned if the *id* parameter is not provided in the request body.
---
---
This snapshot endpoint deletes a specified snapshot.
**Request**
QUERY PARAMETERS
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| id | *integer*
**Required** | The id of the snapshot to be deleted. |
REQUEST EXAMPLE
```json
curl -u admin:admin -i -H "Content-Type: application/json" -X DELETE /rest/configuration-manager/api/1.7/snapshots/1
```
**Responses**
BY STATUS CODE
**STATUS 204 **- Returned if successfully deleted.
```json
HTTP/1.1 204 No Content
...
```
**STATUS 400** - Returned if the *id *parameter is not provided.
**STATUS 403** - Returned if the user does not have permissions to create a snapshot.
**STATUS 404** - Returned if no snapshot with the given id is found.
---
---
Deployment is a two-step process:
1. **Meta information** is provided.
2. A **snapshot file** is uploaded.
A separate REST endpoint is used for tracking deployment progress.
The “*Start a deployment operation*” is the first step of the deployment process. The request parameters provide the **meta information **required.
**Request**
QUERY PARAMETERS
> ℹ️ The query parameters vary based on the value of the `"scope"`** parameter. **
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| **PARAMETERS FOR ALL SCOPES** |
| scope | *string*
**Required** | Accepted values: `"system"` and `"project"`. |
| **PARAMETERS FOR SCOPE: PROJECT** |
| mode | *string*
**Required** | Accepted values: `"singleProject"` and `"multiProject"`. Value depends on the number of projects in the deployed snapshot.
Learn more about deploying [single-project](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/197857553) and [multi-project](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/197825512) snapshots. |
| projectKey | *string*
**Required** | ***Only applicable to ***`"singleProject"`*** mode.***
The key of the project with which to merge, usually the same as the project in the snapshot. |
| options | *object*
Some of the objects are **required **for `singleProject` mode.
Optional for `multiProject` mode. | Specifies the behavior during deployment.
There are two main possibilities during deployment:
- **merging** **the project(s) **in the snapshot with the project(s) on target, or
- **creating a new project *****(only applicable to ***`"singleProject"`*** mode)**** *on target identical to the project in the snapshot.
**Available options**:
- `"createNewProject"` - **required **when creating a new project in** **`"singleProject"`** **mode.** **Default value: *false*.
- `"newProjectKey"`/`"newProjectName"` - **required** if `"createNewProject"` = *true*.
- `"projectKey"` - **required** when merging the project in `"singleProject"` mode. This is the key of the project to merge into.
- `"modifyProjectVersions"` - optional. Default value: *true.*
- `"modifyProjectComponents"` - optional. Default value: *true.*
- `"modifyProjectRoles"` - optional. Default value: *true*.
- `"modifyProjectShortcuts"` - optional. Default value: *true*.
- `"attachmentFilesPath"` - optional.
- `"modifyFieldDefaultValues"` - optional. Default value: *true*.
- `"modifyFieldOptions"` - optional. Default value: *true*.
- `"modifyObjectDescriptions"` - optional. Default value: *true*.
- `"modifyObjectTranslations"` - optional. Default value: *true*.
- `"modifyStatusCategories"` - optional. Default value: *true*.
- `"modifyPriorityColors"` - optional. Default value: *true*.
- `"modifyAvatars"` - optional. Default value: *true*.
- `"skipReindexing"` - optional. Default value: *false*.
- `"modifyAutomationRules"` - optional. Default value: *false*.
Learn more about the options in the [Advanced Options document](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/198021794).
**Example**:
```json
"options" : {
"createNewProject" : true,
"newProjectKey" : "PRJ",
"newProjectName" : "My Project",
"modifyProjectVersions" : false,
"modifyProjectComponents" : false,
"modifyProjectRoles": true,
"attachmentFilesPath" : "C:\\attachments"
}
``` |
| **PARAMETERS FOR SCOPE: SYSTEM** |
| mode | *string*
**Required** | **Accepted values: **
- `"systemRestore"` - replaces the configuration on target with the configuration in the deployed snapshot.
- `"systemMerge"` - keeps the configuration of objects on target that are not present in the snapshot.
The value depends on the deployment strategy.
Learn more about [deploying system snapshots](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/198181573). |
| options | *object*
Optional | Specifies the behavior during deployment.
**Available options: **
- `"modifyProjectVersions"` - default value: *true*.
- `"modifyProjectComponents"` - default value: *true*.
- `"modifyProjectRoles"` - default value: *true*.
- `"modifyProjectShortcuts"` - default value: *true*.
- `"modifyGlobalPermissions"` - default value: *true*.
- `"modifyFieldDefaultValues"` - default value: *true*.
- `"modifyFieldOptions"` - default value: *true*.
- `"modifyObjectDescriptions"` - default value: *true*.
- `"modifyObjectTranslations"` - default value: *true*.
- `"modifyStatusCategories"` - default value: *true*.
- `"modifyPriorityColors"` - default value: *true*.
- `"modifyAvatars"` - default value: *true*.
- `"modifyAutomationRules"` - default value: *false*.
Learn more about the options in the [Advanced Options document](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/198021794).
**Example**:
```json
"options" : {
"modifyProjectVersions" : false,
"modifyProjectComponents" : true,
"modifyProjectRoles" : true,
"modifyProjectShortcuts" : false,
"modifyGlobalPermissions" : false,
"modifyFieldDefaultValues" : true,
"modifyFieldOptions" : true,
"modifyAvatars" : true,
"modifyAutomationRules" : false,
"modifyObjectDescriptions" : true,
"modifyObjectTranslations" : true,
"modifyStatusCategories" : false,
"modifyPriorityColors" : false,
"skipReindexing" : true
}
``` |
**Unix/macOS request **
EXAMPLE
```json
curl -u admin:admin -i -H "Content-Type: application/json" -X POST /rest/configuration-manager/api/1.7/deployments -d '
{
"scope" : "system",
"mode" : "systemRestore"
}
'
```
**Windows request**
EXAMPLE
> ℹ️ **Note** that on Windows machines, single quotes around JSON might not work. Try escaping them like "{\"name\":\"My snapshot\"...
```json
curl -u admin:admin -i -H "Content-Type: application/json" -X POST /rest/configuration-manager/api/1.7/deployments -d^
"{^
\"scope\" : \"system\",^
\"mode\" : \"systemRestore\"^
}"
```
**Responses**
BY STATUS CODE
**STATUS 201 **- Returns the id of the operation.
The** Location** header contains the URI for checking the progress of the deployment operation.
```json
HTTP/1.1 201 Created
...
Location: /rest/configuration-manager/api/1.7/deployments/1
Content-Type: application/json;charset=UTF-8
...
{
"id" : 1
}
```
**STATUS 400** - Returned if a required* *parameter is not provided.
**STATUS 403** - Returned if the user does not have permissions to create a snapshot.
---
---
This endpoint uploads the snapshot content during deployment.
The snapshot content must be provided in a part named '*file*' within a **multipart/form-data** body. After the content is successfully uploaded, the deployment process will start.
> ℹ️ Uploading a snaphot zip file is a **required step** after starting the deployment operation.
**Request**
QUERY PARAMETERS
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| file | *string*
**Required** | The snapshot file to be uploaded. |
| id
(**URI Parameter**) | *integer*
**Required** | The deployment operation id. |
REQUEST EXAMPLE
```json
curl -u admin:admin -i -X PUT /rest/configuration-manager/api/1.7/deployments/1/content -F file=@snapshot.zip
```
**Responses**
BY STATUS CODE
**STATUS 200 **- Returned when the snapshot is successfully uploaded and parsed.
**STATUS 400** - Returned if the type of the snapshot does not match the type of deployment operation.
**STATUS 403** - Returned if the user does not have permissions to create a snapshot.
---
---
Returns the status of the deployment operation with the given id.
This `"id"` is received as a response to the “*Start a deployment operation*” request.
**Request**
QUERY PARAMETERS
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| id | *integer*
**Required** | The deployment operation id. |
REQUEST EXAMPLE
```json
curl -u admin:admin -i -H "Content-Type: application/json" -X GET /rest/configuration-manager/api/1.7/deployments/1
```
**Responses**
BY STATUS CODE
**STATUS 200 **- Returns a status: `"waiting"`, `"running"`, `"failed"`, `"succeeded"`.
```json
HTTP/1.1 200 OK
...
Content-Type: application/json;charset=UTF-8
...
{
"id" : 1,
"status" : "running"
}
```
**STATUS 400** - Returned if the id is not provided.
**STATUS 403** - Returned if the user does not have permissions to create a snapshot.
**STATUS 404 **- Returned if no deployment operation with the given id is found.
> ⚠️ **Status: “waiting” **
> ⚠️
> ⚠️ You will receive the `"waiting"` status as a response in the following cases:
> ⚠️
> ⚠️ - the snapshot zip file you want to deploy is still uploading;
> ⚠️ - you haven’t uploaded a snapshot zip file.
> ⚠️
> ⚠️ Uploading a snapshot zip file is a **required** step in the deployment operation and the `"waiting"` status will not change until you provide a file.
## Issue migration
In certain situations deploying a **configuration snapshot** may require migration of issues (e.g., when a workflow status is deleted and there are issues with this status). Note that this is different than deploying a **snapshot with issues**. This is not supported by the REST API, as migration requires user input. The following response will be returned:
```
{
"id" : 1,
"status" : "failed",
"message" : "Data migration is required - automated deployment cannot continue."
}
```
In this case, the deployment will have to be performed through the user interface.
More information on issue migration can be found [here](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/197923086).
## Conflicting custom fields
Due to the fact that Jira allows the existence of multiple custom fields with the same name and type on a single system, it is not always possible to directly match custom fields on the snapshot to fields on the target system. More information on duplicate custom fields can be found [here](https://appfire.atlassian.net/wiki/display/CMJ/Duplicate+Custom+Fields). CMJ allows these conflicts to be resolved from the GUI, as described [here](https://appfire.atlassian.net/wiki/display/CMJ/Resolving+Custom+Field+Conflicts).
When using the REST API for deployment and such a case is detected, the deployment stops, and an error message is shown.
- You can perform the deployment through the [GUI](https://appfire.atlassian.net/wiki/spaces/CMJ/pages/198116696) and select the proper matching.
- If you want to perform the deployment anyway, the error severity type can be reduced to a warning showing the same message, which doesn't stop the deployment. This is controlled by the [General ](https://appfire.atlassian.net/wiki/display/CMJ/General+Settings)Settings' "Stop deployment in case of possible data loss".
- The duplicate fields on the source Jira can be temporarily renamed before creating the snapshot. The duplicate fields on the target instance can be temporarily renamed before deploying the snapshot in order to get properly matched.
## Status code 500 while creating a snapshot
If there are Integrity Check errors present, CMJ will return status code 500 with the **first***** *****error** in the body. To find all errors, use Integrity Check through the UI or REST API.
##### **Error body**
```javascript
{
"messages": [
"com.botronsoft.jira.rollout.integrity.IntegrityViolationException: Workflow 'Sales Workflow' refers to the missing custom field customfield_10201."
]
}
```