openapi: 3.1.0
info:
title: Atlassian Admin Account Issue Links API
description: The Atlassian Admin API provides programmatic access to manage Atlassian organizations, users, domains, policies, and events. It enables administrators to automate organization management tasks, integrate with identity providers, and ensure appropriate access to Atlassian products.
version: 1.0.0
contact:
name: Atlassian Developer
url: https://developer.atlassian.com/cloud/admin/
license:
name: Atlassian Developer Terms
url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
x-logo:
url: https://wac-cdn.atlassian.com/assets/img/favicons/atlassian/favicon.png
servers:
- url: https://api.atlassian.com
description: Atlassian Cloud API
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Issue Links
paths:
/rest/api/3/issueLink/{linkId}:
delete:
deprecated: false
description: Deletes an issue link.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* Browse project [project permission](https://confluence.atlassian.com/x/yodKLg) for all the projects containing the issues in the link.
* *Link issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for at least one of the projects containing issues in the link.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, permission to view both of the issues.
operationId: atlassianDeleteissuelink
parameters:
- description: The ID of the issue link.
in: path
name: linkId
required: true
schema:
type: string
responses:
'200':
description: 200 response
'204':
description: Returned if the request is successful.
'400':
description: Returned if the issue link ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: "Returned if:\n\n * issue linking is disabled.\n * the issue link is not found.\n * the user doesn't have the required permissions."
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Delete Issue Link
tags:
- Issue Links
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- scheme: OAuth2
scopes:
- delete:issue-link:jira
state: Beta
x-atlassian-connect-scope: DELETE
get:
deprecated: false
description: Returns an issue link.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse project* [project permission](https://confluence.atlassian.com/x/yodKLg) for all the projects containing the linked issues.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, permission to view both of the issues.
operationId: atlassianGetissuelink
parameters:
- description: The ID of the issue link.
in: path
name: linkId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example: '{"id":"10001","inwardIssue":{"fields":{"issuetype":{"avatarId":10002,"description":"A problem with the software.","entityId":"9d7dd6f7-e8b6-4247-954b-7b2c9b2a5ba2","hierarchyLevel":0,"iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10316&avatarType=issuetype\",","id":"1","name":"Bug","scope":{"project":{"id":"10000"},"type":"PROJECT"},"self":"https://your-domain.atlassian.net/rest/api/3/issueType/1","subtask":false},"priority":{"description":"Very little impact.","iconUrl":"https://your-domain.atlassian.net/images/icons/priorities/trivial.png","id":"2","name":"Trivial","self":"https://your-domain.atlassian.net/rest/api/3/priority/5","statusColor":"#cfcfcf"},"status":{"description":"The issue is closed.","iconUrl":"https://your-domain.atlassian.net/images/icons/closed.gif","id":"5","name":"Closed","self":"https://your-domain.atlassian.net/rest/api/3/status/5","statusCategory":{"colorName":"green","id":9,"key":"completed","self":"https://your-domain.atlassian.net/rest/api/3/statuscategory/9"}}},"id":"10004","key":"PR-3","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-3"},"outwardIssue":{"fields":{"issuetype":{"avatarId":1,"description":"A task that needs to be done.","hierarchyLevel":0,"iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10299&avatarType=issuetype\",","id":"3","name":"Task","self":"https://your-domain.atlassian.net/rest/api/3/issueType/3","subtask":false},"priority":{"description":"Major loss of function.","iconUrl":"https://your-domain.atlassian.net/images/icons/priorities/major.png","id":"1","name":"Major","self":"https://your-domain.atlassian.net/rest/api/3/priority/3","statusColor":"#009900"},"status":{"description":"The issue is currently being worked on.","iconUrl":"https://your-domain.atlassian.net/images/icons/progress.gif","id":"10000","name":"In Progress","self":"https://your-domain.atlassian.net/rest/api/3/status/10000","statusCategory":{"colorName":"yellow","id":1,"key":"in-flight","name":"In Progress","self":"https://your-domain.atlassian.net/rest/api/3/statuscategory/1"}}},"id":"10004L","key":"PR-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-2"},"type":{"id":"1000","inward":"Duplicated by","name":"Duplicate","outward":"Duplicates","self":"https://your-domain.atlassian.net/rest/api/3/issueLinkType/1000"}}'
schema:
$ref: '#/components/schemas/IssueLink'
description: Returned if the request is successful.
'400':
description: Returned if the issue link ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: "Returned if:\n\n * issue linking is disabled.\n * the issue link is not found.\n * the user doesn't have the required permissions."
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Get Issue Link
tags:
- Issue Links
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:field:jira
- read:issue-link-type:jira
- read:issue:jira
- read:issue-type:jira
- read:priority:jira
- read:status:jira
- read:avatar:jira
- read:issue.time-tracking:jira
- read:project-category:jira
- read:project:jira
- read:user:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/issueLink:
post:
deprecated: false
description: Creates a link between two issues. Use this operation to indicate a relationship between two issues and optionally add a comment to the from (outward) issue. To use this resource the site must have [Issue Linking](https://confluence.atlassian.com/x/yoXKM) enabled.
This resource returns nothing on the creation of an issue link. To obtain the ID of the issue link, use `https://your-domain.atlassian.net/rest/api/3/issue/[linked issue key]?fields=issuelinks`.
If the link request duplicates a link, the response indicates that the issue link was created. If the request included a comment, the comment is added.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse project* [project permission](https://confluence.atlassian.com/x/yodKLg) for all the projects containing the issues to be linked,
* *Link issues* [project permission](https://confluence.atlassian.com/x/yodKLg) on the project containing the from (outward) issue,
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the comment has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: atlassianLinkissues
parameters: []
requestBody:
content:
application/json:
example:
comment:
body:
content:
- content:
- text: Linked related issue!
type: text
type: paragraph
type: doc
version: 1
visibility:
identifier: 276f955c-63d7-42c8-9520-92d01dca0625
type: group
value: jira-software-users
inwardIssue:
key: HSP-1
outwardIssue:
key: MKY-1
type:
name: Duplicate
schema:
$ref: '#/components/schemas/LinkIssueRequestJsonBean'
description: The issue link request.
required: true
responses:
'201':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
description: Returned if the comment is not created. The response contains an error message indicating why the comment wasn't created. The issue link is also not created.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: "Returned if:\n\n * issue linking is disabled.\n * the user cannot view one or both of the issues. For example, the user doesn't have *Browse project* project permission for a project containing one of the issues.\n * the user does not have *link issues* project permission.\n * either of the link issues are not found.\n * the issue link type is not found."
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Create Issue Link
tags:
- Issue Links
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- scheme: OAuth2
scopes:
- write:comment:jira
- write:issue:jira
- write:issue-link:jira
state: Beta
x-atlassian-connect-scope: WRITE
components:
schemas:
Fields:
additionalProperties: false
description: Key fields from the linked issue.
properties:
assignee:
allOf:
- $ref: '#/components/schemas/UserDetails'
description: The assignee of the linked issue.
readOnly: true
issueType:
allOf:
- $ref: '#/components/schemas/IssueTypeDetails'
description: The type of the linked issue.
readOnly: true
issuetype:
description: The type of the linked issue.
$ref: '#/components/schemas/IssueTypeDetails'
priority:
allOf:
- $ref: '#/components/schemas/Priority'
description: The priority of the linked issue.
readOnly: true
status:
allOf:
- $ref: '#/components/schemas/StatusDetails'
description: The status of the linked issue.
readOnly: true
summary:
description: The summary description of the linked issue.
readOnly: true
type: string
timetracking:
allOf:
- $ref: '#/components/schemas/TimeTrackingDetails'
description: The time tracking of the linked issue.
readOnly: true
type: object
TimeTrackingDetails:
additionalProperties: false
description: Time tracking details.
properties:
originalEstimate:
description: The original estimate of time needed for this issue in readable format.
readOnly: true
type: string
originalEstimateSeconds:
description: The original estimate of time needed for this issue in seconds.
format: int64
readOnly: true
type: integer
remainingEstimate:
description: The remaining estimate of time needed for this issue in readable format.
readOnly: true
type: string
remainingEstimateSeconds:
description: The remaining estimate of time needed for this issue in seconds.
format: int64
readOnly: true
type: integer
timeSpent:
description: Time worked on this issue in readable format.
readOnly: true
type: string
timeSpentSeconds:
description: Time worked on this issue in seconds.
format: int64
readOnly: true
type: integer
type: object
Visibility:
additionalProperties: true
description: The group or role to which this item is visible.
properties:
identifier:
description: The ID of the group or the name of the role that visibility of this item is restricted to.
nullable: true
type: string
type:
description: Whether visibility of this item is restricted to a group or role.
enum:
- group
- role
type: string
value:
description: The name of the group or role that visibility of this item is restricted to. Please note that the name of a group is mutable, to reliably identify a group use `identifier`.
type: string
type: object
IssueLinkType:
additionalProperties: false
description: "This object is used as follows:\n\n * In the [ issueLink](#api-rest-api-3-issueLink-post) resource it defines and reports on the type of link between the issues. Find a list of issue link types with [Get issue link types](#api-rest-api-3-issueLinkType-get).\n * In the [ issueLinkType](#api-rest-api-3-issueLinkType-post) resource it defines and reports on issue link types."
properties:
id:
description: "The ID of the issue link type and is used as follows:\n\n * In the [ issueLink](#api-rest-api-3-issueLink-post) resource it is the type of issue link. Required on create when `name` isn't provided. Otherwise, read only.\n * In the [ issueLinkType](#api-rest-api-3-issueLinkType-post) resource it is read only."
type: string
inward:
description: "The description of the issue link type inward link and is used as follows:\n\n * In the [ issueLink](#api-rest-api-3-issueLink-post) resource it is read only.\n * In the [ issueLinkType](#api-rest-api-3-issueLinkType-post) resource it is required on create and optional on update. Otherwise, read only."
type: string
name:
description: "The name of the issue link type and is used as follows:\n\n * In the [ issueLink](#api-rest-api-3-issueLink-post) resource it is the type of issue link. Required on create when `id` isn't provided. Otherwise, read only.\n * In the [ issueLinkType](#api-rest-api-3-issueLinkType-post) resource it is required on create and optional on update. Otherwise, read only."
type: string
outward:
description: "The description of the issue link type outward link and is used as follows:\n\n * In the [ issueLink](#api-rest-api-3-issueLink-post) resource it is read only.\n * In the [ issueLinkType](#api-rest-api-3-issueLinkType-post) resource it is required on create and optional on update. Otherwise, read only."
type: string
self:
description: The URL of the issue link type. Read only.
format: uri
readOnly: true
type: string
type: object
LinkedIssue:
additionalProperties: false
description: The ID or key of a linked issue.
properties:
fields:
allOf:
- $ref: '#/components/schemas/Fields'
description: The fields associated with the issue.
readOnly: true
id:
description: The ID of an issue. Required if `key` isn't provided.
type: string
key:
description: The key of an issue. Required if `id` isn't provided.
type: string
self:
description: The URL of the issue.
format: uri
readOnly: true
type: string
type: object
IssueLink:
additionalProperties: false
description: Details of a link between issues.
properties:
id:
description: The ID of the issue link.
readOnly: true
type: string
inwardIssue:
allOf:
- $ref: '#/components/schemas/LinkedIssue'
description: Provides details about the linked issue. If presenting this link in a user interface, use the `inward` field of the issue link type to label the link.
outwardIssue:
allOf:
- $ref: '#/components/schemas/LinkedIssue'
description: Provides details about the linked issue. If presenting this link in a user interface, use the `outward` field of the issue link type to label the link.
self:
description: The URL of the issue link.
format: uri
readOnly: true
type: string
type:
allOf:
- $ref: '#/components/schemas/IssueLinkType'
description: The type of link between the issues.
required:
- inwardIssue
- outwardIssue
- type
type: object
xml:
name: issueLinks
Scope:
additionalProperties: true
description: The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO).
properties:
project:
allOf:
- $ref: '#/components/schemas/ProjectDetails'
description: The project the item has scope in.
readOnly: true
type:
description: The type of scope.
enum:
- PROJECT
- TEMPLATE
readOnly: true
type: string
type: object
StatusDetails:
additionalProperties: true
description: A status.
properties:
description:
description: The description of the status.
readOnly: true
type: string
iconUrl:
description: The URL of the icon used to represent the status.
readOnly: true
type: string
id:
description: The ID of the status.
readOnly: true
type: string
name:
description: The name of the status.
readOnly: true
type: string
scope:
allOf:
- $ref: '#/components/schemas/Scope'
description: The scope of the field.
readOnly: true
self:
description: The URL of the status.
readOnly: true
type: string
statusCategory:
allOf:
- $ref: '#/components/schemas/StatusCategory'
description: The category assigned to the status.
readOnly: true
type: object
Comment:
additionalProperties: true
description: A comment.
properties:
author:
allOf:
- $ref: '#/components/schemas/UserDetails'
description: The ID of the user who created the comment.
readOnly: true
body:
description: The comment text in [Atlassian Document Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).
created:
description: The date and time at which the comment was created.
format: date-time
readOnly: true
type: string
id:
description: The ID of the comment.
readOnly: true
type: string
jsdAuthorCanSeeRequest:
description: Whether the comment was added from an email sent by a person who is not part of the issue. See [Allow external emails to be added as comments on issues](https://support.atlassian.com/jira-service-management-cloud/docs/allow-external-emails-to-be-added-as-comments-on-issues/)for information on setting up this feature.
readOnly: true
type: boolean
jsdPublic:
description: Whether the comment is visible in Jira Service Desk. Defaults to true when comments are created in the Jira Cloud Platform. This includes when the site doesn't use Jira Service Desk or the project isn't a Jira Service Desk project and, therefore, there is no Jira Service Desk for the issue to be visible on. To create a comment with its visibility in Jira Service Desk set to false, use the Jira Service Desk REST API [Create request comment](https://developer.atlassian.com/cloud/jira/service-desk/rest/#api-rest-servicedeskapi-request-issueIdOrKey-comment-post) operation.
readOnly: true
type: boolean
properties:
description: A list of comment properties. Optional on create and update.
items:
$ref: '#/components/schemas/EntityProperty'
type: array
renderedBody:
description: The rendered version of the comment.
readOnly: true
type: string
self:
description: The URL of the comment.
readOnly: true
type: string
updateAuthor:
allOf:
- $ref: '#/components/schemas/UserDetails'
description: The ID of the user who updated the comment last.
readOnly: true
updated:
description: The date and time at which the comment was updated last.
format: date-time
readOnly: true
type: string
visibility:
allOf:
- $ref: '#/components/schemas/Visibility'
description: The group or role to which this comment is visible. Optional on create and update.
type: object
UpdatedProjectCategory:
additionalProperties: false
description: A project category.
properties:
description:
description: The name of the project category.
readOnly: true
type: string
id:
description: The ID of the project category.
readOnly: true
type: string
name:
description: The description of the project category.
readOnly: true
type: string
self:
description: The URL of the project category.
readOnly: true
type: string
type: object
UserDetails:
additionalProperties: false
description: "User details permitted by the user's Atlassian Account privacy settings. However, be aware of these exceptions:\n\n * User record deleted from Atlassian: This occurs as the result of a right to be forgotten request. In this case, `displayName` provides an indication and other parameters have default values or are blank (for example, email is blank).\n * User record corrupted: This occurs as a results of events such as a server import and can only happen to deleted users. In this case, `accountId` returns *unknown* and all other parameters have fallback values.\n * User record unavailable: This usually occurs due to an internal service outage. In this case, all parameters have fallback values."
properties:
accountId:
description: The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*.
maxLength: 128
type: string
accountType:
description: The type of account represented by this user. This will be one of 'atlassian' (normal users), 'app' (application user) or 'customer' (Jira Service Desk customer user)
readOnly: true
type: string
active:
description: Whether the user is active.
readOnly: true
type: boolean
avatarUrls:
allOf:
- $ref: '#/components/schemas/AvatarUrlsBean'
description: The avatars of the user.
readOnly: true
displayName:
description: The display name of the user. Depending on the user’s privacy settings, this may return an alternative value.
readOnly: true
type: string
emailAddress:
description: The email address of the user. Depending on the user’s privacy settings, this may be returned as null.
readOnly: true
type: string
key:
description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details.
readOnly: true
type: string
name:
description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details.
readOnly: true
type: string
self:
description: The URL of the user.
readOnly: true
type: string
timeZone:
description: The time zone specified in the user's profile. Depending on the user’s privacy settings, this may be returned as null.
readOnly: true
type: string
type: object
StatusCategory:
additionalProperties: true
description: A status category.
properties:
colorName:
description: The name of the color used to represent the status category.
readOnly: true
type: string
id:
description: The ID of the status category.
format: int64
readOnly: true
type: integer
key:
description: The key of the status category.
readOnly: true
type: string
name:
description: The name of the status category.
readOnly: true
type: string
self:
description: The URL of the status category.
readOnly: true
type: string
type: object
Priority:
additionalProperties: true
description: An issue priority.
properties:
description:
description: The description of the issue priority.
type: string
iconUrl:
description: The URL of the icon for the issue priority.
type: string
id:
description: The ID of the issue priority.
type: string
isDefault:
description: Whether this priority is the default.
type: boolean
name:
description: The name of the issue priority.
type: string
self:
description: The URL of the issue priority.
type: string
statusColor:
description: The color used to indicate the issue priority.
type: string
type: object
LinkIssueRequestJsonBean:
additionalProperties: false
properties:
comment:
$ref: '#/components/schemas/Comment'
inwardIssue:
$ref: '#/components/schemas/LinkedIssue'
outwardIssue:
$ref: '#/components/schemas/LinkedIssue'
type:
$ref: '#/components/schemas/IssueLinkType'
required:
- inwardIssue
- outwardIssue
- type
type: object
EntityProperty:
additionalProperties: false
description: An entity property, for more information see [Entity properties](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
properties:
key:
description: The key of the property. Required on create and update.
type: string
value:
description: The value of the property. Required on create and update.
type: object
AvatarUrlsBean:
additionalProperties: false
properties:
16x16:
description: The URL of the item's 16x16 pixel avatar.
format: uri
type: string
24x24:
description: The URL of the item's 24x24 pixel avatar.
format: uri
type: string
32x32:
description: The URL of the item's 32x32 pixel avatar.
format: uri
type: string
48x48:
description: The URL of the item's 48x48 pixel avatar.
format: uri
type: string
type: object
ProjectDetails:
additionalProperties: false
description: Details about a project.
properties:
avatarUrls:
allOf:
- $ref: '#/components/schemas/AvatarUrlsBean'
description: The URLs of the project's avatars.
readOnly: true
id:
description: The ID of the project.
type: string
key:
description: The key of the project.
readOnly: true
type: string
name:
description: The name of the project.
readOnly: true
type: string
projectCategory:
allOf:
- $ref: '#/components/schemas/UpdatedProjectCategory'
description: The category the project belongs to.
readOnly: true
projectTypeKey:
description: The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project.
enum:
- software
- service_desk
- business
readOnly: true
type: string
self:
description: The URL of the project details.
readOnly: true
type: string
simplified:
description: Whether or not the project is simplified.
readOnly: true
type: boolean
type: object
IssueTypeDetails:
additionalProperties: false
description: Details about an issue type.
properties:
avatarId:
description: The ID of the issue type's avatar.
format: int64
readOnly: true
type: integer
description:
description: The description of the issue type.
readOnly: true
type: string
entityId:
description: Unique ID for next-gen projects.
format: uuid
readOnly: true
type: string
hierarchyLevel:
description: Hierarchy level of the issue type.
format: int32
readOnly: true
type: integer
iconUrl:
description: The URL of the issue type's avatar.
readOnly: true
type: string
id:
description: The ID of the issue type.
readOnly: true
type: string
name:
description: The name of the issue type.
readOnly: true
type: string
scope:
allOf:
- $ref: '#/components/schemas/Scope'
description: Details of the next-gen projects the issue type is available in.
readOnly: true
self:
description: The URL of these issue type details.
readOnly: true
type: string
subtask:
description: Whether this issue type is used to create subtasks.
readOnly: true
type: boolean
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: Use an Atlassian API key as a Bearer token. Create API keys at https://admin.atlassian.com.
oauth2:
type: oauth2
description: OAuth 2.0 authorization for Atlassian Cloud APIs.
flows:
authorizationCode:
authorizationUrl: https://auth.atlassian.com/authorize
tokenUrl: https://auth.atlassian.com/oauth/token
scopes:
read:org:admin: Read organization information.
write:org:admin: Modify organization settings.
read:user:admin: Read user information.
write:user:admin: Modify user accounts.
read:policy:admin: Read organization policies.
write:policy:admin: Modify organization policies.
read:event:admin: Read organization events.
externalDocs:
description: Atlassian Admin REST API Documentation
url: https://developer.atlassian.com/cloud/admin/organization/rest/intro/