• Backlog
  • Board
  • Epic
  • Issue
  • Sprint
  • Development Information
  • Feature Flags
  • Deployments
  • Builds
  • Security Information
Cloud
Jira Software Cloud / Reference / REST API

Epic

Postman Collection
OpenAPI
GET

Get issues without epic

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.

Scopes

Connect app scope requiredREAD

read:epic:jira-software
, read:issue-details:jira, read:jql:jira

Request

Query parameters

startAt

integer

maxResults

integer

jql

string

validateQuery

boolean

fields

array<object>

expand

string

Responses

Returns the requested issues, at the specified page of the results.

application/json

any

GET/rest/agile/1.0/epic/none/issue
1 2 3 4 curl --request GET \ --url 'https://your-domain.atlassian.com/rest/agile/1.0/epic/none/issue' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 { "expand": "names,schema", "startAt": 0, "maxResults": 50, "total": 1, "issues": [ { "expand": "", "id": "10001", "self": "https://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001", "key": "HSP-1", "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": { "self": "https://your-domain.atlassian.net/rest/api/3/project/EX", "id": "10000", "key": "EX", "name": "Example", "avatarUrls": { "48x48": "https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000", "24x24": "https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000", "16x16": "https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000", "32x32": "https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000" }, "projectCategory": { "self": "https://your-domain.atlassian.net/rest/api/3/projectCategory/10000", "id": "10000", "name": "FIRST", "description": "First Project Category" }, "simplified": false, "style": "classic", "insight": { "totalIssueCount": 100, "lastIssueUpdateTime": "2022-11-15T23:15:20.052+0000" } }, "comment": [ { "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000", "id": "10000", "author": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "accountId": "5b10a2844c20165700ede21g", "displayName": "Mia Krystof", "active": false }, "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." } ] } ] }, "updateAuthor": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "accountId": "5b10a2844c20165700ede21g", "displayName": "Mia Krystof", "active": false }, "created": "2021-01-17T12:34:00.000+0000", "updated": "2021-01-18T23:45:00.000+0000", "visibility": { "type": "role", "value": "Administrators", "identifier": "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": [ { "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000", "author": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "accountId": "5b10a2844c20165700ede21g", "displayName": "Mia Krystof", "active": false }, "updateAuthor": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "accountId": "5b10a2844c20165700ede21g", "displayName": "Mia Krystof", "active": false }, "comment": { "type": "doc", "version": 1, "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "I did some work here." } ] } ] }, "updated": "2021-01-18T23:45:00.000+0000", "visibility": { "type": "group", "value": "jira-developers", "identifier": "276f955c-63d7-42c8-9520-92d01dca0625" }, "started": "2021-01-17T12:34:00.000+0000", "timeSpent": "3h 20m", "timeSpentSeconds": 12000, "id": "100028", "issueId": "10002" } ], "updated": 1, "timetracking": { "originalEstimate": "10m", "remainingEstimate": "3m", "timeSpent": "6m", "originalEstimateSeconds": 600, "remainingEstimateSeconds": 200, "timeSpentSeconds": 400 } } } ] }
POST

Remove issues from epic

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: \{\} \} \}

Scopes

Connect app scope requiredWRITE

write:epic:jira-software

Request

Request bodyapplication/json

issues

array<string>

Responses

Empty response is returned if operation was successful.

POST/rest/agile/1.0/epic/none/issue
1 2 3 4 5 6 7 8 9 10 11 curl --request POST \ --url 'https://your-domain.atlassian.com/rest/agile/1.0/epic/none/issue' \ --header 'Authorization: Bearer <access_token>' \ --header 'Content-Type: application/json' \ --data '{ "issues": [ "PR-1", "10001", "PR-3" ] }'
GET

Get epic

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.

Scopes

Connect app scope requiredREAD

read:epic:jira-software

Request

Path parameters

epicIdOrKey

string

Required

Responses

Returns the requested epic.

application/json

any

