Last updated Nov 10, 2023

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:

You need to be an organization admin or site admin.
You need to be an admin of the product that has links you want to update.
You need to create an app link between the product and destination product (cloud). If both live in the same cloud site, the app link should be created automatically.
You need to generate an API token in cloud. Generate API token
You'll need to provide your Site ID in most APIs. To get it, go to https://{SITE_URL}/_edge/tenant_info, for example https://jira.atlassian.net/_edge/tenant_info

Federated instances

To update links between federated instances, you’ll need to use an additional parameter. We’ve prepared a separate page that describes this case only. Learn how to update links to federated instances

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" ...

Schedule a job to update links

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

Parameter	Description
product	The cloud product that has links you want to update: Jira or Confluence. The default is Jira.
productURL	The URL of the cloud product that has links you want to update.
destinationURL	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	The 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.
createBackup	When 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"

Next steps

Check the status and results