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 Epic API version: 1001.0.0 servers: - url: https://your-domain.atlassian.net tags: - description: Apis related to epics name: EPIC paths: /rest/agile/1.0/epic/none/issue: get: deprecated: true description: Returns all issues that do not belong to any epic. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank. **Note:** If you are querying a next-gen project, do not use this operation. Instead, search for issues that don't belong to an epic by using the Search for issues using JQL operation in the Jira platform REST API. Build your JQL query using the `parent is empty` clause. For more information on the `parent` JQL field, see Advanced searching. operationId: getIssuesWithoutEpic parameters: - description: 'The starting index of the returned issues. Base index: 0. See the ''Pagination'' section at the top of this page for more details.' in: query name: startAt schema: format: int64 type: integer - description: The maximum number of issues to return per page. See the 'Pagination' section at the top of this page for more details. Note, the total number of issues returned is limited by the property 'jira.search.views.default.max' in your Jira instance. If you exceed this limit, your results will be truncated. in: query name: maxResults schema: format: int32 type: integer - description: Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues. in: query name: jql schema: type: string - description: 'Specifies whether to validate the JQL query or not. Default: true.' in: query name: validateQuery schema: type: boolean - 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 responses: '200': content: application/json: example: '{"expand":"names,schema","issues":[{"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"}],"maxResults":50,"startAt":0,"total":1}' description: Returns the requested issues, at the specified page of the results. '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. security: - basicAuth: [] - OAuth2: - read:epic:jira-software - read:issue-details:jira - read:jql:jira summary: Get issues without epic tags: - EPIC x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-connect-scope: READ post: deprecated: false description: 'Removes issues from epics. The user needs to have the edit issue permission for all issue they want to remove from epics. The maximum number of issues that can be moved in one operation is 50. **Note:** This operation does not work for epics in next-gen projects. Instead, update the issue using `\{ fields: \{ parent: \{\} \} \}`' operationId: removeIssuesFromEpic requestBody: content: application/json: example: issues: - '10001' - PR-1 - PR-3 schema: additionalProperties: false properties: issues: items: type: string type: array uniqueItems: true type: object required: true responses: '204': description: Empty response is returned if operation was successful. '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 assign issues. '404': description: Returned if the epic does not exist or the user does not have permission to view it. security: - basicAuth: [] - OAuth2: - write:epic:jira-software summary: Remove issues from epic tags: - EPIC x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-connect-scope: WRITE /rest/software/1.0/epic/none/issue: get: deprecated: false description: Returns all issues that do not belong to any epic. Result pagination is token based, using `nextPageToken` and `maxResults`. This only includes issues that the user has permission to view. Issues returned from this resource include Software project fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank. **Note:** If you are querying a Team Managed project, do not use this operation. Instead, search for issues that don't belong to an epic by using the Search for issues using JQL enhanced search operation in the Jira platform REST API. Build your JQL query using the `parent is empty` clause. For more information on the `parent` JQL field, see Advanced searching. operationId: getIssuesWithoutEpicJSIS parameters: - description: 'The token for a page to fetch that is not the first page. The first page has a `nextPageToken` of `null`. Use the `nextPageToken` to fetch the next page of issues. Note: The `nextPageToken` field is **not included** in the response for the last page, indicating there is no next page.' in: query name: nextPageToken schema: type: string - description: The maximum number of items to return per page. To manage page size, the API may return fewer items per page where there is a large number of fields or properties returned. It returns max 5000 issues. in: query name: maxResults schema: format: int32 type: integer - description: Strong consistency issue IDs to be reconciled with search results. Accepts max 50 IDs. This list of IDs should be consistent with each paginated request across different pages. in: query name: reconcileIssues schema: items: format: int64 type: integer type: array uniqueItems: true - description: "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues. \nNote that `username` and `userkey` can't be used as search terms for this parameter due to privacy reasons. Use `accountId` instead." in: query name: jql schema: type: string - description: 'Specifies whether to validate the JQL query or not. Default: true.' in: query name: validateQuery schema: type: boolean - description: The list of fields to return for each issue. By default, all navigable and Software project 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 responses: '200': content: application/json: example: '{"expand":"names,schema","isLast":true,"issues":[{"expand":"","fields":{"watcher":{"isWatching":false,"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-1/watchers","watchCount":1},"attachment":[{"author":{"accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","active":false,"avatarUrls":{"16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32","48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"},"displayName":"Mia Krystof","key":"","name":"","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"content":"https://your-domain.atlassian.net/jira/rest/api/3/attachment/content/10001","created":"2023-06-24T19:24:50.000+0000","filename":"debuglog.txt","id":10001,"mimeType":"text/plain","self":"https://your-domain.atlassian.net/rest/api/2/attachments/10001","size":2460}],"sub-tasks":[{"id":"10000","outwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10003","key":"ED-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/ED-2"},"type":{"id":"10000","inward":"Parent","name":"","outward":"Sub-task"}}],"description":"Main order flow broken","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":"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"}}],"issuelinks":[{"id":"10001","outwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10004L","key":"PR-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-2"},"type":{"id":"10000","inward":"depends on","name":"Dependent","outward":"is depended by"}},{"id":"10002","inwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10004","key":"PR-3","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-3"},"type":{"id":"10000","inward":"depends on","name":"Dependent","outward":"is depended by"}}],"worklog":[{"author":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"comment":"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":"10002","key":"ED-1","self":"https://your-domain.atlassian.net/rest/api/3/issue/10002"}]}' schema: $ref: '#/components/schemas/SoftwareIssueResults' description: Returns the requested issues, at the specified page of the results. '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. security: - basicAuth: [] - OAuth2: - read:epic:jira-software - read:issue-details:jira - read:jql:jira summary: Get issues without epic (enhanced) tags: - EPIC x-atlassian-connect-scope: READ x-atlassian-data-security-policy: - app-access-rule-exempt: false /rest/agile/1.0/epic/{epicIdOrKey}: get: deprecated: false description: Returns the epic for a given epic ID. This epic will only be returned if the user has permission to view it. **Note:** This operation does not work for epics in next-gen projects. operationId: getEpic parameters: - description: The id or key of the requested epic. in: path name: epicIdOrKey required: true schema: type: string responses: '200': content: application/json: example: '{"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}' description: Returns the requested epic. '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 if the epic does not exist or the user does not have permission to view it. security: - basicAuth: [] - OAuth2: - read:epic:jira-software summary: Get epic tags: - EPIC x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-connect-scope: READ post: deprecated: false description: Performs a partial update of the epic. A partial update means that fields not present in the request JSON will not be updated. Valid values for color are `color_1` to `color_9`. **Note:** This operation does not work for epics in next-gen projects. operationId: partiallyUpdateEpic parameters: - description: The id or key of the epic to update. in: path name: epicIdOrKey required: true schema: type: string requestBody: content: application/json: example: color: key: color_6 done: true name: epic 2 summary: epic 2 summary schema: additionalProperties: false properties: color: additionalProperties: false properties: key: enum: - color_1 - color_2 - color_3 - color_4 - color_5 - color_6 - color_7 - color_8 - color_9 - color_10 - color_11 - color_12 - color_13 - color_14 type: string type: object done: type: boolean name: type: string summary: type: string type: object required: true responses: '200': content: application/json: example: '{"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}' description: Updated epic '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 edit issue permission. '404': description: Returned if the epic does not exist or the user does not have permission to view it. security: - basicAuth: [] - OAuth2: - write:epic:jira-software summary: Partially update epic tags: - EPIC x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-connect-scope: WRITE /rest/agile/1.0/epic/{epicIdOrKey}/issue: get: deprecated: true description: Returns all issues that belong to the epic, for the given epic ID. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank. **Note:** If you are querying a next-gen project, do not use this operation. Instead, search for issues that belong to an epic by using the Search for issues using JQL operation in the Jira platform REST API. Build your JQL query using the `parent` clause. For more information on the `parent` JQL field, see Advanced searching. operationId: getIssuesForEpic parameters: - description: The id or key of the epic that contains the requested issues. in: path name: epicIdOrKey required: true schema: type: string - description: 'The starting index of the returned issues. Base index: 0. See the ''Pagination'' section at the top of this page for more details.' in: query name: startAt schema: format: int64 type: integer - description: 'The maximum number of issues to return per page. Default: 50. See the ''Pagination'' section at the top of this page for more details. Note, the total number of issues returned is limited by the property ''jira.search.views.default.max'' in your Jira instance. If you exceed this limit, your results will be truncated.' in: query name: maxResults schema: format: int32 type: integer - description: "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues. \nNote that `username` and `userkey` can't be used as search terms for this parameter due to privacy reasons. Use `accountId` instead." in: query name: jql schema: type: string - description: 'Specifies whether to validate the JQL query or not. Default: true.' in: query name: validateQuery schema: type: boolean - 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 responses: '200': content: application/json: example: '{"expand":"names,schema","issues":[{"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"}],"maxResults":50,"startAt":0,"total":1}' description: Returns the requested issues, at the specified page of the results. '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 if the epic does not exist or the user does not have permission to view it. security: - basicAuth: [] - OAuth2: - read:epic:jira-software - read:issue-details:jira - read:jql:jira summary: Get issues for epic tags: - EPIC x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-connect-scope: READ post: deprecated: false description: Moves issues to an epic, for a given epic id. Issues can be only in a single epic at the same time. That means that already assigned issues to an epic, will not be assigned to the previous epic anymore. The user needs to have the edit issue permission for all issue they want to move and to the epic. The maximum number of issues that can be moved in one operation is 50. **Note:** This operation does not work for epics in next-gen projects. operationId: moveIssuesToEpic parameters: - description: The id or key of the epic that you want to assign issues to. in: path name: epicIdOrKey required: true schema: type: string requestBody: content: application/json: example: issues: - '10001' - PR-1 - PR-3 schema: additionalProperties: false properties: issues: items: type: string type: array uniqueItems: true type: object required: true responses: '204': description: Empty response is returned if operation was successful. '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 edit issue permission for all issues to assign or for the epic. '404': description: Returned if the epic does not exist or the user does not have permission to view it. security: - basicAuth: [] - OAuth2: - write:epic:jira-software summary: Move issues to epic tags: - EPIC x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-connect-scope: WRITE /rest/software/1.0/epic/{epicIdOrKey}/issue: get: deprecated: false description: Returns all issues that belong to the epic, for the given epic ID. Result pagination is token based, using `nextPageToken` and `maxResults`. This only includes issues that the user has permission to view. Issues returned from this resource include Software project fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank. **Note:** If you are querying a Team Managed project, do not use this operation. Instead, search for issues that belong to an epic by using the Search for issues using JQL enhanced search operation in the Jira platform REST API. Build your JQL query using the `parent` clause. For more information on the `parent` JQL field, see Advanced searching. operationId: getIssuesForEpicJSIS parameters: - description: The ID or key of the epic that contains the requested issues. in: path name: epicIdOrKey required: true schema: type: string - description: 'The token for a page to fetch that is not the first page. The first page has a `nextPageToken` of `null`. Use the `nextPageToken` to fetch the next page of issues. Note: The `nextPageToken` field is **not included** in the response for the last page, indicating there is no next page.' in: query name: nextPageToken schema: type: string - description: The maximum number of items to return per page. To manage page size, the API may return fewer items per page where there is a large number of fields or properties returned. It returns max 5000 issues. in: query name: maxResults schema: format: int32 type: integer - description: Strong consistency issue IDs to be reconciled with search results. Accepts max 50 IDs. This list of IDs should be consistent with each paginated request across different pages. in: query name: reconcileIssues schema: items: format: int64 type: integer type: array uniqueItems: true - description: "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues. \nNote that `username` and `userkey` can't be used as search terms for this parameter due to privacy reasons. Use `accountId` instead." in: query name: jql schema: type: string - description: 'Specifies whether to validate the JQL query or not. Default: true.' in: query name: validateQuery schema: type: boolean - description: The list of fields to return for each issue. By default, all navigable and Software project 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 responses: '200': content: application/json: example: '{"expand":"names,schema","isLast":true,"issues":[{"expand":"","fields":{"watcher":{"isWatching":false,"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-1/watchers","watchCount":1},"attachment":[{"author":{"accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","active":false,"avatarUrls":{"16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32","48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"},"displayName":"Mia Krystof","key":"","name":"","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"content":"https://your-domain.atlassian.net/jira/rest/api/3/attachment/content/10001","created":"2023-06-24T19:24:50.000+0000","filename":"debuglog.txt","id":10001,"mimeType":"text/plain","self":"https://your-domain.atlassian.net/rest/api/2/attachments/10001","size":2460}],"sub-tasks":[{"id":"10000","outwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10003","key":"ED-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/ED-2"},"type":{"id":"10000","inward":"Parent","name":"","outward":"Sub-task"}}],"description":"Main order flow broken","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":"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"}}],"issuelinks":[{"id":"10001","outwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10004L","key":"PR-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-2"},"type":{"id":"10000","inward":"depends on","name":"Dependent","outward":"is depended by"}},{"id":"10002","inwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10004","key":"PR-3","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-3"},"type":{"id":"10000","inward":"depends on","name":"Dependent","outward":"is depended by"}}],"worklog":[{"author":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"comment":"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":"10002","key":"ED-1","self":"https://your-domain.atlassian.net/rest/api/3/issue/10002"}]}' schema: $ref: '#/components/schemas/SoftwareIssueResults' description: Returns the requested issues, at the specified page of the results. '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 if the epic does not exist or the user does not have permission to view it. security: - basicAuth: [] - OAuth2: - read:epic:jira-software - read:issue-details:jira - read:jql:jira summary: Get issues for epic (enhanced) tags: - EPIC x-atlassian-connect-scope: READ x-atlassian-data-security-policy: - app-access-rule-exempt: false /rest/agile/1.0/epic/{epicIdOrKey}/rank: put: deprecated: false description: 'Moves (ranks) an epic before or after a given epic. If rankCustomFieldId is not defined, the default rank field will be used. **Note:** This operation does not work for epics in next-gen projects.' operationId: rankEpics parameters: - description: The id or key of the epic to rank. in: path name: epicIdOrKey required: true schema: type: string requestBody: content: application/json: example: rankBeforeEpic: '10000' rankCustomFieldId: 10521 schema: additionalProperties: false properties: rankAfterEpic: type: string rankBeforeEpic: type: string rankCustomFieldId: format: int64 type: integer type: object description: bean which contains the information where the given epic should be ranked. required: true responses: '204': description: Empty response is returned if operation was successful. '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 epics that they want to rank. '404': description: Returned when the given epics in the path parameter or the request body do not exist. security: - basicAuth: [] - OAuth2: - write:epic:jira-software summary: Rank epics tags: - EPIC x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-connect-scope: WRITE components: schemas: LinkGroup: additionalProperties: false description: Details a link group, which defines issue operations. properties: groups: items: $ref: '#/components/schemas/LinkGroup' type: array header: additionalProperties: false description: Details about the operations available in this version. properties: href: type: string iconClass: type: string id: type: string label: type: string styleClass: type: string title: type: string weight: format: int32 type: integer type: object xml: name: link id: type: string links: items: additionalProperties: false description: Details about the operations available in this version. properties: href: type: string iconClass: type: string id: type: string label: type: string styleClass: type: string title: type: string weight: format: int32 type: integer type: object xml: name: link type: array styleClass: type: string weight: format: int32 type: integer type: object Operations: additionalProperties: true description: Details of the operations that can be performed on the issue. properties: linkGroups: description: Details of the link groups defining issue operations. items: $ref: '#/components/schemas/LinkGroup' readOnly: true type: array type: object IssueBean: additionalProperties: false description: Details about an issue. properties: changelog: allOf: - additionalProperties: false description: A page of changelogs. properties: histories: description: The list of changelogs. items: additionalProperties: false description: A log of changes made to issue fields. Changelogs related to workflow associations are currently being deprecated. properties: author: allOf: - 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: - 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 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 description: The user who made the change. readOnly: true created: description: The date on which the change took place. format: date-time readOnly: true type: string historyMetadata: allOf: - additionalProperties: true description: Details of issue history metadata. properties: activityDescription: description: The activity described in the history record. type: string activityDescriptionKey: description: The key of the activity described in the history record. type: string actor: allOf: - additionalProperties: true description: Details of user or system associated with a issue history metadata item. properties: avatarUrl: description: The URL to an avatar for the user or system associated with a history record. type: string displayName: description: The display name of the user or system associated with a history record. type: string displayNameKey: description: The key of the display name of the user or system associated with a history record. type: string id: description: The ID of the user or system associated with a history record. type: string type: description: The type of the user or system associated with a history record. type: string url: description: The URL of the user or system associated with a history record. type: string type: object description: Details of the user whose action created the history record. cause: allOf: - additionalProperties: true description: Details of user or system associated with a issue history metadata item. properties: avatarUrl: description: The URL to an avatar for the user or system associated with a history record. type: string displayName: description: The display name of the user or system associated with a history record. type: string displayNameKey: description: The key of the display name of the user or system associated with a history record. type: string id: description: The ID of the user or system associated with a history record. type: string type: description: The type of the user or system associated with a history record. type: string url: description: The URL of the user or system associated with a history record. type: string type: object description: Details of the cause that triggered the creation the history record. description: description: The description of the history record. type: string descriptionKey: description: The description key of the history record. type: string emailDescription: description: The description of the email address associated the history record. type: string emailDescriptionKey: description: The description key of the email address associated the history record. type: string extraData: additionalProperties: type: string description: Additional arbitrary information about the history record. type: object generator: allOf: - additionalProperties: true description: Details of user or system associated with a issue history metadata item. properties: avatarUrl: description: The URL to an avatar for the user or system associated with a history record. type: string displayName: description: The display name of the user or system associated with a history record. type: string displayNameKey: description: The key of the display name of the user or system associated with a history record. type: string id: description: The ID of the user or system associated with a history record. type: string type: description: The type of the user or system associated with a history record. type: string url: description: The URL of the user or system associated with a history record. type: string type: object description: Details of the system that generated the history record. type: description: The type of the history record. type: string type: object description: The history metadata associated with the changed. readOnly: true id: description: The ID of the changelog. readOnly: true type: string items: description: The list of items changed. items: additionalProperties: false description: A change item. properties: field: description: The name of the field changed. readOnly: true type: string fieldId: description: The ID of the field changed. readOnly: true type: string fieldtype: description: The type of the field changed. readOnly: true type: string from: description: The details of the original value. readOnly: true type: string fromString: description: The details of the original value as a string. readOnly: true type: string to: description: The details of the new value. readOnly: true type: string toString: description: The details of the new value as a string. readOnly: true type: string type: object readOnly: true type: array type: object 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 description: Details of changelogs associated with the issue. readOnly: true editmeta: allOf: - description: A list of editable field details. properties: fields: additionalProperties: additionalProperties: false description: The metadata describing an issue field. properties: allowedValues: description: The list of values allowed in the field. items: readOnly: true readOnly: true type: array autoCompleteUrl: description: The URL that can be used to automatically complete the field. readOnly: true type: string configuration: additionalProperties: readOnly: true description: The configuration properties. readOnly: true type: object defaultValue: description: The default value of the field. readOnly: true hasDefaultValue: description: Whether the field has a default value. readOnly: true type: boolean key: description: The key of the field. readOnly: true type: string name: description: The name of the field. readOnly: true type: string operations: description: The list of operations that can be performed on the field. items: readOnly: true type: string readOnly: true type: array required: description: Whether the field is required. readOnly: true type: boolean schema: allOf: - additionalProperties: false description: The schema of a field. properties: configuration: additionalProperties: readOnly: true description: If the field is a custom field, the configuration of the field. readOnly: true type: object custom: description: If the field is a custom field, the URI of the field. readOnly: true type: string customId: description: If the field is a custom field, the custom ID of the field. format: int64 readOnly: true type: integer items: description: When the data type is an array, the name of the field items within the array. readOnly: true type: string system: description: If the field is a system field, the name of the field. readOnly: true type: string type: description: The data type of the field. readOnly: true type: string required: - type type: object description: The data type of the field. readOnly: true required: - key - name - operations - required - schema type: object xml: name: availableField readOnly: true type: object type: object 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: additionalProperties: false properties: actuallyIncluded: items: type: string type: array uniqueItems: true excluded: items: type: string type: array uniqueItems: true included: items: type: string type: array uniqueItems: true type: object 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: additionalProperties: false description: The schema of a field. properties: configuration: additionalProperties: readOnly: true description: If the field is a custom field, the configuration of the field. readOnly: true type: object custom: description: If the field is a custom field, the URI of the field. readOnly: true type: string customId: description: If the field is a custom field, the custom ID of the field. format: int64 readOnly: true type: integer items: description: When the data type is an array, the name of the field items within the array. readOnly: true type: string system: description: If the field is a system field, the name of the field. readOnly: true type: string type: description: The data type of the field. readOnly: true type: string required: - type type: object 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: additionalProperties: true description: Details of an issue transition. properties: expand: description: Expand options that include additional transition details in the response. readOnly: true type: string fields: additionalProperties: additionalProperties: false description: The metadata describing an issue field. properties: allowedValues: description: The list of values allowed in the field. items: readOnly: true readOnly: true type: array autoCompleteUrl: description: The URL that can be used to automatically complete the field. readOnly: true type: string configuration: additionalProperties: readOnly: true description: The configuration properties. readOnly: true type: object defaultValue: description: The default value of the field. readOnly: true hasDefaultValue: description: Whether the field has a default value. readOnly: true type: boolean key: description: The key of the field. readOnly: true type: string name: description: The name of the field. readOnly: true type: string operations: description: The list of operations that can be performed on the field. items: readOnly: true type: string readOnly: true type: array required: description: Whether the field is required. readOnly: true type: boolean schema: allOf: - additionalProperties: false description: The schema of a field. properties: configuration: additionalProperties: readOnly: true description: If the field is a custom field, the configuration of the field. readOnly: true type: object custom: description: If the field is a custom field, the URI of the field. readOnly: true type: string customId: description: If the field is a custom field, the custom ID of the field. format: int64 readOnly: true type: integer items: description: When the data type is an array, the name of the field items within the array. readOnly: true type: string system: description: If the field is a system field, the name of the field. readOnly: true type: string type: description: The data type of the field. readOnly: true type: string required: - type type: object description: The data type of the field. readOnly: true required: - key - name - operations - required - schema type: object xml: name: availableField description: Details of the fields associated with the issue transition screen. Use this information to populate `fields` and `update` in a transition request. readOnly: true type: object hasScreen: description: Whether there is a screen associated with the issue transition. readOnly: true type: boolean id: description: The ID of the issue transition. Required when specifying a transition to undertake. type: string isAvailable: description: Whether the transition is available to be performed. readOnly: true type: boolean isConditional: description: Whether the issue has to meet criteria before the issue transition is applied. readOnly: true type: boolean isGlobal: description: Whether the issue transition is global, that is, the transition is applied to issues regardless of their status. readOnly: true type: boolean isInitial: description: Whether this is the initial issue transition for the workflow. readOnly: true type: boolean looped: type: boolean name: description: The name of the issue transition. readOnly: true type: string to: allOf: - 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: - 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: - additionalProperties: false description: Details about a project. properties: avatarUrls: allOf: - 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 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: - 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 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 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 description: The scope of the field. readOnly: true self: description: The URL of the status. readOnly: true type: string statusCategory: allOf: - 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 description: The category assigned to the status. readOnly: true type: object description: Details of the issue status after the transition. readOnly: true type: object 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 SoftwareIssueResults: additionalProperties: false description: The result of an issue search in Jira Software APIs. properties: expand: description: Expand options that include additional search result details in the response. readOnly: true type: string isLast: description: Indicates whether this is the last page of the paginated response. readOnly: true type: boolean issues: description: The list of issues found by the search. items: $ref: '#/components/schemas/IssueBean' readOnly: true type: array names: additionalProperties: readOnly: true type: string description: The ID and name of each field in the search results. readOnly: true type: object nextPageToken: description: Continuation token to fetch the next page. If this result represents the last or only page, this token will be null. readOnly: true type: string schema: additionalProperties: $ref: '#/components/schemas/JsonTypeBean' description: The schema describing the field types in the search results. readOnly: true type: object warningMessages: description: Any warnings related to the JQL query. items: readOnly: true type: string readOnly: true type: array type: object JsonTypeBean: additionalProperties: false description: The schema of a field. properties: configuration: additionalProperties: readOnly: true description: If the field is a custom field, the configuration of the field. readOnly: true type: object custom: description: If the field is a custom field, the URI of the field. readOnly: true type: string customId: description: If the field is a custom field, the custom ID of the field. format: int64 readOnly: true type: integer items: description: When the data type is an array, the name of the field items within the array. readOnly: true type: string system: description: If the field is a system field, the name of the field. readOnly: true type: string type: description: The data type of the field. readOnly: true type: string required: - type type: object 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: - anchor: introduction body: "Welcome to the Jira Software Cloud REST API reference. You can use this REST API to build add-ons for Jira Software,\ndevelop integrations between Jira Software and other applications, or script interactions with Jira Software. This page\ndocuments the REST resources available in Jira Software Cloud, along with expected HTTP response codes and sample\nrequests.\n\nJira Software is built on the Jira platform. As such, there is an overlap in functionality\nbetween what is provided by Jira Software and what is provided by the Jira platform. The REST API reference for the\nJira Cloud platform is here: [Jira Cloud platform REST API](https://developer.atlassian.com/cloud/jira/platform/rest).\n\n## Authentication\n\n### Authentication for Atlassian Connect add-ons\n\nIf you are integrating with the Jira REST APIs via an Atlassian Connect add-on, API calls are authenticated via JWT\n(JSON Web Tokens). This is built into the supported Atlassian Connect libraries. At a high level, authentication works\nby the add-on exchanging a security context with the application. This context is used to create and validate JWT\ntokens, embedded in API calls. To learn more, read the [Atlassian Connect authentication documentation](https://developer.atlassian.com/cloud/jira/platform/authentication-for-apps/).\n\nSome integration APIs such as [Feature Flags](#api-group-Feature-Flags) are only available to Atlassian Connect apps that\ndefine the relevant [module](https://developer.atlassian.com/cloud/jira/platform/about-jira-modules/) related to that API.\nOther APIs, such as the [Development Information](#api-group-Development-Information), [Builds](#api-group-Builds), and [Deployments](#api-group-Deployments) APIs\nare available to both Atlassian Connect apps and on-premises tools using Jira Software's\n[OAuth credentials](https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/) for system-to-system integration.\n\n### Authentication for REST API requests\n\nIf you are integrating directly with the REST APIs, rather than via an Atlassian Connect add-on, use one of the\nauthentication methods listed below:\n* [OAuth 2.0](https://developer.atlassian.com/cloud/jira/software/scopes-for-oauth-2-3LO-and-forge-apps/) -\n This token-based method is the recommended method. It is more flexible and secure than other options.\n * [OAuth 1.0a](https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-oauth-authentication) -\n This is a legacy authentication method and, therefore, isn't recommended. Instead use OAuth 2.0.\n * [Basic HTTP](https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-basic-authentication/) -\n This method is only recommended for tools like scripts or bots. It is easier to implement, but much less secure.\n\nNote, Jira itself uses cookie-based authentication in the browser, so you can call REST from Javascript on the page and\nrely on the authentication that the browser has established. To reproduce the behavior of the Jira log-in page (for\nexample, to display authentication error messages to users) can `POST` to the `/auth/1/session` [resource](https://docs.atlassian.com/jira/REST/cloud/#auth/1/session).\n\n### Authentication for on-premises integrations\n\nIf you are integrating an on-premises app with the Jira REST APIs, API calls are authenticated via an OAuth token.\nTo obtain a token, create a set of OAuth credentials with permissions for the APIs that app needs to access.\nUse the credentials to request a token by calling `https://api.atlassian.com/oauth/token`.\nSee [Integrating Jira Software Cloud with on-premises tools](https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/) for details.\nNote that only the [Development Information](#api-group-Development-Information), [Builds](#api-group-Builds), and [Deployments](#api-group-Deployments) APIs are currently available for on-premises integrations.\nTo simplify development, we have a separate [downloadable API spec](https://developer.atlassian.com/cloud/jira/software/on-premise-swagger.json).\n\nAtlassian has developed an [open source plugin for Jenkins](https://github.com/jenkinsci/atlassian-jira-software-cloud-plugin), which you can use to bootstrap development.\nThis plugin uses the authentication method described above and calls the Builds and Deployments APIs.\n\n\n#### Base URL differences\n\nWhen building an on-premises integration, the base URL for API operations is different to the base URL used for Connect apps. This is because requests from on-premises integrations (OAuth) need to be sent via the Atlassian API proxy at `https://api.atlassian.com`.\n\nThis document does not display the base URLs used by on-premises integrations. Therefore, when using an operation, you must replace `https://your-domain.atlassian.net/rest/{type}/{version}/{operation}`\nwith `https://api.atlassian.com/jira/{type}/{version}/cloud/{cloudId}/{operation}`.\n\nFor example:\n* Builds API: Change the path from `https://your-domain.atlassian.net/rest/builds/0.1/bulk` to `https://api.atlassian.com/jira/builds/0.1/cloud/{cloudId}/bulk`.\n* Development Information: Change the path from `https://your-domain.atlassian.net/rest/devinfo/0.10/bulk` to `https://api.atlassian.com/jira/devinfo/0.1/cloud/{cloudId}/bulk`. Note the version change.\n* Deployments: Change the path from `https://your-domain.atlassian.net/rest/deployments/0.1/bulk` to `https://api.atlassian.com/jira/deployments/0.1/cloud/{cloudId}/bulk`.\n\nNote, get the `cloudId` for a Jira instance by calling `https://your-domain.atlassian.net/_edge/tenant_info`.\n\n\n## URI structure\n\nJira Agile's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application\nwill make an HTTP request and parse the response. The Jira Agile REST API uses [JSON](http://en.wikipedia.org/wiki/JSON)\nas its communication format, and the standard HTTP methods like `GET`, `PUT`, `POST` and `DELETE` (see API descriptions\nbelow for which methods are available for each resource). URIs for Jira Agile's REST API resource have the following\nstructure:\n\n http://host:port/context/rest/api-name/api-version/resource-name\n\nCurrently there are two API names available, which will be discussed further below:\n\n * `auth` - for authentication-related operations, and\n * `api` - for everything else.\n\nThe current API version is `1`. However, there is also a symbolic version, called `latest`, which resolves to the\nlatest version supported by the given Jira Software Cloud instance. For example, if you wanted to retrieve the JSON\nrepresentation of a board with `boardId=123`, from a Jira Software Cloud instance at `https://jira.atlassian.net`, you\nwould access:\n\n https://jira.atlassian.net/rest/agile/latest/board/123\n\n## Pagination\n\nPagination is used for the Jira REST APIs to conserve server resources and limit response size for resources that\nreturn potentially large collection of items. A request to a pages API will result in a values array wrapped in a JSON\nobject with some paging metadata, like this:\n\n#### Request\n\n http://host:port/context/rest/api-name/api-version/resource-name?startAt=0&maxResults=10\n\n#### Response\n\n```javascript\n{\n \"startAt\" : 0,\n \"maxResults\" : 10,\n \"total\": 200,\n \"values\": [\n { /* result 0 */ },\n { /* result 1 */ },\n { /* result 2 */ }\n ]\n}\n```\n\n * `startAt` - the item used as the first item in the page of results.\n * `maxResults` - how many results to return per page.\n * `total` - the number of items that the calling user has permissions for. This number *may change* while the client requests the next pages. A client should always assume that the requested page can be empty. REST API consumers should also consider the field to be optional. This value may not be included in the response, if it is too expensive to calculate.\n\nClients can use the `startAt`, `maxResults`, and `total` parameters to retrieve the desired number of results. Note,\neach API resource or method may have a different limit on the number of items returned, which means you can ask for\nmore than you are given. The actual number of items returned is an implementation detail and this can be changed over\ntime.\n\n## Experimental methods\n\nMethods marked as experimental may change without an earlier notice. We are looking for your feedback for these methods.\n\n## Query parameters\n\nAll query parameters for the resources described below are optional, unless specified otherwise.\n\n## Special Request and Response headers\n\n - **X-Atlassian-Token** (request): Operations that accept multipart/form-data must include the `X-Atlassian-Token: no-check` header in requests.\nOtherwise the request will be blocked by XSRF protection.\n- **X-AACCOUNTID** (response): This response header contains the Atlassian account ID of the authenticated user.\n\n## Jira Software field input formats\n\nJira Software provides a number of custom fields, which are made available in the Jira platform REST API. The custom\nfields are: `Sprint`, `Epic link`, `Epic name`, and `Story points`.\n\nYou can read and edit these custom fields via the [issue resource](https://docs.atlassian.com/jira/REST/cloud/#api/2/issue)\nof the Jira Platform REST API. In order to identify the custom field that you want to read or edit, you'll need the\ncustom field id. To obtain the custom field id, retrieve the list of fields from the [fields resource](https://docs.atlassian.com/jira/REST/latest/#api/2/field-getFields)\nand search for the custom field. It's better to find the field based on the schema where possible (e.g. the Sprint\nfield is identified by \"`com.pyxis.greenhopper.jira:gh-sprint`\"), as custom field names are mutable. The custom field\nid will be in the id, (e.g. `id: customfield_10007`).\n\nIf you only need to get the value of the custom field for a single issue, you may want to use the [issue resource](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/issue-getIssue)\nprovided by the Jira Software REST API instead. This resource returns the issue with all Jira Software-specific fields,\nincluding the fields listed above. These fields will also be formatted as proper fields with keys, in the response.\n\nNote, Jira Software also has a number of internal custom fields, which are: `Epic Color`, `Epic Status`, `Flag`, `Rank`.\nThese internal fields shouldn't be read or updated using the REST API and are not documented below.\n\n##### Sprint custom field\n\nThe Sprint custom field contains a list of sprints for a given issue. This list includes the active/future sprint that\nthe issue is currently in, as well as any closed sprints that the issue was in previously.\n\nFor legacy reasons, the [Get issue (Jira platform) method](https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getIssue)\nreturns the Sprint custom field with sprints in a `toString` format, which is difficult to parse. See the example below.\n\n_**Deprecation notice:** The `toString` representation of sprints in the Sprint custom field that is returned by Get\nissue (Jira platform) will soon be removed. See the [notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-tostring-representation-of-sprints-in-get-issue-response/)._\n\n###### Example - Get issue (Jira platform) response\n\n```javascript\ncustomfield_11458\": [\n \"com.atlassian.greenhopper.service.sprint.Sprint@1bf75fd[id=1,rapidViewId=1,state=CLOSED,name=Sprint 1,goal=Sprint 1 goal,startDate=2016-06-06T21:30:53.537+10:00,endDate=2016-06-20T21:30:00.000+10:00,completeDate=2016-06-06T21:30:57.523+10:00,sequence=1]\",\n \"com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=,endDate=,completeDate=,sequence=2]\"\n]\n```\n\nIf you want to parse the sprint information, use either the [Get issue (Jira Software) method](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/issue-getIssue)\nor [Get issue (Jira platform) method](https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getIssue) with expanded\n`versionedRepresentations` instead, both of which return sprints in a proper format. See the example below.\n\n###### Example - Get issue (Jira platform) response with expanded versionedRepresentations\n\n```javascript\n\"customfield_10021\": {\n \"1\": [\n \"com.atlassian.greenhopper.service.sprint.Sprint@1bf75fd[id=1,rapidViewId=1,state=CLOSED,name=Sprint 1,goal=Sprint 1 goal,startDate=2016-06-06T21:30:53.537+10:00,endDate=2016-06-20T21:30:00.000+10:00,completeDate=2016-06-06T21:30:57.523+10:00,sequence=1]\",\n \"com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=,endDate=,completeDate=,sequence=2]\"\n ],\n \"2\": [\n {\n \"id\": 1,\n \"name\": \"Sprint 1\",\n \"state\": \"closed\",\n \"boardId\": 1\n },\n {\n \"id\": 2,\n \"name\": \"Sprint 2\",\n \"state\": \"future\",\n \"boardId\": 1\n }\n ]\n}\n```\n\nIf you want to update a sprint, you need to know the sprint id, which is a number. See the example below. Note, an\nissue can only be in one active or future sprint at a time, and only the active/future sprint can edited.\n\n###### Example - Update issue request\n\n```javascript\n\"customfield_10021\": 2\n```\n\n##### Epic link custom field\n\nThe Epic link custom field contains the key of an epic that a given issue belongs to. Be aware that only the issue key\nof the existing epic can be set. Also, the Epic link cannot be set for sub-tasks and epics.\n\n###### Example\n\n```javascript\n\"customfield_11458\": \"EPIC-1\"\n```\n\n##### Epic Name\n\nThe Epic name custom field contains the name of an epic that a given issue belongs to. Be aware that only the issue key\nof the existing epic can be set. Also, the epic link cannot be set for sub-tasks and epics.\n\n###### Example\n\n```javascript\n\"customfield_11410\": \"Epic Name\"\n```\n\n##### Estimation\n\nJira Software provides a `Story Points` custom field, however the field is just a regular numeric field. The type of\nestimation and field used for estimation is determined by the board configuration. You can get this from the\n[board configuration resource](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/board-getConfiguration).\nNote that if the estimation field is not on a screen, it cannot be edited, and you should use the\n[Estimate issue for board method](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/issue-estimateIssueForBoard) instead.\n" title: Introduction