Atlassian Jira Issue API
The Atlassian Jira Issue API enables creating, updating, deleting, and querying issues within Jira including comments, attachments, and transitions.
OpenAPI Specification
components:
schemas:
IssueArchivalSyncResponse:
additionalProperties: false
description: >-
Number of archived/unarchived issues and list of errors that occurred
during the action, if any.
properties:
errors:
$ref: '#/components/schemas/Errors'
numberOfIssuesUpdated:
format: int64
type: integer
type: object
IssueCreateMetadata:
additionalProperties: false
description: The wrapper for the issue creation metadata for a list of projects.
properties:
expand:
description: >-
Expand options that include additional project details in the
response.
readOnly: true
type: string
xml:
attribute: true
projects:
description: List of projects and their issue creation metadata.
items:
$ref: '#/components/schemas/ProjectIssueCreateMetadata'
readOnly: true
type: array
type: object
PageOfCreateMetaIssueTypes:
additionalProperties: true
description: A page of CreateMetaIssueTypes.
properties:
createMetaIssueType:
items:
$ref: '#/components/schemas/IssueTypeIssueCreateMetadata'
type: array
writeOnly: true
issueTypes:
description: The list of CreateMetaIssueType.
items:
$ref: '#/components/schemas/IssueTypeIssueCreateMetadata'
readOnly: true
type: array
maxResults:
description: The maximum number of items to return per page.
format: int32
readOnly: true
type: integer
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The total number of items in all pages.
format: int64
readOnly: true
type: integer
type: object
PageOfCreateMetaIssueTypeWithField:
additionalProperties: true
description: A page of CreateMetaIssueType with Field.
properties:
fields:
description: The collection of FieldCreateMetaBeans.
items:
$ref: '#/components/schemas/FieldCreateMetadata'
readOnly: true
type: array
maxResults:
description: The maximum number of items to return per page.
format: int32
readOnly: true
type: integer
results:
items:
$ref: '#/components/schemas/FieldCreateMetadata'
type: array
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The total number of items in all pages.
format: int64
readOnly: true
type: integer
type: object
IssuePickerSuggestions:
additionalProperties: false
description: A list of issues suggested for use in auto-completion.
properties:
sections:
description: >-
A list of issues for an issue type suggested for use in
auto-completion.
items:
$ref: '#/components/schemas/IssuePickerSuggestionsIssueType'
readOnly: true
type: array
type: object
BulkIssueIsWatching:
additionalProperties: false
description: A container for the watch status of a list of issues.
properties:
issuesIsWatching:
additionalProperties:
readOnly: true
type: boolean
description: The map of issue ID to boolean watch status.
readOnly: true
type: object
type: object
IssueBean:
additionalProperties: false
description: Details about an issue.
properties:
changelog:
allOf:
- $ref: '#/components/schemas/PageOfChangelogs'
description: Details of changelogs associated with the issue.
readOnly: true
editmeta:
allOf:
- $ref: '#/components/schemas/IssueUpdateMetadata'
description: The metadata for the fields on the issue that can be amended.
readOnly: true
expand:
description: >-
Expand options that include additional issue details in the
response.
readOnly: true
type: string
xml:
attribute: true
fields:
additionalProperties: {}
type: object
fieldsToInclude:
$ref: '#/components/schemas/IncludedFields'
id:
description: The ID of the issue.
readOnly: true
type: string
key:
description: The key of the issue.
readOnly: true
type: string
names:
additionalProperties:
readOnly: true
type: string
description: The ID and name of each field present on the issue.
readOnly: true
type: object
operations:
allOf:
- $ref: '#/components/schemas/Operations'
description: The operations that can be performed on the issue.
readOnly: true
properties:
additionalProperties:
readOnly: true
description: Details of the issue properties identified in the request.
readOnly: true
type: object
renderedFields:
additionalProperties:
readOnly: true
description: The rendered value of each field present on the issue.
readOnly: true
type: object
schema:
additionalProperties:
$ref: '#/components/schemas/JsonTypeBean'
description: The schema describing each field present on the issue.
readOnly: true
type: object
self:
description: The URL of the issue details.
format: uri
readOnly: true
type: string
transitions:
description: The transitions that can be performed on the issue.
items:
$ref: '#/components/schemas/IssueTransition'
readOnly: true
type: array
versionedRepresentations:
additionalProperties:
additionalProperties:
readOnly: true
readOnly: true
type: object
description: The versions of each field on the issue.
readOnly: true
type: object
type: object
xml:
name: issue
PageBeanChangelog:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/Changelog'
readOnly: true
type: array
type: object
PageOfChangelogs:
additionalProperties: false
description: A page of changelogs.
properties:
histories:
description: The list of changelogs.
items:
$ref: '#/components/schemas/Changelog'
readOnly: true
type: array
maxResults:
description: The maximum number of results that could be on the page.
format: int32
readOnly: true
type: integer
startAt:
description: The index of the first item returned on the page.
format: int32
readOnly: true
type: integer
total:
description: The number of results on the page.
format: int32
readOnly: true
type: integer
type: object
PageOfComments:
additionalProperties: true
description: A page of comments.
properties:
comments:
description: The list of comments.
items:
$ref: '#/components/schemas/Comment'
readOnly: true
type: array
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
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
IssueUpdateMetadata:
description: A list of editable field details.
properties:
fields:
additionalProperties:
$ref: '#/components/schemas/FieldMetadata'
readOnly: true
type: object
type: object
PropertyKeys:
additionalProperties: false
description: List of property keys.
properties:
keys:
description: Property key details.
items:
$ref: '#/components/schemas/PropertyKey'
readOnly: true
type: array
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
RemoteIssueLink:
additionalProperties: false
description: Details of an issue remote link.
properties:
application:
allOf:
- $ref: '#/components/schemas/Application'
description: Details of the remote application the linked item is in.
globalId:
description: >-
The global ID of the link, such as the ID of the item on the remote
system.
type: string
id:
description: The ID of the link.
format: int64
type: integer
object:
allOf:
- $ref: '#/components/schemas/RemoteObject'
description: Details of the item linked to.
relationship:
description: >-
Description of the relationship between the issue and the linked
item.
type: string
self:
description: The URL of the link.
format: uri
type: string
type: object
RemoteIssueLinkIdentifies:
additionalProperties: false
description: Details of the identifiers for a created or updated remote issue link.
properties:
id:
description: >-
The ID of the remote issue link, such as the ID of the item on the
remote system.
format: int64
readOnly: true
type: integer
xml:
attribute: true
self:
description: The URL of the remote issue link.
readOnly: true
type: string
xml:
attribute: true
type: object
Transitions:
additionalProperties: false
description: List of issue transitions.
properties:
expand:
description: >-
Expand options that include additional transitions details in the
response.
readOnly: true
type: string
xml:
attribute: true
transitions:
description: List of issue transitions.
items:
$ref: '#/components/schemas/IssueTransition'
readOnly: true
type: array
type: object
Votes:
additionalProperties: false
description: The details of votes on an issue.
properties:
hasVoted:
description: Whether the user making this request has voted on the issue.
readOnly: true
type: boolean
self:
description: The URL of these issue vote details.
format: uri
readOnly: true
type: string
voters:
description: >-
List of the users who have voted on this issue. An empty list is
returned when the calling user doesn't have the *View voters and
watchers* project permission.
items:
$ref: '#/components/schemas/User'
readOnly: true
type: array
votes:
description: The number of votes on the issue.
format: int64
readOnly: true
type: integer
type: object
Watchers:
additionalProperties: false
description: The details of watchers on an issue.
properties:
isWatching:
description: Whether the calling user is watching this issue.
readOnly: true
type: boolean
self:
description: The URL of these issue watcher details.
readOnly: true
type: string
watchCount:
description: The number of users watching this issue.
format: int32
readOnly: true
type: integer
watchers:
description: Details of the users watching this issue.
items:
$ref: '#/components/schemas/UserDetails'
readOnly: true
type: array
type: object
xml:
name: watchers
PageOfWorklogs:
additionalProperties: true
description: Paginated list of worklog details
properties:
maxResults:
description: The maximum number of results that could be on the page.
format: int32
readOnly: true
type: integer
startAt:
description: The index of the first item returned on the page.
format: int32
readOnly: true
type: integer
total:
description: The number of results on the page.
format: int32
readOnly: true
type: integer
worklogs:
description: List of worklogs.
items:
$ref: '#/components/schemas/Worklog'
readOnly: true
type: array
type: object
Worklog:
additionalProperties: true
description: Details of a worklog.
properties:
author:
allOf:
- $ref: '#/components/schemas/UserDetails'
description: Details of the user who created the worklog.
readOnly: true
comment:
description: >-
A comment about the worklog in [Atlassian Document
Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).
Optional when creating or updating a worklog.
created:
description: The datetime on which the worklog was created.
format: date-time
readOnly: true
type: string
id:
description: The ID of the worklog record.
readOnly: true
type: string
issueId:
description: The ID of the issue this worklog is for.
readOnly: true
type: string
properties:
description: >-
Details of properties for the worklog. Optional when creating or
updating a worklog.
items:
$ref: '#/components/schemas/EntityProperty'
type: array
self:
description: The URL of the worklog item.
format: uri
readOnly: true
type: string
started:
description: >-
The datetime on which the worklog effort was started. Required when
creating a worklog. Optional when updating a worklog.
format: date-time
type: string
timeSpent:
description: >-
The time spent working on the issue as days (\#d), hours (\#h), or
minutes (\#m or \#). Required when creating a worklog if
`timeSpentSeconds` isn't provided. Optional when updating a worklog.
Cannot be provided if `timeSpentSecond` is provided.
type: string
timeSpentSeconds:
description: >-
The time in seconds spent working on the issue. Required when
creating a worklog if `timeSpent` isn't provided. Optional when
updating a worklog. Cannot be provided if `timeSpent` is provided.
format: int64
type: integer
updateAuthor:
allOf:
- $ref: '#/components/schemas/UserDetails'
description: Details of the user who last updated the worklog.
readOnly: true
updated:
description: The datetime on which the worklog was last updated.
format: date-time
readOnly: true
type: string
visibility:
allOf:
- $ref: '#/components/schemas/Visibility'
description: >-
Details about any restrictions in the visibility of the worklog.
Optional when creating or updating a worklog.
type: object
xml:
name: worklog
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
info:
contact:
email: [email protected]
description: Needs description.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: 'Atlassian rest/api/3/issue/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/issue/archive:
post:
deprecated: false
description: >-
Enables admins to archive up to 100,000 issues in a single request using
JQL, returning the URL to check the status of the submitted
request.<br><br>You can use the [get
task](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-tasks/#api-rest-api-3-task-taskid-get)
and [cancel
task](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-tasks/#api-rest-api-3-task-taskid-cancel-post)
APIs to manage the request.<br><br>**Note that:**<br><br> * you can't
archive subtasks directly, only through their parent issues<br> * you
can only archive issues from software, service management, and business
projects<br><br>**[Permissions](#permissions) required:** Jira admin or
site admin: [global
permission](https://confluence.atlassian.com/x/x4dKLg)<br><br>**License
required:** Premium or Enterprise<br><br>**Signed-in users only:** This
API can't be accessed anonymously.<br><br>**Rate limiting:** Only a
single request per jira instance can be active at any given
time.<br><br> <br>
operationId: atlassianArchiveissuesasync
parameters: []
requestBody:
content:
application/json:
example:
jql: project = FOO AND updated < -2y
schema:
$ref: '#/components/schemas/ArchiveIssueAsyncRequest'
description: >-
A JQL query specifying the issues to archive. Note that subtasks can
only be archived through their parent issues.
required: true
responses:
'202':
content:
application/json:
example: '"https://your-domain.atlassian.net/rest/api/3/task/1010"'
schema:
type: string
description: Returns the URL to check the status of the submitted request.
'400':
content:
application/json:
example: '{"errorMessages":["Invalid JQL. Bad request."],"errors":{}}'
description: >-
Returned if no issues were archived due to a bad request, for
example an invalid JQL query.
'401':
content:
application/json:
example: '{"errorMessages":["User is not logged in."],"errors":{}}'
description: >-
Returned if no issues were archived because the provided
authentication credentials are either missing or invalid.
'403':
content:
application/json:
example: >-
{"errorMessages":["Archiving issues is only available for
premium editions of Jira."],"errors":{}}
description: >-
Returned if no issues were archived because the user lacks the
required Jira admin or site admin permissions.
'412':
content:
application/json:
example: >-
{"errorMessages":["An issue archival task is already running
with ID 1010. To start a new one, cancel the task or wait for it
to finish."],"errors":{}}
description: Returned if a request to archive issue(s) is already running.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Archive Issue S By Jql
tags:
- Issues
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:issue:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: WRITE
put:
deprecated: false
description: >-
Enables admins to archive up to 1000 issues in a single request using
issue ID/key, returning details of the issue(s) archived in the process
and the errors encountered, if any.<br><br>**Note that:**<br><br> * you
can't archive subtasks directly, only through their parent issues<br> * you can only archive issues from software, service management, and
business projects<br><br>**[Permissions](#permissions) required:** Jira
admin or site admin: [global
permission](https://confluence.atlassian.com/x/x4dKLg)<br><br>**License
required:** Premium or Enterprise<br><br>**Signed-in users only:** This
API can't be accessed anonymously.<br><br> <br>
operationId: atlassianArchiveissues
parameters: []
requestBody:
content:
application/json:
example:
issueIdsOrKeys:
- PR-1
- '1001'
- PROJECT-2
schema:
$ref: '#/components/schemas/IssueArchivalSyncRequest'
description: Contains a list of issue keys or IDs to be archived.
required: true
responses:
'200':
content:
application/json:
example: >-
{"errors":{"issueIsSubtask":{"count":3,"issueIdsOrKeys":["ST-1","ST-2","ST-3"],"message":"Issue
is
subtask."},"issuesInArchivedProjects":{"count":2,"issueIdsOrKeys":["AR-1","AR-2"],"message":"Issue
exists in archived
project."},"issuesInUnlicensedProjects":{"count":3,"issueIdsOrKeys":["UL-1","UL-2","UL-3"],"message":"Issues
with these IDs are in unlicensed
projects."},"issuesNotFound":{"count":3,"issueIdsOrKeys":["PR-1","PR-2","PR-3"],"message":"Issue
not found."}},"numberOfIssuesUpdated":10}
schema:
$ref: '#/components/schemas/IssueArchivalSyncResponse'
description: >-
Returned if there is at least one valid issue to archive in the
request. The return message will include the count of archived
issues and subtasks, as well as error details for issues which
failed to get archived.
'400':
content:
application/json:
example: >-
{"errorMessages":["No valid issue to archive or unarchive. Bad
request."],"errors":{}}
description: >-
Returned if none of the issues in the request can be archived.
Possible reasons:
* the issues weren't found
* the issues are subtasks
* the issues belong to unlicensed projects
* the issues belong to archived projects
'401':
content:
application/json:
example: '{"errorMessages":["User is not logged in."],"errors":{}}'
description: >-
Returned if no issues were archived because the provided
authentication credentials are either missing or invalid.
'403':
content:
application/json:
example: >-
{"errorMessages":["Only admins can archive or unarchive issues.
Access denied."],"errors":{}}
description: >-
Returned if no issues were archived because the user lacks the
required Jira admin or site admin permissions.
'412':
content:
application/json:
example: >-
{"errorMessages":["The number of issues to archive or unarchive
exceeds the hard limit of 1000. Precondition
failed."],"errors":{}}
description: >-
Returned if one or more issues were successfully archived, but the
operation was incomplete because the number of issue IDs or keys
provided exceeds 1000.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Archive Issue S By Issue Id Key
tags:
- Issues
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:issue:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: WRITE
/rest/api/3/issue/bulk:
post:
deprecated: false
description: >-
Creates upto **50** issues and, where the option to create subtasks is
enabled in Jira, subtasks. Transitions may be applied, to move the
issues or subtasks to a workflow step other than the default start step,
and issue properties set.<br><br>The content of each issue or subtask is
defined using `update` and `fields`. The fields that can be set in the
issue or subtask are determined using the [ Get create issue
metadata](#api-rest-api-3-issue-createmeta-get). These are the same
fields that appear on the issues' create screens. Note that the
`description`, `environment`, and any `textarea` type custom fields
(multi-line text fields) take Atlassian Document Format content. Single
line custom fields (`textfield`) accept a string and don't handle
Atlassian Document Format content.<br><br>Creating a subtask differs
from creating an issue as follows:<br><br> * `issueType` must be set to
a subtask issue type (use [ Get create issue
metadata](#api-rest-api-3-issue-createmeta-get) to find subtask issue
types).<br> * `parent` the must contain the ID or key of the parent
issue.<br><br>**[Permissions](#permissions) required:** *Browse
projects* and *Create issues* [project
permissions](https://confluence.atlassian.com/x/yodKLg) for the project
in which each issue or subtask is created.
operationId: atlassianCreateissues
parameters: []
requestBody:
content:
application/json:
example:
issueUpdates:
- fields:
assignee:
id: 5b109f2e9729b51b54dc274d
components:
- id: '10000'
customfield_10000: 09/Jun/19
customfield_20000: 06/Jul/19 3:25 PM
customfield_30000:
- '10000'
- '10002'
customfield_40000:
content:
- content:
- text: Occurs on all orders
type: text
type: paragraph
type: doc
version: 1
customfield_50000:
content:
- content:
- text: Could impact day-to-day work.
type: text
# --- truncated at 32 KB (253 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-issue--openapi-original.yml