GET/rest/agile/1.0/epic/{epicIdOrKey}
1 2 3 4 curl --request GET \ --url 'https://your-domain.atlassian.com/rest/agile/1.0/epic/{epicIdOrKey}' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 { "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 }
POST

Partially update epic

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.

Scopes

Connect app scope requiredWRITE

write:epic:jira-software

Request

Path parameters

epicIdOrKey

string

Required

Request bodyapplication/json

name

string

summary

string

color

object

done

boolean

Responses

Updated epic

application/json

any

POST/rest/agile/1.0/epic/{epicIdOrKey}
1 2 3 4 5 6 7 8 9 10 11 12 13 curl --request POST \ --url 'https://your-domain.atlassian.com/rest/agile/1.0/epic/{epicIdOrKey}' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "summary": "epic 2 summary", "color": { "key": "color_6" }, "name": "epic 2", "done": true }'
200Response
1 2 3 4 5 6 7 8 9 10 { "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 }
GET

Get issues for epic

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.

Scopes

Connect app scope requiredREAD

read:epic:jira-software
, read:issue-details:jira, read:jql:jira

Request

Path parameters

epicIdOrKey

string

Required

Query parameters

startAt

integer

maxResults

integer

jql

string

validateQuery

boolean

fields

array<object>

expand

string

Responses

Returns the requested issues, at the specified page of the results.

application/json

any

GET/rest/agile/1.0/epic/{epicIdOrKey}/issue
1 2 3 4 curl --request GET \ --url 'https://your-domain.atlassian.com/rest/agile/1.0/epic/{epicIdOrKey}/issue' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 { "expand": "names,schema", "startAt": 0, "maxResults": 50, "total": 1, "issues": [ { "expand": "", "id": "10001", "self": "https://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001", "key": "HSP-1", "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": { "self": "https://your-domain.atlassian.net/rest/api/3/project/EX", "id": "10000", "key": "EX", "name": "Example", "avatarUrls": { "48x48": "https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000", "24x24": "https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000", "16x16": "https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000", "32x32": "https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000" }, "projectCategory": { "self": "https://your-domain.atlassian.net/rest/api/3/projectCategory/10000", "id": "10000", "name": "FIRST", "description": "First Project Category" }, "simplified": false, "style": "classic", "insight": { "totalIssueCount": 100, "lastIssueUpdateTime": "2022-11-15T23:15:20.052+0000" } }, "comment": [ { "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000", "id": "10000", "author": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "accountId": "5b10a2844c20165700ede21g", "displayName": "Mia Krystof", "active": false }, "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." } ] } ] }, "updateAuthor": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "accountId": "5b10a2844c20165700ede21g", "displayName": "Mia Krystof", "active": false }, "created": "2021-01-17T12:34:00.000+0000", "updated": "2021-01-18T23:45:00.000+0000", "visibility": { "type": "role", "value": "Administrators", "identifier": "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": [ { "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000", "author": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "accountId": "5b10a2844c20165700ede21g", "displayName": "Mia Krystof", "active": false }, "updateAuthor": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "accountId": "5b10a2844c20165700ede21g", "displayName": "Mia Krystof", "active": false }, "comment": { "type": "doc", "version": 1, "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "I did some work here." } ] } ] }, "updated": "2021-01-18T23:45:00.000+0000", "visibility": { "type": "group", "value": "jira-developers", "identifier": "276f955c-63d7-42c8-9520-92d01dca0625" }, "started": "2021-01-17T12:34:00.000+0000", "timeSpent": "3h 20m", "timeSpentSeconds": 12000, "id": "100028", "issueId": "10002" } ], "updated": 1, "timetracking": { "originalEstimate": "10m", "remainingEstimate": "3m", "timeSpent": "6m", "originalEstimateSeconds": 600, "remainingEstimateSeconds": 200, "timeSpentSeconds": 400 } } } ] }
POST

Move issues to epic

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.

Scopes

Connect app scope requiredWRITE

write:epic:jira-software

Request

Path parameters

epicIdOrKey

string

Required

Request bodyapplication/json

issues

array<string>

Responses

Empty response is returned if operation was successful.

POST/rest/agile/1.0/epic/{epicIdOrKey}/issue
1 2 3 4 5 6 7 8 9 10 11 curl --request POST \ --url 'https://your-domain.atlassian.com/rest/agile/1.0/epic/{epicIdOrKey}/issue' \ --header 'Authorization: Bearer <access_token>' \ --header 'Content-Type: application/json' \ --data '{ "issues": [ "PR-1", "10001", "PR-3" ] }'
PUT

Rank epics

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.

Scopes

Connect app scope requiredWRITE

write:epic:jira-software

Request

Path parameters

epicIdOrKey

string

Required

Request bodyapplication/json

bean which contains the information where the given epic should be ranked.

rankBeforeEpic

string

rankAfterEpic

string

rankCustomFieldId

integer

Responses

Empty response is returned if operation was successful.

PUT/rest/agile/1.0/epic/{epicIdOrKey}/rank
1 2 3 4 5 6 7 8 curl --request PUT \ --url 'https://your-domain.atlassian.com/rest/agile/1.0/epic/{epicIdOrKey}/rank' \ --header 'Authorization: Bearer <access_token>' \ --header 'Content-Type: application/json' \ --data '{ "rankBeforeEpic": "10000", "rankCustomFieldId": 10521 }'