Backlog
Board
Epic
Issue
Sprint
Development Information
Feature Flags
Deployments
Builds
Remote Links
Security Information
Other operations

Rate this page:

Epic

Apis related to epics

Get issues without epic

GET /rest/agile/1.0/epic/none/issue

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.

Connect app scope required: READ

OAuth 2.0 scopes required:
read:epic:jira-software
, read:issue-details:jira, read:jql:jira

Request

Query parameters
startAt

integer

The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.

Format: int64
maxResults

integer

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.

Format: int32
jql

string

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.

validateQuery

boolean

Specifies whether to validate the JQL query or not. Default: true.

fields

Array<object>

The list of fields to return for each issue. By default, all navigable and Agile fields are returned.

expand

string

A comma-separated list of the parameters to expand.

Example

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'

Responses

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

Content typeValue
application/json

anything

Example response (application/json)

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
        }
      }
    }
  ]
}

Remove issues from epic

POST /rest/agile/1.0/epic/none/issue

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

Connect app scope required: WRITE

OAuth 2.0 scopes required:
write:epic:jira-software

Request

Body parameters
issues

Array<string>

Unique items: true

Example

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"
  ]
}'

Responses

Empty response is returned if operation was successful.

Get epic

GET /rest/agile/1.0/epic/{epicIdOrKey}

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.

Connect app scope required: READ

OAuth 2.0 scopes required:
read:epic:jira-software

Request

Path parameters
epicIdOrKey Required

string

The id or key of the requested epic.

Example

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'

Responses

Returns the requested epic.

Content typeValue
application/json

anything

Example response (application/json)

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
}

Partially update epic

POST /rest/agile/1.0/epic/{epicIdOrKey}

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.

Connect app scope required: WRITE

OAuth 2.0 scopes required:
write:epic:jira-software

Request

Path parameters
epicIdOrKey Required

string

The id or key of the epic to update.

Body parameters
name

string

summary

string

color

object

done

boolean

Example

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
}'

Responses

Updated epic

Content typeValue
application/json

anything

Example response (application/json)

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 issues for epic

GET /rest/agile/1.0/epic/{epicIdOrKey}/issue

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.

Connect app scope required: READ

OAuth 2.0 scopes required:
read:epic:jira-software
, read:issue-details:jira, read:jql:jira

Request

Path parameters
epicIdOrKey Required

string

The id or key of the epic that contains the requested issues.

Query parameters
startAt

integer

The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.

Format: int64
maxResults

integer

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.

Format: int32
jql

string

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.
Note that username and userkey can't be used as search terms for this parameter due to privacy reasons. Use accountId instead.

validateQuery

boolean

Specifies whether to validate the JQL query or not. Default: true.

fields

Array<object>

The list of fields to return for each issue. By default, all navigable and Agile fields are returned.

expand

string

A comma-separated list of the parameters to expand.

Example

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'

Responses

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

Content typeValue
application/json

anything

Example response (application/json)

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
        }
      }
    }
  ]
}

Move issues to epic

POST /rest/agile/1.0/epic/{epicIdOrKey}/issue

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.

Connect app scope required: WRITE

OAuth 2.0 scopes required:
write:epic:jira-software

Request

Path parameters
epicIdOrKey Required

string

The id or key of the epic that you want to assign issues to.

Body parameters
issues

Array<string>

Unique items: true

Example

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"
  ]
}'

Responses

Empty response is returned if operation was successful.

Rank epics

PUT /rest/agile/1.0/epic/{epicIdOrKey}/rank

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.

Connect app scope required: WRITE

OAuth 2.0 scopes required:
write:epic:jira-software

Request

Path parameters
epicIdOrKey Required

string

The id or key of the epic to rank.

Body parameters
rankBeforeEpic

string

rankAfterEpic

string

rankCustomFieldId

integer

Format: int64

Example

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
}'

Responses

Empty response is returned if operation was successful.

Rate this page: