{"openapi":"3.0.0","info":{"description":"Endpoints available in Jira and Confluence cloud instances to support app migrations","version":"1.0","title":"App Migration","contact":{}},"x-atlassian-narrative":{"documents":[{"title":"Authentication and authorization","anchor":"auth","body":"Requests to these endpoints require a valid JWT token. See [this page](https://developer.atlassian.com/cloud/confluence/security-for-connect-apps/) for more information."},{"title":"Product-specific paths","anchor":"productpaths","body":"Request paths should be prefixed based on the corresponding product i.e.,\n\n* For Confluence: `your-site.atlassian.net/wiki/rest/atlassian-connect/1/migration/`\n* For Jira: `your-site.atlassian.net/rest/atlassian-connect/1/migration/`"}]},"tags":[{"name":"atlassian-connect-resource","description":""},{"name":"Notification API","description":"Provides endpoints to register/deregister your cloud app and to receive notifications about migration events. To learn more about notifications, see [Prepare your cloud app](/platform/app-migration/prepare-cloud-app/#webhooks).\n"},{"name":"Status API","description":"Provides endpoints to update the status of the transfer. To learn more, see [App migration transfers](/platform/app-migration/transfer).\n"},{"name":"Mapping API","description":"Provides endpoints to retrieve mappings\n"},{"name":"App data retrieval API","description":"Provides endpoints to access files exported from the server (files not exported as part of the migration)\n"},{"name":"Transfer retrieval API","description":"Provides endpoints to retrieve active transfers and its migration details\n"},{"name":"Feedback channel API","description":"Provides endpoints to send information from your cloud app to your server app\n"},{"name":"Error retrieval API","description":"Provides endpoints to retrieve details about errors from your server app.\n"}],"paths":{"/data/{transferId}/all":{"get":{"tags":["App data retrieval API"],"summary":"Get list of app data exports","description":"Returns all uploaded data keys for a transferId","operationId":"getUploadeds3KeysUsingGET","parameters":[{"name":"transferId","in":"path","description":"transferId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UploadedDataDto"}}}}},"400":{"description":"- Time limit to make requests using transferId has expired\n- Bad request\n"},"401":{"description":"Unauthorized"},"403":{"description":"- Transfer doesn't exist or transfer is settled; or the time limit to make requests for the transfer has expired.\n- Forbidden\n"},"404":{"description":"Not Found"}},"deprecated":false}},"/data/{s3Key}":{"get":{"tags":["App data retrieval API"],"summary":"Get app data export signed URL","description":"Returns an object containing a signed url to retrieve app data","operationId":"getMigrationObjectUsingGET","parameters":[{"name":"s3Key","in":"path","description":"s3Key","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"- Transfer doesn't exist or transfer is settled; or the time limit to make requests for the transfer has expired.\n- Forbidden\n"},"404":{"description":"Not Found"}},"deprecated":false}},"/feedback/{transferId}":{"post":{"tags":["Feedback channel API"],"summary":"Send information to server app","description":"Feeds the app migration listener back with basic info coming from cloud","operationId":"receiveFeedbackUsingPOST","parameters":[{"name":"transferId","in":"path","description":"transferId","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudFeedback"}}},"description":"cloudFeedback","required":true},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"- Time limit to make requests using transferId has expired\n- Bad request\n"},"401":{"description":"Unauthorized"},"403":{"description":"- Transfer doesn't exist or transfer is settled; or the time limit to make requests for the transfer has expired.\n- Forbidden\n"},"404":{"description":"- No feedback using transferId has been sent via cloud app\n- Not Found\n"}},"deprecated":false}},"/mapping/{transferId}/find":{"post":{"tags":["Mapping API"],"summary":"Get mappings by keys","description":"Retrieves mappings for a specific namespace filtering by the keys provided on the payload","operationId":"findByNamespaceAndKeysUsingPOST_1","parameters":[{"name":"namespace","in":"query","description":"Namespace","required":true,"allowEmptyValue":false,"schema":{"type":"string"}},{"name":"transferId","in":"path","description":"Transfer ID as UUID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}},"description":"keys","required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationMappingItem"}}}},"400":{"description":"- List contains null or empty values - Bad request\n"},"401":{"description":"Unauthorized"},"403":{"description":"- Transfer doesn't exist or transfer is settled; or the time limit to make requests for the transfer has expired.\n- Forbidden\n"},"404":{"description":"Not Found"}},"deprecated":false}},"/mapping/{transferId}/page":{"get":{"tags":["Mapping API"],"summary":"Get mappings in pages","description":"Returns mappings for a given namespace","operationId":"getMigrationContextForNamespaceUsingGET_1","parameters":[{"name":"transferId","in":"path","description":"transferId","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"namespace","in":"query","description":"namespace","required":true,"schema":{"type":"string"}},{"name":"lastEntity","in":"query","description":"lastEntity","required":false,"schema":{"type":"string"}},{"name":"pageSize","in":"query","description":"pageSize. See the [deprecation notice](/platform/app-migration/release-notes/paginated-mapping-endpoint-page-size-deprecation-notice) for upcoming change in page size.","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":5000}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationMappingDto"}}}},"400":{"description":"- PageSize value is invalid.\n- Bad request\n"},"401":{"description":"Unauthorized"},"403":{"description":"- Transfer doesn't exist or transfer is settled; or the time limit to make requests for the transfer has expired.\n- Forbidden\n"},"404":{"description":"Not Found"}},"deprecated":false}},"/transfer/recent":{"get":{"tags":["Transfer retrieval API"],"summary":"Get list of active transfers","description":"Returns a list of latest active transfers (upto 100) with migration details","operationId":"getRecentTransferUsingGET","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TransferMetadata"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/container/{transferId}/page":{"get":{"tags":["Transfer retrieval API"],"summary":"Get containers in pages","description":"Returns containers for a given container type","operationId":"getContainersByPageUsingGET_1","parameters":[{"name":"transferId","in":"path","description":"transferId","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"containerType","in":"query","description":"type of container","required":true,"schema":{"type":"string","enum":["ConfluenceSpace","JiraProject","Site"]}},{"name":"lastEntity","in":"query","description":"lastEntity","required":false,"schema":{"type":"string","format":"string"}},{"name":"pageSize","in":"query","description":"pageSize","required":false,"schema":{"type":"integer","minimum":1,"maximum":250,"default":250}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContainerFetchResponse"}}}},"400":{"description":"- PageSize value is invalid. Minimum value is 1 and maximum value is 250\n- Bad request - Time limit to make requests using transferId has expired\n"},"401":{"description":"Unauthorized"},"403":{"description":"- Transfer doesn't exist or transfer is settled; or the time limit to make requests for the transfer has expired.\n- Forbidden\n"},"404":{"description":"Not Found"}},"deprecated":false}},"/webhook":{"get":{"tags":["Notification API"],"summary":"Get all webhooks","description":"Retrieves all the webhook endpoints for a cloud site","operationId":"getWebhookUsingGET","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointsDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false},"put":{"tags":["Notification API"],"summary":"Update webhook","description":"Replaces existing URLs with a new set of URLs provided by your cloud app to receive notifications","operationId":"putWebhookUsingPUT","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointsDto"}}},"description":"Set of endpoints called after the app migration","required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointsDto"}}}},"201":{"description":"Created"},"400":{"description":"- Number of webhooks present in this request exceeds the maximum limit (5)\n- Invalid URL\n- Bad request\n"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/progress/{transferId}":{"post":{"tags":["Status API"],"summary":"Send migration progress","description":"Updates migration status for a given transfer ID. \n\n When you  [implement the listener interface](/platform/app-migration/prepare-server-app/) in your server app, your cloud app **must** use this operation to: \n\n - Report progress on your app migration so that admin users can monitor it in the Cloud Migration Assistant. \n\n - Settle the transfer at the end of your migration by updating its status to `SUCCESS`, `INCOMPLETE`, or `FAILED` so that admin users know it's finished. \n\n Once a transfer is settled, subsequent requests for that transfer ID return an HTTP 403 error.","operationId":"setProgressUsingPOST","parameters":[{"name":"transferId","in":"path","description":"Identifies the transfer. The app migration platform generates a unique transfer ID for each migration listener. \n\n Transfer IDs are published in app migration notification events, for example, the `listener-triggered` event.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgressEndpointDto"}}},"description":"progressEndpointDto","required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgressEndpointDto"}}}},"201":{"description":"Created"},"400":{"description":"- Time limit to make requests using transferId has expired\n- Bad request\n- Percent value should be in between 0 to 100\n- Field status can not be null\n"},"401":{"description":"Unauthorized"},"403":{"description":"- Transfer doesn't exist or transfer is settled; or the time limit to make requests for the transfer has expired.\n- Forbidden\n"},"404":{"description":"Not Found"}},"deprecated":false}},"/error/{transferId}":{"get":{"tags":["Error retrieval API"],"summary":"Fetch server side error","description":"**Note: This feature is available for app migrations using CCMA v3.3.7 and JCMA v1.7.2 onwards.**\n\nRetrieves details of the exception thrown from your server side listener method `onStartAppMigration`\n","operationId":"fetchServerSideExceptionUsingGET","parameters":[{"name":"transferId","in":"path","description":"transferId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferErrorDto"}}}},"400":{"description":"- Time limit to make requests using transferId has expired\n- Bad request\n"},"401":{"description":"Unauthorized"},"403":{"description":"- Transfer doesn't exist or transfer is settled; or the time limit to make requests for the transfer has expired.\n- Forbidden\n"},"404":{"description":"- No errors associated with the given transfer\n- Not Found\n"}},"deprecated":false}}},"servers":[{"url":"//your-site.atlassian.net/rest/atlassian-connect/1/migration/","description":"Jira"},{"url":"//your-site.atlassian.net/wiki/rest/atlassian-connect/1/migration/","description":"Confluence"}],"components":{"schemas":{"ConfluenceSpaceContainerV1":{"title":"ConfluenceSpaceContainerV1","allOf":[{"$ref":"#/components/schemas/ContainerV1"},{"type":"object","required":["key","type","sourceId"],"properties":{"key":{"type":"string"},"type":{"type":"string"},"sourceId":{"type":"string"}},"title":"ConfluenceSpaceContainerV1"}]},"JiraProjectContainerV1":{"title":"JiraProjectContainerV1","allOf":[{"$ref":"#/components/schemas/ContainerV1"},{"type":"object","required":["key","type","sourceId"],"properties":{"key":{"type":"string"},"type":{"type":"string"},"sourceId":{"type":"string"}},"title":"JiraProjectContainerV1"}]},"UserSelectionContainerV1":{"title":"UserSelectionContainerV1","allOf":[{"$ref":"#/components/schemas/ContainerV1"},{"type":"object","required":["type"],"properties":{"selectedUsers":{"type":"string","enum":["ALL_USERS"]},"type":{"type":"string"}},"title":"UserSelectionContainerV1"}]},"ContainerV1":{"type":"object","required":["type"],"discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string"}},"title":"ContainerV1"},"EnrichedMigrationDetailsDtoV1":{"type":"object","properties":{"cloudUrl":{"type":"string","example":"https://www.destination-cloudsite.com","description":"URL of the destination cloud site for the migration"},"confluenceClientKey":{"type":"string","example":"847e2ce1-34e0-4b3d-a487-344f3d0b2909","description":"This is the clientKey of the Confluence cloud instance, present in the installed [lifecycle callback](https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/#lifecycle) sent to your cloud application during installation"},"createdAt":{"type":"integer","format":"int64","example":1702530783417,"description":"Unix timestamp in milliseconds when the migration was created"},"jiraClientKey":{"type":"string","example":"fbc7b56e-82fd-4c43-a73b-854fa668ec49","description":"This is the clientKey of the Jira cloud instance, present in the `installed` [lifecycle callback](https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/#lifecycle) sent to your cloud application during installation"},"migrationId":{"type":"string","example":"fd2b0ea1-3e68-464e-86d7-8f34a3441c2f","description":"An ID (UUID) that the app migration platform uses to uniquely identify a migration"},"migrationScopeId":{"type":"string","example":"0bba5d1d-7b51-4e85-a6e2-31745aa65849","description":"An ID that the app migration platform generates to uniquely determine a source (server) and destination (cloud-site) of migration"},"name":{"example":"My test migration","description":"The name of the migration plan","type":"string"}},"title":"EnrichedMigrationDetailsDtoV1"},"CloudFeedback":{"type":"object","properties":{"details":{"type":"object"}},"title":"CloudFeedback"},"TransferMetadata":{"type":"object","required":["migrationDetails","transferId","status"],"properties":{"migrationDetails":{"$ref":"#/components/schemas/EnrichedMigrationDetailsDtoV1"},"transferId":{"type":"string","description":"An ID (UUID) that the app migration platform uniquely generates per migration for each listener","example":"2e170ff3-6aa6-4969-a08a-e60119ef2db3"},"status":{"type":"string","description":"The status of the migration","example":"IN_PROGRESS","enum":["IN_PROGRESS","CANCELLATION_REQUESTED"]}},"title":"TransferMetadata"},"WebhookEndpointsDto":{"type":"object","properties":{"endpoints":{"type":"array","description":"Non empty JSON array of absolute URL(s)","items":{"type":"string"}}},"title":"WebhookEndpointsDto"},"MigrationMappingDto":{"type":"object","required":["items","meta"],"properties":{"items":{"$ref":"#/components/schemas/MigrationMappingItem"},"meta":{"$ref":"#/components/schemas/MigrationMappingMeta"}},"title":"MigrationMappingDto"},"MigrationMappingItem":{"type":"object","properties":{"additionalProperties":{"type":"string"}},"title":"MigrationMappingItem"},"UploadedDataDto":{"type":"object","required":["s3Key"],"properties":{"label":{"type":"string"},"s3Key":{"type":"string"}},"title":"UploadedDataDto"},"MigrationMappingMeta":{"type":"object","required":["hasNext","pageSize"],"properties":{"hasNext":{"type":"boolean"},"lastEntity":{"type":"string"},"pageSize":{"type":"integer","format":"int32"}},"title":"MigrationMappingMeta"},"ProgressEndpointDto":{"type":"object","required":["status"],"properties":{"status":{"description":"The migration status of the transfer. \n\n Use one of these values:\n\n - `IN_PROGRESS`: We recommend reporting progress about once a minute.\n\n - `SUCCESS`: Use when the migration runs to completion and all entities are successfully migrated.\n\n - `INCOMPLETE`: Use when the migration finishes but some entities are not migrated or when the migration  is cancelled (see [Transfer cancellation](/platform/app-migration/transfer-cancellation/)).\n\n - `FAILED`: Use when the migration doesn't run to completion because it encounters a problem.","type":"string","enum":["IN_PROGRESS","SUCCESS","FAILED","INCOMPLETE"]},"percent":{"type":"integer","description":"The percent complete for the transfer. If not provided (or set as zero), the previous value will be kept. \n\n The status update is ignored when the value of `percent` is less than the value in a previous update. \n\n When the result of a migration is `SUCCESS`, set `percent` to 100. Otherwise, set the value to an integer between 1 and 99 that represents the proportion of entities migrated.","format":"int32","minimum":0,"maximum":100,"example":90},"message":{"type":"string","description":"A progress message for the transfer.\n\n Messages can't contain more than 65,536 characters. Messages that exceed this limit are truncated to 65,536 characters, and the following string is appended: `<truncated, message too large>`.","example":"App data migration is in the last stage. For more info, refer to http://documentation.example.com."}},"title":"ProgressEndpointDto"},"ContainerResponseMeta":{"type":"object","required":["hasNext","pageSize"],"properties":{"hasNext":{"type":"boolean"},"lastEntity":{"type":"string"},"pageSize":{"type":"integer","format":"int32"}},"title":"ContainerResponseMeta"},"ContainerFetchResponse":{"type":"object","required":["containers","meta"],"properties":{"containers":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ContainerV1"}},"meta":{"$ref":"#/components/schemas/ContainerResponseMeta"}},"title":"ContainerFetchResponse"},"TransferErrorDto":{"type":"object","required":["exceptionType","safeStackTrace"],"properties":{"exceptionType":{"type":"string","description":"Type of the exception"},"safeStackTrace":{"type":"string","description":"Stack trace of the exception (obfuscated for privacy reasons)"}},"title":"TransferErrorDto"}}}}