---
title: "Create or update remote issue link"
method: POST
path: "/rest/api/3/issue/{issueIdOrKey}/remotelink"
tags: ["Issue remote links"]
---

# Create or update remote issue link

`POST /rest/api/3/issue/{issueIdOrKey}/remotelink`

Creates or updates a remote issue link for an issue.

If a `globalId` is provided and a remote issue link with that global ID is found it is updated. Any fields without values in the request are set to null. Otherwise, the remote issue link is created.

This operation requires [issue linking to be active](https://confluence.atlassian.com/x/yoXKM).

This operation can be accessed anonymously.

**[Permissions](#permissions) required:**

 *  *Browse projects* and *Link issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
 *  If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.

## Path parameters

- `issueIdOrKey` string, required

## Request body

- RemoteIssueLinkRequest — Details of a remote issue link.
  - `application` Application — The application the linked item is in.
    - `name` string — The name of the application. Used in conjunction with the (remote) object icon title to display a tooltip for the link's icon. The tooltip takes the format "\[application name\] icon title". Blank items are excluded from the tooltip title. If both items are blank, the icon tooltop displays as "Web Link". Grouping and sorting of links may place links without an application name last.
    - `type` string — The name-spaced type of the application, used by registered rendering apps.
  - `globalId` string — An identifier for the remote item in the remote system. For example, the global ID for a remote item in Confluence would consist of the app ID and page ID, like this: `appId=456&pageId=123`. Setting this field enables the remote issue link details to be updated or deleted using remote system and item details as the record identifier, rather than using the record's Jira ID. The maximum length is 255 characters.
  - `object` RemoteObject, required — The linked item.
    - `icon` Icon — An icon. If no icon is defined: * for a status icon, no status icon displays in Jira. * for the remote object icon, the default link icon displays in Jira.
      - `link` string — The URL of the tooltip, used only for a status icon. If not set, the status icon in Jira is not clickable.
      - `title` string — The title of the icon. This is used as follows: * For a status icon it is used as a tooltip on the icon. If not set, the status icon doesn't display a tooltip in Jira. * For the remote object icon it is used in conjunction with the application name to display a tooltip for the link's icon. The tooltip takes the format "\[application name\] icon title". Blank itemsare excluded from the tooltip title. If both items are blank, the icon tooltop displays as "Web Link".
      - `url16x16` string — The URL of an icon that displays at 16x16 pixel in Jira.
    - `status` Status — The status of the item.
      - `icon` Icon — An icon. If no icon is defined: * for a status icon, no status icon displays in Jira. * for the remote object icon, the default link icon displays in Jira.
        - `link` string — The URL of the tooltip, used only for a status icon. If not set, the status icon in Jira is not clickable.
        - `title` string — The title of the icon. This is used as follows: * For a status icon it is used as a tooltip on the icon. If not set, the status icon doesn't display a tooltip in Jira. * For the remote object icon it is used in conjunction with the application name to display a tooltip for the link's icon. The tooltip takes the format "\[application name\] icon title". Blank itemsare excluded from the tooltip title. If both items are blank, the icon tooltop displays as "Web Link".
        - `url16x16` string — The URL of an icon that displays at 16x16 pixel in Jira.
      - `resolved` boolean — Whether the item is resolved. If set to "true", the link to the issue is displayed in a strikethrough font, otherwise the link displays in normal font.
    - `summary` string — The summary details of the item.
    - `title` string, required — The title of the item.
    - `url` string, required — The URL of the item.
  - `relationship` string — Description of the relationship between the issue and the linked item. If not set, the relationship description "links to" is used in Jira.

## Response `200`

Returned if the remote issue link is updated.

- RemoteIssueLinkIdentifies — Details of the identifiers for a created or updated remote issue link.
  - `id` integer — The ID of the remote issue link, such as the ID of the item on the remote system.
  - `self` string — The URL of the remote issue link.

## Other responses

- `201` — Returned if the remote issue link is created.
- `400` — Returned if the request is invalid.
- `401` — Returned if the authentication credentials are incorrect or missing.
- `403` — Returned if the user does not have permission to link issues.
- `404` — Returned if the issue is not found or the user does not have permission to view the issue.

---

[API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api-2/revisions/5a51740d7ab3/schema)