Support for Server products ended Feb. 15, 2024. Learn what this means for you.

Server

Jira Data Center / Reference / REST API

epic

Operations

GET/agile/1.0/epic/none/issue POST/agile/1.0/epic/none/issue GET/agile/1.0/epic/{epicIdOrKey}POST/agile/1.0/epic/{epicIdOrKey}GET/agile/1.0/epic/{epicIdOrKey}/issue POST/agile/1.0/epic/{epicIdOrKey}/issue PUT/agile/1.0/epic/{epicIdOrKey}/rank

GET

Get issues without an 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.

Request

Query parameters

expand

string

jql

string

maxResults

integer

validateQuery

boolean

fields

array<StringList>

startAt

integer

Responses

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

application/json

SearchResultsBean

GET/agile/1.0/epic/none/issue

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'http://{baseurl}/rest/agile/1.0/epic/none/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

POST

Remove issues from any 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.

Request

Request bodyapplication/json

The issues to remove from epics.

issues

array<string>

Responses

Empty response is returned if operation was successful.

POST/agile/1.0/epic/none/issue

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/agile/1.0/epic/none/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json'

GET

Get an epic by id or key

Returns the epic for a given epic Id. This epic will only be returned if the user has permission to view it.

Request

Path parameters

epicIdOrKey

string

Required

Responses

Returns the requested epic.

application/json

EpicBean

GET/agile/1.0/epic/{epicIdOrKey}

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'http://{baseurl}/rest/agile/1.0/epic/{epicIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

POST

Update an epic's details

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.

Request

Path parameters

epicIdOrKey

string

Required

Request bodyapplication/json

The epic properties to update.

color

ColorBean

done

boolean

name

string

summary

string

Responses

Updated epic

application/json

EpicBean

POST/agile/1.0/epic/{epicIdOrKey}

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/agile/1.0/epic/{epicIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

GET

Get issues for a specific 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.

Request

Path parameters

epicIdOrKey

string

Required

Query parameters

expand

string

jql

string

maxResults

integer

validateQuery

boolean

fields

array<StringList>

startAt

integer

Responses

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

application/json

SearchResultsBean

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

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'http://{baseurl}/rest/agile/1.0/epic/{epicIdOrKey}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

POST

Move issues to a specific 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.

Request

Path parameters

epicIdOrKey

string

Required

Request bodyapplication/json

The issues to move to the epic.

issues

array<string>

Responses

Empty response is returned if operation was successful.

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

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/agile/1.0/epic/{epicIdOrKey}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json'

PUT

Rank an epic relative to another

Moves (ranks) an epic before or after a given epic. If rankCustomFieldId is not defined, the default rank field will be used.

Request

Path parameters

epicIdOrKey

string

Required

Request bodyapplication/json

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

rankAfterEpic

string

rankBeforeEpic

string

rankCustomFieldId

integer

Responses

Empty response is returned if operation was successful.

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

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/agile/1.0/epic/{epicIdOrKey}/rank' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json'