Last updated Feb 28, 2024

Update links to federated instances

When you split a single Jira Server or Data Center instance into multiple instances in cloud, links between issues that were previously local won’t exist after the migration. You can use REST API to recreate them as remote links. They will be updated to their new destinations at the same time.

Before you begin


You can recreate your links only for 2 weeks after the migration. Afterwards, the migration data that we use to identify those links is deleted for privacy reasons.


You can recreate links to federated instances only for Jira. Confluence and page links aren’t supported.

When you use this REST API, it will recreate and update links that were previously local, including issue links and links in user-generated content. For other links, for example links to other products, you can use the same REST API or the Product links view from Recreating links is supported only through REST API.


Here are additional prerequisites:


Your requests will be authenticated via HTTP basic auth by using your personal API token. You need to attach the following header to each request:

Authorization: Basic $BASE64_TOKEN

The $BASE64_TOKEN is a base64 encoded string that consists of your email address and API token, like in the following snippet:


That’s a standard basic auth header. You can generate it by using, for example, curl:


Before you can run a link update, you need to authorize the app links. This is only required when you’re recreating the links, it’s not needed for regular link updates.

To authorize the app link:

  1. Open the Jira instance that has links you want to update.

  2. Open any issue and start creating an issue link. To do this, select Link issue.

  3. Expand the Local drop-down and search for the destination Jira instance.

  4. Select Authorize and search, and follow instructions on the screen.

You don’t need to complete the issue link, but only authorize the access to the federated instance. If you’re updating links on multiple federated instances, repeat these steps on each of them.

You will use the same REST API resources as for other link updates, with an additional recreateAsRemote parameter.

To run a link update, use the following request:

curl \
  -H 'Content-Type: application/json' \
  -XPOST "${SITE_ID}/jobs/cma" \
  --data "$REQUEST_BODY"

Request body

productThe cloud product that has links you want to update: Jira or Confluence. The default is Jira. You will run a separate update for every federated instance.
productURLThe URL of the cloud product that has links you want to update.
destinationURLThe 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).
migratedFromThe Base URL of the Server or Data Center instance from which you migrated data to the destination product represented by destinationURL.
migratedFromOverride(Optional) If you migrated from a staging or backup instance, provide the Base URL of the corresponding production instance so we can properly map the links. If you migrated from a production instance, skip this parameter.
recreateAsRemoteThis parameter recreates local links as remote ones. It’s required for this case.
createBackupWhen set to true, we’ll create a backup of your Jira Cloud instance before updating links. The default is false. Available only for Jira Cloud.

Example request body

    "product":               "jira",
    "productURL":            "",
    "destinationURL":        "",
    "migratedFrom":          "",
    "migratedFromOverride":  "",
    "recreateAsRemote":      "true",
    "createBackup":          "true"

Example full request

export YOUR_API_TOKEN=21Iv4we2ZtoLixXX21OUQiF06a
export SITE_ID=b436336f-99ce-2fbc-4520-7301132h1674
export REQUEST_BODY="{
    \"product\":                 \"jira\",
    \"productURL\":              \"\",
    \"destinationURL\":          \"\",
    \"migratedFrom\":            \"\",
    \"migratedFromOverride\":    \"\",
    \"recreateAsRemote\":        \"true\",
    \"createBackup\":            \"true\"
curl \
  -H 'Content-Type: application/json' \
  -XPOST "${SITE_ID}/jobs/cma" \
  --data "$REQUEST_BODY"

Next steps

Check the status and results

Rate this page: