JIRA API: Get epic for issue

Question

Is there a way in which I could get the epic for an issue ?

The api returns a lot of information about an issue, but the epic is not included.

I'm using the JIRA REST API (https://developer.atlassian.com/display/JIRADEV/JIRA+REST+APIs).

Nictitate

Have you read API for finding Epic Links? – Cyclothymia

Answer 1

I wanted to extract the epic name for an issue and this stumped me for a few days. The key was to realise that an epic is just a parent issue, and the epic name is the summary field of the parent issue.

So:

Step 1

Find the custom field of where the epic is stored by using the editmeta query:

https://[your-jira-hostname]/jira/rest/api/2/issue/[issue-number]/editmeta

This will yield something like below which reveals the custom field Id we need

{
  "fields": {
    <SNIP>
    "customfield_12360": {
      "required": false,
      "schema": {
        "type": "any",
        "custom": "com.pyxis.greenhopper.jira:gh-epic-link",
        "customId": 12360
      },
      "name": "Epic Link",
      "operations": [
        "set"
      ]
    }
    <SNIP>
  }
}

Step 2

Query your issue, pulling out the custom field value

https://[your-jira-hostname]/jira/rest/api/2/issue/[issue-number]?fields=customfield_12360,summary

if our issue is JIRA-34 say, this will yield something like

{
  "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
  "id": "39080",
  "key": "JIRA-34",
  "fields": {
    "summary": "Write heavily upvoted answers for stack overflow",
    "customfield_12360": "JIRA-33"
  }
}

Step 3

Now we know the issue number of our epic is JIRA-33, so now query the epic...

https://[your-jira-hostname]/jira/rest/api/2/issue/JIRA-33?fields=summary

{
      "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
      "id": "39080",
      "key": "JIRA-33",
      "fields": {
        "summary": "Improve StackOverflow reptuation"
      }
    }

The name of the epic for JIRA-34 is "Improve StackOverflow reptuation"

Done.

Nutcracker

Nice! I am not sure if this was supported in the API at the time. Good find! – Nictitate

Instead of Step 1, you can find out the epic link custom field by querying the custom fields API directly, without needing an issue key/id: /rest/api/3/field/search?type=custom&query=Epic%20Link. This is useful if you need to pull out epic links from a call to the issue search API for example. API docs are here: developer.atlassian.com/cloud/jira/platform/rest/v3/… – Parshall

@MikeRippon I think that suggestion is good enough as a separate answer (especially as this answer uses the v2 of the API and might not have that ability). Care to make one? I will upvote it. – Rokach

Answer 2

To get the epic key for an issue:

Send a request to: /issue/ISSUE-NUMBER

And look at the response body:

{
    ...,
    fields: {
        ...,
        customfield_11300: ... <- here, the epic should be listed. The number can be different
    }
}

Nictitate

Hello. I wonder if you could point any knowledge as to why this is the case, or where it would be documented what the exact customField is (and how to find out if it would be different). – Convexoconcave

I really don't know, the documentation was not so good at the time. Maybe try and look into Greenhopper's API. – Nictitate

customFields will likely change on a per-jira-instance basis. Meaning, the custom field your epic link shows up in for you will be different from mine. Mine is customfield_10101, for example. So this is not a reliable way of retrieving the epic link. – Bortz

Answer 3

@fiat have the very clear steps to find the custom field and epic mapping. In my scenario, the whole jira instance is using the same custom field as epic. So I won't need to repeat those steps to map for each project. Hope this could help.

Loren

Answer 4

According to https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-fields/ , you can make a API call to /rest/api/3/field, then you can get data like this:

[
  {
    "id": "customfield_10014",
    "key": "customfield_10014",
    "name": "Epic Link",
    "untranslatedName": "Epic Link",
    "custom": true,
    "orderable": true,
    "navigable": true,
    "searchable": true,
    "clauseNames": [
      "cf[10014]",
      "Epic Link"
    ],
    "schema": {
      "type": "any",
      "custom": "com.pyxis.greenhopper.jira:gh-epic-link",
      "customId": 10014
    }
  },
]

Then look back to your issue json data:

issue:
  fields:
    ....
    customfield_10014: OT-5
    ....

The OT-5 is the Epic's key.

Lorimer