Last updated Jan 25, 2024

Update product links with REST API

You update links by scheduling jobs. Every job represents a separate link update that updates all existing and compatible links found in the product you chose to update. If you later migrate more data into this product, you can schedule another job to update links included in this data.

You can run as many jobs as you need, the already updated links will be omitted.

Before you begin

Here are some prerequisites:

Authentication

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:

1
2
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:

1
2
$YOUR_EMAIL:$YOUR_API_TOKEN

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

1
2
curl -u "$YOUR_EMAIL:$YOUR_API_TOKEN" ...

You need to use a different API endpoint depending on how the destination product was migrated:

  • Jira Cloud Migration Assistant (any migration option) or Confluence Cloud Migration Assistant
  • Jira site import

If you migrated products from a staging or backup instance, you can use an additional parameter to specify the URL of the corresponding production instance. We've noticed that's quite a common case.

Cloud migration assistant migrations

Use this section if the destination product was migrated with the Jira Cloud Migration Assistant (any migration option) or the Confluence Cloud Migration Assistant.

To schedule a job, use the following request:

1
2
curl \
  -u "$YOUR_EMAIL:YOUR_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -XPOST "https://api.atlassian.com/links/v1/${SITE_ID}/jobs/cma" \
  --data "$REQUEST_BODY"

Request body

ParameterDescription
productThe cloud product that has links you want to update: Jira or Confluence. The default is Jira.
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.
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

1
2
{
    "product":               "jira",
    "productURL":            "https://jira.atlassian.net",
    "destinationURL":        "https://confluence.atlassian.net",
    "migratedFrom":          "https://confluence-datacenter.com",
    "migratedFromOverride":  "https://confluence-dc-production.com",
    "createBackup":          "true"
}

Example full request

1
2
export YOUR_EMAIL=charlie@atlassian.com
export YOUR_API_TOKEN=21Iv4we2ZtoLixXX21OUQiF06a
export SITE_ID=b436336f-99ce-2fbc-4520-7301132h1674
export REQUEST_BODY="{
    \"product\":                 \"jira\",
    \"productURL\":              \"https://jira.atlassian.net\",
    \"destinationURL\":          \"https://confluence.atlassian.net\",
    \"migratedFrom\":            \"https://confluence-datacenter.com\",
    \"migratedFromOverride\":    \"https://confluence-dc-production.com\",
    \"createBackup\":            \"true\"
}"
 
curl \
  -u "$YOUR_EMAIL:$YOUR_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -XPOST "https://api.atlassian.com/links/v1/${SITE_ID}/jobs/cma" \
  --data "$REQUEST_BODY"

Jira site import

Use this section if the destination product was migrated using the Jira site import.

To schedule a job, use the following request:

1
2
curl \
  -u "$YOUR_EMAIL:YOUR_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -XPOST "https://api.atlassian.com/links/v1/${SITE_ID}/jobs/non-cma" \
  --data "$REQUEST_BODY"

Request body

ParameterDescription
productURLThe Jira Cloud where you update the links. Make sure the URL doesn’t include the jira context path
destinationURLThe URL of the cloud product that will be a new destination for links. We’ll update existing links to this URL.
migratedFromThe Base URL of the Server or Data Center instance from which you migrated data to the destination product represented by destinationURL.

Example request body

1
2
{
    "productURL":             "https://jira.atlassian.net",
    "destinationURL":         "https://confluence.atlassian.net",
    "migratedFrom":           "https://confluence-datacenter.com",
}

Example full request

1
2
export YOUR_EMAIL=charlie@atlassian.com
export YOUR_API_TOKEN=21Iv4we2ZtoLixXX21OUQiF06a
export SITE_ID=b436336f-99ce-2fbc-4520-7301132h1674
export REQUEST_BODY="{
    \"productURL\":       \"https://jira.atlassian.net\",
    \"destinationURL\":   \"https://confluence.atlassian.net\",
    \"migratedFrom\":     \"https://confluence-datacenter.com\",
}"
 
curl \
  -u "$YOUR_EMAIL:$YOUR_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -XPOST "https://api.atlassian.com/links/v1/${SITE_ID}/jobs/non-cma" \
  --data "$REQUEST_BODY"

Next steps

Check the status and results

Rate this page: