{"openapi":"3.0.1","info":{"title":"Migration Public APIs","version":"v1"},"servers":[{"url":"https://api.atlassian.com"}],"tags":[{"name":"Migration job","description":"A migration job is a wrapper object describing a migration. This description includes a flow, such as `jira-onpremises-to-cloud`, the name of your migration, source, destination, and scope. Use this resource to create new jobs or get existing ones."},{"name":"Migration task","description":"Use migration task resources to execute migration tasks or run pre-flight checks. Tasks are aggregated under a job."},{"name":"Migration task status","description":"Use these APIs to check the status of existing migration tasks. The response is in the form of a status tree, where the root level contains the overall status. You can also drill down on the details of the status to see which pre-migration checks failed and which spaces/projects failed or were successful. Because the response could contain a lot of statuses, this API returns paginated responses. For more details, see this [guide](/platform/migration-api/guides/migrate-jira-or-confluence-to-cloud-using-api/#7--check-the-status-of-your-tasks)."},{"name":"Artifacts","description":"Use artifact resources to access artifacts related to a task."}],"paths":{"/migrations/public/v1/jobs":{"post":{"tags":["Migration job"],"summary":"Create migration job","description":"Use this resource to create new migration jobs. Creating a job returns a `jobId`, which you can then use to execute pre-migration checks as well as migrations. <br>Rate limit: 5 requests per minute.","operationId":"createJob","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobDefinition"},"examples":{"Jira request to migrate three projects and all the associated data.":{"description":"Jira request to migrate three projects and all the associated data.","value":{"flow":"jira-onpremises-to-cloud","source":{"serverId":"0123456789"},"destination":{"url":"https://username.jira-dev.com"},"scope":{"projects":{"includedKeys":["ABC","DEF","XYZ"],"includedData":"all"}}}},"Jira request to migrate three projects, all the users present in server, two provided apps, and all the AR plans.":{"description":"Jira request to migrate three projects, all the users present in server, two provided apps, and all the AR plans.","value":{"name":"Sample migration","flow":"jira-onpremises-to-cloud","source":{"serverId":"0123456789"},"destination":{"url":"https://username.jira-dev.com"},"scope":{"projects":{"includedKeys":[],"includedData":"all"},"usersAndGroups":{"mode":"referenced","preserveMemberships":"true","includeUsersInGroups":false,"includeRoleActors":false},"jsm":{"customers":{"mode":"referenced"}},"ar":{"mode":"none"},"apps":{"includedKeys":[]}}}},"Confluence request to migrate three spaces, all the users present in server, and two provided apps.":{"description":"Confluence request to migrate three spaces, all the users present in server, and two provided apps.","value":{"flow":"confluence-onpremises-to-cloud","name":"Sample migration","source":{"serverId":"0123456789"},"destination":{"url":"https://username.jira-dev.com"},"scope":{"spaces":{"includedKeys":["ABC","DEF","XYZ"],"includedData":"all"},"usersAndGroups":{"mode":"all"},"apps":{"includedKeys":["awesome-app-key","another-awesome-app-key"]}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJobResponse"}}}}}}},"/migrations/public/v1/jobs/{jobId}/tasks":{"get":{"tags":["Migration task"],"summary":"Get migration tasks by job","description":"Returns all the tasks for the given `jobId`, sorted in descending order of creation. Response is paginated with 20 entries per page. <br>Rate limit: 600 requests per minute.","operationId":"getAllTaskDetails","parameters":[{"name":"jobId","in":"path","description":"ID of the job from which to get tasks.","required":true,"schema":{"type":"string","description":"ID of the job from which to get tasks."}},{"name":"cursor","in":"query","description":"Cursor value for pagination. Use one of the values provided in the `links` field of the response.","required":false,"schema":{"type":"string","description":"Cursor value for pagination. Use one of the values provided in the `links` field of the response."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAllTaskResponse"}}}}}},"post":{"tags":["Migration task"],"summary":"Create migration task","description":"Use this API to create new tasks. A task can either be a pre-migration check or a migration. The endpoint returns a `taskId`, which you can later use to check the status and definition of your tasks. <br>Rate limit: 5 requests per minute.","operationId":"createTask","parameters":[{"name":"jobId","in":"path","description":"ID of the job under which to create the new task.","required":true,"schema":{"type":"string","description":"ID of the job under which to create the new task."}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskRequest"},"examples":{"Task for executing checks":{"description":"Task for executing checks","value":{"task":"check"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskResponse"}}}}}}},"/migrations/public/v1/jobs/{jobId}":{"get":{"tags":["Migration job"],"summary":"Get migration job","description":"Use this resource to get the details of an existing job. <br>Rate limit: 600 requests per minute.","operationId":"getJobDetails","parameters":[{"name":"jobId","in":"path","description":"ID of the job whose details to get.","required":true,"schema":{"type":"string","description":"ID of the job whose details to get."}}],"responses":{"default":{"description":"default response","content":{"application/json":{"examples":{"Response to a Jira request with all default values.":{"description":"Response to a Jira request with all default values.","value":{"name":"Sample migration","flow":"jira-onpremises-to-cloud","source":{"serverId":"0123456789"},"destination":{"url":"https://username.jira-dev.com"},"scope":{"projects":{"includedKeys":[],"includedData":"all"},"usersAndGroups":{"mode":"referenced","preserveMemberships":"true","includeUsersInGroups":false,"includeRoleActors":false},"jsm":{"customers":{"mode":"referenced"}},"ar":{"mode":"none"},"apps":{"includedKeys":[]}}}},"Response to a Confluence request with all default values.":{"description":"Response to a Confluence request with all default values.","value":{"name":"Sample migration","flow":"jira-onpremises-to-cloud","source":{"serverId":"0123456789"},"destination":{"url":"https://username.jira-dev.com"},"scope":{"projects":{"includedKeys":[],"includedData":"all"},"usersAndGroups":{"mode":"referenced","preserveMemberships":"true","includeUsersInGroups":false,"includeRoleActors":false},"jsm":{"customers":{"mode":"referenced"}},"ar":{"mode":"none"},"apps":{"includedKeys":[]}}}}}}}}}}},"/migrations/public/v1/jobs/{jobId}/tasks/{taskId}":{"get":{"tags":["Migration task"],"summary":"Get migration task","description":"Returns the definition of a specific task within a job. Requires both a `jobId` and a `taskId`. <br>Rate limit: 600 requests per minute.","operationId":"getTaskDetails","parameters":[{"name":"jobId","in":"path","description":"ID of the job from which to get your task.","required":true,"schema":{"type":"string","description":"ID of the job from which to get your task."}},{"name":"taskId","in":"path","description":"ID of the task to get.","required":true,"schema":{"type":"string","description":"ID of the task to get."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTaskResponse"}}}}}}},"/migrations/public/v1/jobs/{jobId}/tasks/{taskId}/status":{"get":{"tags":["Migration task status"],"summary":"Get migration task status","description":"Returns the status of the indicated task within a job. <br>Rate limit: 600 requests per minute.","operationId":"getTaskStatus","parameters":[{"name":"jobId","in":"path","description":"ID of the job under which your task is grouped.","required":true,"schema":{"type":"string","description":"ID of the job under which your task is grouped."}},{"name":"taskId","in":"path","description":"ID of the task to get.","required":true,"schema":{"type":"string","description":"ID of the task to get."}},{"name":"expandChildren","in":"query","description":"Whether to expand child tasks.","required":false,"schema":{"type":"string","description":"Whether to expand child tasks."}},{"name":"level","in":"query","description":"How deep a task is nested. For example, a `migrate` task's level can be `[migrate]` or `[migrate, usersAndGroups]`.","required":false,"schema":{"type":"string","description":"How deep a task is nested. For example, a `migrate` task's level can be `[migrate]` or `[migrate, usersAndGroups]`."}},{"name":"status","in":"query","description":"Indicates where in its lifecycle a task is. See [here](/platform/migration-api/guides/migrate-jira-or-confluence-to-cloud-using-api/#pre-migration-check-statuses-and-outcomes) for more information.","required":false,"schema":{"type":"string","description":"Indicates where in its lifecycle a task is. See [here](/platform/migration-api/guides/migrate-jira-or-confluence-to-cloud-using-api/#pre-migration-check-statuses-and-outcomes) for more information."}},{"name":"outcome","in":"query","description":"Indicates the outcome of a finished task. See [here](/platform/migration-api/guides/migrate-jira-or-confluence-to-cloud-using-api/#pre-migration-check-statuses-and-outcomes) for more information.","required":false,"schema":{"type":"string","description":"Indicates the outcome of a finished task. See [here](/platform/migration-api/guides/migrate-jira-or-confluence-to-cloud-using-api/#pre-migration-check-statuses-and-outcomes) for more information."}},{"name":"cursor","in":"query","description":"Cursor value for pagination. Use one of the values provided in the `links` field of the response.","required":false,"schema":{"type":"string","description":"Cursor value for pagination. Use one of the values provided in the `links` field of the response."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskStatusPaginatedResponse"}}}}}}},"/migrations/public/v1/artifacts/{artifactId}":{"get":{"tags":["Artifacts"],"summary":"Get artifact","description":"Use this API to download the artifact file.<br>Rate limit: 20 requests per minute.","operationId":"getArtifact","parameters":[{"name":"artifactId","in":"path","description":"ID of the artifact.","required":true,"schema":{"type":"string","description":"ID of the artifact."}}],"responses":{"200":{"description":"OK","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}}}}}},"components":{"schemas":{"CloudSite":{"required":["url"],"type":"object","properties":{"cloudId":{"type":"string","readOnly":true},"url":{"type":"string","format":"url"}}},"JobDefinition":{"required":["destination","flow","scope","source"],"type":"object","properties":{"flow":{"type":"string","description":"Flow type for your migration. Can be either `confluence-onpremises-to-cloud` or `jira-onpremises-to-cloud`."},"name":{"type":"string","description":"Name of your migration. Will be displayed in the UI."},"source":{"$ref":"#/components/schemas/Site"},"destination":{"$ref":"#/components/schemas/Site"},"scope":{"$ref":"#/components/schemas/Scope"}}},"ServerSite":{"required":["serverId"],"type":"object","properties":{"serverId":{"type":"string"}}},"Site":{"type":"object","description":"Migration destination site. Accepts `serverId` for server sites and `url` for cloud sites.","oneOf":[{"$ref":"#/components/schemas/ServerSite"},{"$ref":"#/components/schemas/CloudSite"}]},"CreateJobResponse":{"required":["jobDefinition","jobId"],"type":"object","properties":{"jobId":{"type":"string","description":"Job ID.","format":"uuid","example":"0bacecde-372e-4d84-8d79-d66433b8fa45"},"jobDefinition":{"$ref":"#/components/schemas/JobDefinition"}}},"CreateTaskRequest":{"required":["task"],"type":"object","properties":{"task":{"$ref":"#/components/schemas/TaskTypes"},"options":{"$ref":"#/components/schemas/TaskOptions"}}},"CreateTaskResponse":{"required":["taskId"],"type":"object","properties":{"taskId":{"type":"string","description":"Task ID.","format":"uuid","example":"0bacecde-372e-4d84-8d79-d66433b8fa45"}}},"Artifact":{"required":["expireAt","location","name"],"type":"object","properties":{"name":{"type":"string","description":"Name of the artifact."},"location":{"type":"string","description":"Download link of the artifact. Downloading an artifact requires the same access as running its respective migration job."},"expireAt":{"type":"integer","description":"Timestamp when this artifact will be deleted.","format":"int64"}},"description":"Artifacts generated as a result of task execution. For example `migration-error-logs.zip` is generated when a `migrate` task fails or partially complete. This is available since JCMA version - 1.12.2 & CCMA version - 3.10.5"},"GetAllTaskResponse":{"required":["data","links"],"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GetTaskResponse"}},"links":{"$ref":"#/components/schemas/GetAllTaskResponseCursors"}}},"GetAllTaskResponseCursors":{"type":"object","properties":{"next":{"type":"string","description":"Cursor values to query next page"},"self":{"type":"string","description":"Cursor values to query existing page"}},"description":"Cursor values for the pagination"},"GetTaskResponse":{"required":["createdAt","taskId","taskType"],"type":"object","properties":{"taskId":{"type":"string","format":"uuid"},"taskType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"payload":{"$ref":"#/components/schemas/TaskOptions"},"results":{"$ref":"#/components/schemas/Results"}}},"Results":{"type":"object","properties":{"artifacts":{"type":"array","description":"Artifacts generated as a result of task execution. For example `migration-error-logs.zip` is generated when a `migrate` task fails or partially complete. This is available since JCMA version - 1.12.2 & CCMA version - 3.10.5","items":{"$ref":"#/components/schemas/Artifact"}}},"description":"Results associated with execution of the task."},"Progress":{"required":["isSupported"],"type":"object","properties":{"isSupported":{"type":"boolean","description":"`True` if progress is supported for the given node."},"percent":{"type":"number","format":"double"},"data":{"type":"array","description":"Granular progress data associated with the node.","items":{"$ref":"#/components/schemas/ProgressData"}}},"description":"This contains progress associated with the node. Only supported for the jira-onpremises-to-cloud flow."},"ProgressData":{"required":["name","processed","total"],"type":"object","properties":{"name":{"type":"string","description":"Represents the name of a granular entity."},"total":{"type":"integer","description":"Total number of entities to be processed.","format":"int32"},"processed":{"type":"integer","description":"Count of total entities that have been processed.","format":"int32"}},"description":"Granular progress data associated with the node."},"StatusNode":{"type":"object","properties":{"status":{"type":"string","description":"Entity execution status.\nPENDING - Waiting for execution, IN_PROGRESS - Being executed now, SUSPENDED - Execution is paused, FINISHED - Execution is completed","enum":["PENDING","IN_PROGRESS","SUSPENDED","FINISHED"]},"outcome":{"type":"string","description":"Execution outcome, only applies to entities with the FINISHED status.\nSUCCESS - Completed successfully without errors, FAILED - Execution failed, INCOMPLETE - Execution completed with errors, WARNING - Execution completed with warnings, SKIPPED - Entity wasn't executed, CANCELLED - Execution was cancelled","enum":["SUCCESS","FAILED","INCOMPLETE","WARNING","SKIPPED","CANCELLED"]},"message":{"type":"string"},"details":{"$ref":"#/components/schemas/StatusDetails"},"progressDetails":{"$ref":"#/components/schemas/Progress"},"children":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/StatusNode"}}}},"TaskStatusCursors":{"type":"object","properties":{"next":{"type":"string","description":"Cursor value to query next page."},"self":{"type":"string","description":"Cursor value to query existing page."}},"description":"Cursor value for pagination."},"TaskStatusPaginatedResponse":{"required":["links"],"type":"object","properties":{"data":{"$ref":"#/components/schemas/StatusNode"},"links":{"$ref":"#/components/schemas/TaskStatusCursors"}}},"ConfluenceOnpremisesToCloudScope":{"type":"object","properties":{"spaces":{"type":"object","properties":{"includedKeys":{"type":"array","items":{"type":"string"},"default":"[]"},"includedData":{"type":"string","default":"ALL","enum":["ALL","ATTACHMENTS"]}},"description":"Provide keys of spaces to migrate and decide whether to migrate `all` data or just `attachments`."},"usersAndGroups":{"type":"object","properties":{"mode":{"type":"string","description":"UgMigrationMode \n* `ALL` - Migrate all users and groups. \n* `REFERENCED` - Migrate users and groups referenced in space data.","default":"REFERENCED","enum":["ALL","REFERENCED"]}},"description":"Whether to migrate all users or only referenced users."},"apps":{"type":"object","properties":{"includedKeys":{"type":"array","items":{"type":"string"},"default":"[]"}},"description":"Accepts an array of app keys to be migrated."},"globalEntities":{"type":"object","properties":{"includedTypes":{"type":"array","items":{"type":"string","enum":["GLOBAL_PAGE_TEMPLATES","CUSTOM_SYSTEM_TEMPLATES"]},"default":"[]"}},"description":"Which types of global entities to migrate."}}},"JiraOnpremisesToCloudScope":{"type":"object","properties":{"projects":{"type":"object","properties":{"includedKeys":{"type":"array","items":{"type":"string"},"default":"[]"},"includedData":{"type":"string","default":"ALL","enum":["ALL","ATTACHMENTS"]},"includeArchivedIssues":{"type":"boolean","description":"Whether to include issues that have been archived in the selected projects.\nSupported since JCMA version - 1.11.4","default":true}},"description":"Which project keys to migrate and which data to include (`all` or `attachments` only)."},"usersAndGroups":{"type":"object","properties":{"mode":{"type":"string","description":"UgMigrationMode \n* `ALL` - Migrate all users and groups. \n* `REFERENCED` - Migrate users and groups referenced in project data.\n* `NONE` - Don't migrate any users and groups.","default":"REFERENCED","enum":["ALL","REFERENCED","NONE"]},"preserveMemberships":{"type":"boolean","default":true},"includeUsersInGroups":{"type":"boolean","default":false},"includeRoleActors":{"type":"boolean","default":false}},"description":"How to deal with users and groups. `mode` decides which users to migrate: `all`, `referenced`, or `none`. You can also indicate whether to `preserveMemberships`, `incldueUsersInGroups`, and `includeRoleActors`."},"jsm":{"type":"object","properties":{"customers":{"type":"object","properties":{"mode":{"type":"string","description":"JsmCustomerMigrationMode \n* `ALL` - Migrate all customers. \n* `REFERENCED` - Migrate customers referenced in project data.\n* `NONE` - Don't migrate customers.","default":"REFERENCED","enum":["ALL","REFERENCED","NONE"]}}}},"description":"How to deal with JSM customers. `mode` decides which customers to migrate: `all`, `referenced`, or `none`."},"ar":{"type":"object","properties":{"mode":{"type":"string","default":"NONE","enum":["ALL","NONE"]}},"description":"Whether to migrate Advanced Roadmaps (AR) properties."},"apps":{"type":"object","properties":{"includedKeys":{"type":"array","items":{"type":"string"},"default":"[]"}},"description":"App keys to migrate."},"dashboards":{"type":"object","properties":{"mode":{"type":"string","default":"SCOPED","enum":["ALL","SCOPED","NONE"]}},"description":"Whether to migrate dashboards. By default only dashboards linked to selected projects specified in gadgets or dashboard permissions will be migrated. This will not include dashboards that are not linked to any projects. To migrate such dashboards, use the All Dashboards option. Some projects related to dashboards may not have been selected for migration. You can continue migrating these dashboards. We'll relink when you migrate them again, along with their associated projects. After migration, some dashboard gadgets may not work because certain gadgets on the server are either third-party or not currently supported in the cloud. Learn more about migrating dashboards - https://support.atlassian.com/migration/docs/how-cross-project-boards-and-filters-are-migrated/\nSupported since JCMA version - 1.11.16"},"boardsAndFilters":{"type":"object","properties":{"mode":{"type":"string","description":"BoardsAndFiltersMigrationMode \n* `ALL` - All filters and cross-project boards - This includes all filters (both single and cross-project) and cross-project boards, irrespective of their shared access.\n* `SCOPED` - Only boards and filters shared with selected projects - This includes both single and cross-project boards and filters that have been shared with the projects selected for migration.\n* `NONE`","default":"SCOPED","enum":["ALL","SCOPED","NONE"]}},"description":"How to migrate boards and filters. By default only boards and filters shared with selected projects will be migrated. Some boards and filters could be related to multiple projects, including ones you've not selected for migration. You can continue to migrate these boards and filters, we will relink them when the relevant projects are migrated to cloud. Learn more about migrating boards and filters - https://support.atlassian.com/migration/docs/how-cross-project-boards-and-filters-are-migrated/\nSupported since JCMA version - 1.11.4"}}},"Scope":{"oneOf":[{"$ref":"#/components/schemas/ConfluenceOnpremisesToCloudScope"},{"$ref":"#/components/schemas/JiraOnpremisesToCloudScope"}]},"ConfluenceOnpremisesToCloudTaskOptions":{"oneOf":[{"$ref":"#/components/schemas/ConfluenceOnpremisesToCloudCheckOptions"},{"$ref":"#/components/schemas/ConfluenceOnpremisesToCloudMigrateOptions"}]},"JiraOnpremisesToCloudTaskOptions":{"oneOf":[{"$ref":"#/components/schemas/JiraOnpremisesToCloudCheckOptions"},{"$ref":"#/components/schemas/JiraOnpremisesToCloudMigrateOptions"}]},"ConfluenceOnpremisesToCloudCheckOptions":{"type":"object","properties":{"checkTypes":{"required":["excludeKeys","includeKeys"],"type":"object","properties":{"includeKeys":{"type":"array","items":{"type":"string"}},"excludeKeys":{"type":"array","items":{"type":"string"}}}}}},"ConfluenceOnpremisesToCloudMigrateOptions":{"type":"object","properties":{}},"JiraOnpremisesToCloudCheckOptions":{"type":"object","properties":{"checkTypes":{"required":["excludeKeys","includeKeys"],"type":"object","properties":{"includeKeys":{"type":"array","items":{"type":"string"}},"excludeKeys":{"type":"array","items":{"type":"string"}}}}}},"JiraOnpremisesToCloudMigrateOptions":{"type":"object","properties":{}},"ConfluenceOnpremisesToCloudTaskTypes":{"properties":{" ":{"type":"string","enum":["check","migrate"]}}},"JiraOnpremisesToCloudTaskTypes":{"properties":{" ":{"type":"string","enum":["check","migrate"]}}},"TaskTypes":{"anyOf":[{"$ref":"#/components/schemas/ConfluenceOnpremisesToCloudTaskTypes"},{"$ref":"#/components/schemas/JiraOnpremisesToCloudTaskTypes"}]},"TaskOptions":{"oneOf":[{"$ref":"#/components/schemas/ConfluenceOnpremisesToCloudCheckOptions"},{"$ref":"#/components/schemas/ConfluenceOnpremisesToCloudMigrateOptions"},{"$ref":"#/components/schemas/JiraOnpremisesToCloudCheckOptions"},{"$ref":"#/components/schemas/JiraOnpremisesToCloudMigrateOptions"}]},"CheckStatusDetails":{"type":"object","properties":{"occurrences":{"maxLength":100,"type":"array","description":"Top 100 of objects that violated the check","example":"List of Confluence space or Jira project keys that already exist in the destination site","items":{"type":"string"}}},"description":"Detailed check outcome"},"StatusDetails":{"oneOf":[{"$ref":"#/components/schemas/CheckStatusDetails"}]}}}}