{"openapi":"3.0.1","info":{"title":"Migration REST API","description":"REST API related to migrations from Server or Data Center to Cloud.","version":"v1"},"security":[{"basicAuth":[]}],"tags":[{"name":"Link fixing","description":"APIs for updating links after Data Center to Cloud or Cloud to Cloud migrations"}],"paths":{"/jobs/cma":{"post":{"tags":["Link fixing"],"summary":"Update links","description":"Updates links that go to a a destination product (Jira, Confluence) that was migrated from Data Center or a different Cloud site.","operationId":"scheduleFixingLinksJob_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FBLCmaJobRequestDTO"}}},"required":true},"responses":{"200":{"description":"A link update has been scheduled. You should receive an ID that you can use to check the status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledJobDTO"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/jobs/status/{jobId}":{"get":{"tags":["Link fixing"],"summary":"Get status by ID","description":"Returns the status of a link update by ID.","operationId":"getStatus","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusDTO"}}}}}}},"/jobs/status":{"get":{"tags":["Link fixing"],"summary":"Get status by product","description":"Returns the statuses of all link updates performed for a given product.","operationId":"getStatuses","parameters":[{"name":"product","in":"query","required":true,"schema":{"type":"string"}},{"name":"productURL","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/JobStatusDTO"}}}}}}}},"/jobs/products/{orgId}":{"get":{"tags":["Link fixing"],"summary":"Get products by an organization","description":"Returns the list of all products in an organization. You can use it to help you find products that might have links to update.","operationId":"getProductsToFix","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"pattern":"^[a-zA-Z\\d-:]+$","type":"string"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductDTO"}}}}}}}},"/report/links":{"post":{"tags":["Link fixing"],"summary":"Export audit log","description":"Exports the audit log that shows every successful link modification for a given product from the last 29 days.","operationId":"exportLinksHistory","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequestDTO"}}},"required":true},"responses":{"202":{"description":"The audit log is being generated. When completed, you'll receive an email with the download link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestDescriptiveResultDTO"}}}}}}},"/report/jobs":{"post":{"tags":["Link fixing"],"summary":"Export history report","description":"Exports the history report that shows the summary of all link updates for a given product and their summarized results.","operationId":"exportJobsHistory","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequestDTO"}}},"required":true},"responses":{"202":{"description":"The history report is being generated. When completed, you'll receive an email with the download link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestDescriptiveResultDTO"}}}}}}}},"servers":[{"url":"https://api.atlassian.com/links/v1/{siteId}"}],"x-atlassian-narrative":{"documents":[{"title":"About","anchor":"About","body":"The link fixing REST API provides resources related to updating Jira issue links and Confluence page links after migrating from Data Center to Cloud or from Cloud to Cloud."},{"title":"Authentication","anchor":"auth","body":"Authentication is implemented via an API key. Use the API key as a Bearer access token\n\n[Learn how to create an API key](https://id.atlassian.com/manage-profile/security/api-tokens)."},{"title":"Rate limits","anchor":"rate limits","body":"A rate limit defines the maximum number of API calls an application or user can perform during a specific time frame. When this threshold is surpassed, or if CPU or total time constraints are exceeded, the application or user might encounter delays. Consequently, API requests initiated by the user or application will not succeed.\n\nIt is essential to note that all API requests are subjected to rate limits.\n\nWhen a client breach the rate limit thresholds, they get [HTTP 429 Too Many Requests](https://datatracker.ietf.org/doc/html/rfc6585#section-4) responses. The client has to wait for the rate limit counter to reset on the server before being able to make successful requests.\n\n**Rate limit response headers**\n\nThe following HTTP response headers are returned indicating the rate and threshold allowed for a client for each endpoint.\n- **X-RateLimit-Limit:** The number of allowed requests in the current period\n- **X-RateLimit-Remaining:** The number of remaining requests in the current period\n- **X-RateLimit-Reset:** Next period reset time (ISO 8601 - Date and time in UTC)"},{"title":"Version and URI","anchor":"uri","body":"\nThe URIs for resources have the following structure.\n\n```\nhttps://api.atlassian.com/links/v1/{siteId}/<resource-name>\n```"}]},"components":{"securitySchemes":{"basicAuth":{"description":"You can access this resource via basic auth.","scheme":"basic","type":"http"}},"schemas":{"ReportRequestDTO":{"required":["product","productURL"],"type":"object","properties":{"product":{"type":"string","description":"Product name, Jira or Confluence."},"productURL":{"type":"string","description":"URL of a cloud product that has links you want to update."}}},"RequestDescriptiveResultDTO":{"type":"object","properties":{"result":{"type":"string","description":"result"}}},"ScheduledJobDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"ID of a link update"}}},"ErrorResponse":{"required":["errorMessage","id","status"],"type":"object","properties":{"id":{"type":"string","description":"Error ID"},"status":{"type":"integer","description":"Error status code","format":"int32"},"errorMessage":{"type":"string","description":"Error message"},"errors":{"type":"array","description":"Possible reasons for returning a given error.","items":{"type":"string","description":"Possible reasons for returning a given error."}}}},"FBLCmaJobRequestDTO":{"required":["product","productURL","destinationURL","migratedFrom"],"type":"object","properties":{"product":{"type":"string","description":"Product name, Jira or Confluence."},"productURL":{"type":"string","description":"The URL of the cloud product that has links you want to update."},"destinationURL":{"type":"string","description":"The URL of the cloud product that will be a new destination for links. We'll update existing links to this URL. It can be a different cloud product (remote links) or the same as the one you're updating (local links)."},"migratedFrom":{"type":"string","description":"The base URL of the Data Center or Cloud instance from which you migrated data to the destination product. **Important:** If you're updating links to Confluence Cloud migrated from another Cloud site (Cloud to Cloud migrations), you must add the \"/wiki\" suffix to the URL, for example \"https://mysite.atlassian.net/wiki\". The Base URL without this suffix defaults to Jira if it lives under the same URL."},"migratedFromOverride":{"type":"string","description":"(Optional) If you migrated from a staging or backup instance, provide the base URL of the corresponding production instance so we can properly remap the links. If you migrated from a production instance, skip this paramter."},"recreateAsRemote":{"type":"boolean","description":"(Optional) Use this parameter if you migrated a single product into multiple instances in cloud (federation). In this case, links between issues that were previously local need to be recreated as remote links. This type of links can be updated only for 2 weeks after the migration."},"createBackup":{"type":"boolean","description":"When set to true, the backup will be created before updating links. The default is false. Available only for Jira Cloud."}}},"CmaJobRecommendation":{"type":"object","properties":{"destinationUrl":{"type":"string"},"migratedFrom":{"type":"string"}}},"JobsRecommendation":{"type":"object","properties":{"siteId":{"type":"string"},"siteUrl":{"type":"string"},"generatedAt":{"type":"string"},"jobsToRunForJira":{"uniqueItems":true,"type":"array","items":{"$ref":"#/components/schemas/CmaJobRecommendation"}},"jobsToRunForConfluence":{"uniqueItems":true,"type":"array","items":{"$ref":"#/components/schemas/CmaJobRecommendation"}}}},"ErrorDTO":{"type":"object","properties":{"error":{"type":"string","enum":["UNAUTHENTICATED_ERROR","FORBIDDEN_ERROR","ENDPOINT_NOT_ENABLED","CLOUD_SITE_NOT_FOUND","APPLICATION_LINK_NOT_FOUND","NO_MIGRATIONS_FOUND","CONFLUENCE_TASK_ERROR","INTERNAL_ERROR","MIGRATION_SCOPES_WITH_DIFFERENT_PRODUCT_FAMILIES","BACKUP_CREATION_FAILED"]},"description":{"type":"string"},"details":{"type":"string"},"productUri":{"type":"string"}}},"JobRequestDetailsDTO":{"type":"object","properties":{"product":{"type":"string","enum":["JIRA","CONFLUENCE"]},"productURL":{"type":"string","format":"uri"},"destinationURL":{"type":"string","format":"uri"},"migratedFrom":{"type":"string","format":"uri"},"createBackup":{"type":"boolean"}}},"JobStatusDTO":{"type":"object","properties":{"id":{"type":"string","description":"ID of a link update."},"status":{"type":"string","enum":["PENDING","BACKUP","IN_PROGRESS","COMPLETE","RETRY","ERROR"]},"error":{"$ref":"#/components/schemas/ErrorDTO"},"linksMigrationResults":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/LinkTypeMigrationStatus"}},"startTimeEpoch":{"type":"integer","format":"int64","example":1701432850},"endTimeEpoch":{"type":"integer","format":"int64","example":1701432850},"jobRequestDetails":{"$ref":"#/components/schemas/JobRequestDetailsDTO"}}},"LinkTypeMigrationStatus":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","BACKUP","IN_PROGRESS","COMPLETE","RETRY","ERROR"]},"result":{"$ref":"#/components/schemas/LinksMigrationResult"},"error":{"type":"string","enum":["UNAUTHENTICATED_ERROR","FORBIDDEN_ERROR","ENDPOINT_NOT_ENABLED","CLOUD_SITE_NOT_FOUND","APPLICATION_LINK_NOT_FOUND","NO_MIGRATIONS_FOUND","CONFLUENCE_TASK_ERROR","INTERNAL_ERROR","MIGRATION_SCOPES_WITH_DIFFERENT_PRODUCT_FAMILIES","BACKUP_CREATION_FAILED"]}}},"LinksMigrationResult":{"type":"object","properties":{"updatedCount":{"type":"integer","format":"int32"},"skippedCount":{"type":"integer","format":"int32"},"failedCount":{"type":"integer","format":"int32"},"remainingCount":{"type":"integer","format":"int32"},"replacementStatsByLinkType":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ReplacementStats"}},"aggregatedLinksReplacementStats":{"$ref":"#/components/schemas/ReplacementStats"}}},"ReplacementStats":{"type":"object","properties":{"updatedCount":{"type":"integer","format":"int32"},"failed":{"type":"object","additionalProperties":{"type":"integer","format":"int32"}}}},"ProductDTO":{"type":"object","properties":{"siteId":{"type":"string"},"siteURL":{"type":"string","format":"uri"},"lastMigrationTimeEpoch":{"type":"integer","format":"int64","example":1701432850},"lastLinksUpdateTimeEpoch":{"type":"integer","format":"int64","example":1701432850},"lastLinksUpdateStatus":{"type":"string","enum":["PENDING","BACKUP","IN_PROGRESS","COMPLETE","RETRY","COMPLETED_WITH_ERRORS","ERROR"]},"scopes":{"uniqueItems":true,"type":"array","items":{"$ref":"#/components/schemas/ReducedMigrationScopeDTO"}},"productFamily":{"type":"string","enum":["JIRA","CONFLUENCE"]},"sandbox":{"type":"boolean"},"productKey":{"type":"string"},"productName":{"type":"string"}}},"ReducedMigrationScopeDTO":{"type":"object","properties":{"migratedFrom":{"type":"string"},"destinationURL":{"type":"string"},"productFamily":{"type":"string","enum":["JIRA","CONFLUENCE"]}}}}}}