Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
contact:
url: https://getsupport.atlassian.com
description: Jira Software Cloud REST API documentation
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: Jira Software Cloud Issue API
version: 1001.0.0
servers:
- url: https://your-domain.atlassian.net
tags:
- description: Apis related to issues
name: Issue
paths:
/rest/agile/1.0/issue/rank:
put:
deprecated: false
description: 'Moves (ranks) issues before or after a given issue. At most 50 issues may be ranked at once.
This operation may fail for some issues, although this will be rare. In that case the 207 status code is returned for the whole response and detailed information regarding each issue is available in the response body.
If rankCustomFieldId is not defined, the default rank field will be used.'
operationId: rankIssues
requestBody:
content:
application/json:
example:
issues:
- PR-1
- '10001'
- PR-3
rankBeforeIssue: PR-4
rankCustomFieldId: 10521
schema:
additionalProperties: false
properties:
issues:
items:
type: string
type: array
rankAfterIssue:
type: string
rankBeforeIssue:
type: string
rankCustomFieldId:
format: int64
type: integer
type: object
description: bean which contains list of issues to rank and information where it should be ranked.
required: true
responses:
'204':
description: Empty response is returned if operation was successful.
'207':
content:
application/json:
example: '{"entries":[{"issueId":10000,"issueKey":"PR-1","status":200},{"issueId":10001,"issueKey":"PR-2","status":200},{"errors":["JIRA Agile cannot execute the rank operation at this time. Please try again later."],"issueId":10002,"issueKey":"PR-3","status":503}]}'
description: Returns the list of issue with status of rank operation.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the user is not logged in.
'403':
description: Returned if the user does not have a valid license or does not have permission to rank. To rank issues user has to have schedule issue permission for issues that they want to rank.
security:
- basicAuth: []
- OAuth2:
- write:issue:jira-software
summary: Rank issues
tags:
- Issue
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: WRITE
/rest/agile/1.0/issue/{issueIdOrKey}:
get:
deprecated: false
description: Returns a single issue, for a given issue ID or issue key. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic.
operationId: getIssue
parameters:
- description: The ID or key of the requested issue.
in: path
name: issueIdOrKey
required: true
schema:
type: string
- description: The list of fields to return for each issue. By default, all navigable and Agile fields are returned.
in: query
name: fields
schema:
items:
additionalProperties: false
type: object
type: array
- description: A comma-separated list of the parameters to expand.
in: query
name: expand
schema:
type: string
- description: A boolean indicating whether the issue retrieved by this method should be added to the current user's issue history
in: query
name: updateHistory
schema:
type: boolean
responses:
'200':
content:
application/json:
example: '{"expand":"","fields":{"flagged":true,"sprint":{"id":37,"self":"https://your-domain.atlassian.net/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2","goal":"sprint 2 goal"},"closedSprints":[{"id":37,"self":"https://your-domain.atlassian.net/rest/agile/1.0/sprint/23","state":"closed","name":"sprint 1","startDate":"2015-04-11T15:22:00.000+10:00","endDate":"2015-04-20T01:22:00.000+10:00","completeDate":"2015-04-20T11:04:00.000+10:00","goal":"sprint 1 goal"}],"description":"example bug report","project":{"avatarUrls":{"16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000","48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000"},"id":"10000","insight":{"lastIssueUpdateTime":"2021-04-22T05:37:05.000+0000","totalIssueCount":100},"key":"EX","name":"Example","projectCategory":{"description":"First Project Category","id":"10000","name":"FIRST","self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000"},"self":"https://your-domain.atlassian.net/rest/api/3/project/EX","simplified":false,"style":"classic"},"comment":[{"author":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"body":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."}]}]},"created":"2021-01-17T12:34:00.000+0000","id":"10000","self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000","updateAuthor":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"updated":"2021-01-18T23:45:00.000+0000","visibility":{"identifier":"Administrators","type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"https://your-domain.atlassian.net/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"author":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"comment":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"I did some work here."}]}]},"id":"100028","issueId":"10002","self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000","started":"2021-01-17T12:34:00.000+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"updateAuthor":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"updated":"2021-01-18T23:45:00.000+0000","visibility":{"identifier":"276f955c-63d7-42c8-9520-92d01dca0625","type":"group","value":"jira-developers"}}],"updated":1,"timetracking":{"originalEstimate":"10m","originalEstimateSeconds":600,"remainingEstimate":"3m","remainingEstimateSeconds":200,"timeSpent":"6m","timeSpentSeconds":400}},"id":"10001","key":"HSP-1","self":"https://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001"}'
description: Returns the requested issue.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the user is not logged in.
'403':
description: Returned if the user does not have a valid license.
'404':
description: "Returned in these cases:\n\n * the issue does not exist\n * the user does not have permission to view issue"
security:
- basicAuth: []
- OAuth2:
- read:issue:jira-software
summary: Get issue
tags:
- Issue
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/rest/agile/1.0/issue/{issueIdOrKey}/estimation:
get:
deprecated: false
description: 'Returns the estimation of the issue and a fieldId of the field that is used for it. `boardId` param is required. This param determines which field will be updated on a issue.
Original time internally stores and returns the estimation as a number of seconds.
The field used for estimation on the given board can be obtained from board configuration resource. More information about the field are returned by edit meta resource or field resource.'
operationId: getIssueEstimationForBoard
parameters:
- description: The ID or key of the requested issue.
in: path
name: issueIdOrKey
required: true
schema:
type: string
- description: The ID of the board required to determine which field is used for estimation.
in: query
name: boardId
schema:
format: int64
type: integer
responses:
'200':
content:
application/json:
example: '{"fieldId":"customfield_12532","value":"8.0"}'
description: Returns the estimation of the issue and a fieldId of the field that is used for it.
'400':
description: Returned if the boardId was not provided, field does not exists or value was in wrong format.
'401':
description: Returned if the user is not logged in.
'403':
description: Returned if the user does not have a valid license or does not have permission to edit issue.
'404':
description: "Returned in these cases:\n\n * the issue does not exist\n * the user does not have permission to view issue\n * the board does not exist\n * the user does not have permission to view board\n * the issue does not belong to the board"
security:
- basicAuth: []
- OAuth2:
- read:issue:jira-software
- read:issue-details:jira
summary: Get issue estimation for board
tags:
- Issue
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: READ
put:
deprecated: false
description: 'Updates the estimation of the issue. boardId param is required. This param determines which field will be updated on a issue.
Note that this resource changes the estimation field of the issue regardless of appearance the field on the screen.
Original time tracking estimation field accepts estimation in formats like "1w", "2d", "3h", "20m" or number which represent number of minutes. However, internally the field stores and returns the estimation as a number of seconds.
The field used for estimation on the given board can be obtained from board configuration resource. More information about the field are returned by edit meta resource or field resource.'
operationId: estimateIssueForBoard
parameters:
- description: The ID or key of the requested issue.
in: path
name: issueIdOrKey
required: true
schema:
type: string
- description: The ID of the board required to determine which field is used for estimation.
in: query
name: boardId
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
value: '8.0'
schema:
additionalProperties: false
properties:
value:
type: string
type: object
description: bean that contains value of a new estimation.
required: true
responses:
'200':
content:
application/json:
example: '{"fieldId":"customfield_12532","value":"8.0"}'
description: Returns the estimation of the issue and a fieldId of the field that is used for it.
'400':
description: Returned if the boardId was not provided, field does not exists or value was in wrong format.
'401':
description: Returned if the user is not logged in.
'403':
description: Returned if the user does not have a valid license or does not have permission to edit issue.
'404':
description: "Returned in these cases:\n\n * the issue does not exist\n * the user does not have permission to view issue\n * the board does not exist\n * the user does not have permission to view board\n * the issue does not belong to the board"
security:
- basicAuth: []
- OAuth2:
- write:issue:jira-software
- read:issue-details:jira
summary: Estimate issue for board
tags:
- Issue
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: WRITE
components:
securitySchemes:
OAuth2:
description: OAuth2 scopes for Jira
flows:
authorizationCode:
authorizationUrl: https://auth.atlassian.com/authorize
scopes:
delete:board-scope.admin:jira-software: Remove board configuration, features, and properties.
delete:sprint:jira-software: Delete sprints and their properties.
manage:jira-configuration: Configure Jira settings that require the Jira administrators permission, for example, create projects and custom fields, view workflows, manage issue link types.
manage:jira-project: Create and edit project settings and create new project-level objects, for example, versions, components.
manage:jira-webhook: Manage Jira webhooks. Enables an OAuth app to register and unregister dynamic webhooks in Jira. It also provides for fetching of registered webhooks.
read:board-scope.admin:jira-software: View configuration, features, filters, project, properties and quick filters related to the given board.
read:board-scope:jira-software: View board and issues from a board, view issues from a backlog and view reports and versions.
read:build:jira-software: View builds.
read:deployment:jira-software: View deployments.
read:epic:jira-software: View and search for epics, view issues related to an epic and issues without an epic.
read:feature-flag:jira-software: View feature flags.
read:issue:jira-software: View issues, issue estimations and field used for estimations.
read:jira-user: View user information in Jira that you have access to, including usernames, email addresses, and avatars.
read:jira-work: Read project and issue data. Search for issues and objects associated with issues (such as attachments and worklogs).
read:remote-link:jira-software: View remote links.
read:source-code:jira-software: View repositories and check if data exists for the supplied properties.
read:sprint:jira-software: View sprints and sprint related issues and properties.
write:board-scope.admin:jira-software: Create board, toggle features and set and delete properties.
write:board-scope:jira-software: Move issues to a backlog and move issues from a backlog to a board.
write:build:jira-software: Submit and delete build.
write:deployment:jira-software: Submit and delete deployment.
write:epic:jira-software: Remove issues from epic, move issues to epic, rank epics and partially update epics. A partial update means that fields not present in the request JSON will not be updated.
write:feature-flag:jira-software: Submit and delete feature flag.
write:issue:jira-software: Move (rank) issues and update estimation of the issue.
write:jira-work: Create and edit issues in Jira, post comments, create worklogs, and delete issues.
write:remote-link:jira-software: Submit and delete remote link.
write:source-code:jira-software: Store and delete development information, delete repository and delete development information entity.
write:sprint:jira-software: Save, move issues to sprints, and change the order of sprints.
read:dev-info:jira: Read development information
write:dev-info:jira: Write development information
delete:dev-info:jira: Delete development information
read:feature-flag-info:jira: Read feature flag information
write:feature-flag-info:jira: Write feature flag information
delete:feature-flag-info:jira: Delete feature flag information
read:deployment-info:jira: Read deployment information
write:deployment-info:jira: Write deployment information
delete:deployment-info:jira: Delete deployment information
read:build-info:jira: Read build information
write:build-info:jira: Write build information
delete:build-info:jira: Delete build information
read:remote-link-info:jira: Read remote link information
write:remote-link-info:jira: Write remote link information
delete:remote-link-info:jira: Delete remote link information
read:security:jira: Read security information
write:security:jira: Write security information
delete:security:jira: Delete security information
tokenUrl: https://auth.atlassian.com/oauth/token
type: oauth2
basicAuth:
description: Basic authentication using email and API token
scheme: basic
type: http
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
x-atlassian-narrative:
documents:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jira/refs/heads/main/openapi/jira-issue-api-openapi.yml