Introduction

Welcome to the Jira Software Cloud REST API reference. You can use this REST API to build add-ons for Jira Software, develop integrations between Jira Software and other applications, or script interactions with Jira Software. This page documents the REST resources available in Jira Software Cloud, along with expected HTTP response codes and sample requests.

Looking for the REST API reference for a different Jira version? Follow the links below.

Jira Agile is an add-on, which is part of the Jira Software application and provides the Agile planning features like boards and sprints. Jira Software is built on the Jira platform. As such, there is a natural overlap in functionality between what is provided by Jira Software and what is provided by the Jira platform. The REST API reference for the Jira Cloud platform is here: Jira Cloud platform REST API.

Authentication

Authentication for Atlassian Connect add-ons

If you are integrating with the Jira REST APIs via an Atlassian Connect add-on, API calls are authenticated via JWT (JSON Web Tokens). This is built into the supported Atlassian Connect libraries. At a high level, authentication works by the add-on exchanging a security context with the application. This context is used to create and validate JWT tokens, embedded in API calls. To learn more, read the Atlassian Connect authentication documentation.

Some integration apis such as Development Information and Feature Flags are only available to Atlassian Connect apps that define the relevant module related to that api.

Authentication for REST API requests

If you are integrating directly with the REST APIs, rather than via an Atlassian Connect add-on, use one of the authentication methods listed below:

  • OAuth (1.0a) - This token-based method is the recommended method. It is more flexible and secure than other options.
  • Basic HTTP - This method is only recommended for tools like scripts or bots. It is easier to implement, but much less secure.

Note, Jira itself uses cookie-based authentication in the browser, so you can call REST from Javascript on the page and rely on the authentication that the browser has established. To reproduce the behavior of the Jira log-in page (for example, to display authentication error messages to users) can POST to the /auth/1/session resource.

URI structure

Jira Agile's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The Jira Agile REST API uses JSON as its communication format, and the standard HTTP methods like GET, PUT, POST and DELETE (see API descriptions below for which methods are available for each resource). URIs for Jira Agile's REST API resource have the following structure:

1
http://host:port/context/rest/api-name/api-version/resource-name

Currently there are two API names available, which will be discussed further below:

  • auth - for authentication-related operations, and
  • api - for everything else.

The current API version is 1. However, there is also a symbolic version, called latest, which resolves to the latest version supported by the given Jira Software Cloud instance. For example, if you wanted to retrieve the JSON representation of a board with boardId=123, from a Jira Software Cloud instance at https://jira.atlassian.net, you would access:

1
https://jira.atlassian.net/rest/agile/latest/board/123

Pagination

Pagination is used for the Jira REST APIs to conserve server resources and limit response size for resources that return potentially large collection of items. A request to a pages API will result in a values array wrapped in a JSON object with some paging metadata, like this:

Request

1
http://host:port/context/rest/api-name/api-version/resource-name?startAt=0&maxResults=10

Response

1
2
3
4
5
6
7
8
9
10
{
    "startAt" : 0,
    "maxResults" : 10,
    "total": 200,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
    ]
}
  • startAt - the item used as the first item in the page of results.
  • maxResults - how many results to return per page.
  • 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.

Clients can use the startAt, maxResults, and total parameters to retrieve the desired number of results. Note, each API resource or method may have a different limit on the number of items returned, which means you can ask for more than you are given. The actual number of items returned is an implementation detail and this can be changed over time.

Experimental methods

Methods marked as experimental may change without an earlier notice. We are looking for your feedback for these methods.

Query parameters

All query parameters for the resources described below are optional, unless specified otherwise.

Special Request and Response headers

  • X-AUSERNAME - Response header which contains either username of the authenticated user or 'anonymous'.
  • X-Atlassian-Token - Methods which accept multipart/form-data will only process requests with 'X-Atlassian-Token: no-check' header.

Jira Software field input formats

Jira Software provides a number of custom fields, which are made available in the Jira platform REST API. The custom fields are: Sprint, Epic link, Epic name, and Story points.

You can read and edit these custom fields via the issue resource of the Jira Platform REST API. In order to identify the custom field that you want to read or edit, you'll need the custom field id. To obtain the custom field id, retrieve the list of fields from the fields resource and search for the custom field. It's better to find the field based on the schema where possible (e.g. the Sprint field is identified by "com.pyxis.greenhopper.jira:gh-sprint"), as custom field names are mutable. The custom field id will be in the id, (e.g. id: customfield_10007).

If you only need to get the value of the custom field for a single issue, you may want to use the issue resource provided by the Jira Software REST API instead. This resource returns the issue with all Jira Software-specific fields, including the fields listed above. These fields will also be formatted as proper fields with keys, in the response.

Note, Jira Software also has a number of internal custom fields, which are: Epic Color, Epic Status, Flag, Rank. These internal fields shouldn't be read or updated using the REST API and are not documented below.

Sprint custom field

The Sprint custom field contains a list of sprints for a given issue. This list includes the active/future sprint that the issue is currently in, as well as any closed sprints that the issue was in previously.

For legacy reasons, the Get issue (Jira platform) method returns the Sprint custom field with sprints in a toString format, which is difficult to parse. See the example below.

Deprecation notice: The toString representation of sprints in the Sprint custom field that is returned by Get issue (Jira platform) will soon be removed. See the notice.

Example - Get issue (Jira platform) response
1
2
3
4
customfield_11458": [
    "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]",
    "com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=<null>,endDate=<null>,completeDate=<null>,sequence=2]"
]

If you want to parse the sprint information, use either the Get issue (Jira Software) method or Get issue (Jira platform) method with expanded versionedRepresentations instead, both of which return sprints in a proper format. See the example below.

Example - Get issue (Jira platform) response with expanded versionedRepresentations
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
"customfield_10021": {
    "1": [
        "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]",
        "com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=<null>,endDate=<null>,completeDate=<null>,sequence=2]"
    ],
    "2": [
        {
            "id": 1,
            "name": "Sprint 1",
            "state": "closed",
            "boardId": 1
        },
        {
            "id": 2,
            "name": "Sprint 2",
            "state": "future",
            "boardId": 1
        }
    ]
}

If you want to update a sprint, you need to know the sprint id, which is a number. See the example below. Note, an issue can only be in one active or future sprint at a time, and only the active/future sprint can edited.

Example - Update issue request
1
"customfield_10021": 2
Epic link custom field

The Epic link custom field contains the key of an epic that a given issue belongs to. Be aware that only the issue key of the existing epic can be set. Also, the Epic link cannot be set for sub-tasks and epics.

Example
1
"customfield_11458": "EPIC-1"
Epic Name

The Epic name custom field contains the name of an epic that a given issue belongs to. Be aware that only the issue key of the existing epic can be set. Also, the epic link cannot be set for sub-tasks and epics.

Example
1
"customfield_11410": "Epic Name"
Estimation

Jira Software provides a Story Points custom field, however the field is just a regular numeric field. The type of estimation and field used for estimation is determined by the board configuration. You can get this from the board configuration resource. Note that if the estimation field is not on a screen, it cannot be edited, and you should use the Estimate issue for board method instead.

Backlog

Apis related to the backlog

Move issues to backlog

POST /rest/agile/1.0/backlog/issue

Move issues to the backlog. This operation is equivalent to remove future and active sprints from a given set of issues. At most 50 issues may be moved at once.

App scope requiredWRITE

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.net/rest/agile/1.0/backlog/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "issues": [
    "PR-1",
    "10001",
    "PR-3"
  ]
}'

Responses

Empty response is returned if operation was successful.

Move issues to backlog for board

POST /rest/agile/1.0/backlog/{boardId}/issue

Move issues to the backlog of a particular board (if they are already on that board).
This operation is equivalent to remove future and active sprints from a given set of issues if the board has sprints If the board does not have sprints this will put the issues back into the backlog from the board. At most 50 issues may be moved at once.

App scope requiredWRITE

Request

Path parameters
boardId Required

integer

Format: int64
Body parameters
issues

Array<string>

rankBeforeIssue

string

rankAfterIssue

string

rankCustomFieldId

integer

Format: int64

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/backlog/{boardId}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "issues": [
    "PR-1",
    "10001",
    "PR-3"
  ],
  "rankBeforeIssue": "PR-4",
  "rankCustomFieldId": 10521
}'

Responses

Empty response is returned if operation was successful.

Board

Apis related to boards

Get all boards

GET /rest/agile/1.0/board

Returns all boards. This only includes boards that the user has permission to view.

App scope requiredREAD

Request

Query parameters
startAt

integer

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

Format: int64
maxResults

integer

The maximum number of boards to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.

Format: int32
type

string

Filters results to boards of the specified types. Valid values: scrum, kanban, simple.

name

string

Filters results to boards that match or partially match the specified name.

projectKeyOrId

string

Filters results to boards that are relevant to a project. Relevance means that the jql filter defined in board contains a reference to a project.

accountIdLocation

string

userkeyLocation

string

usernameLocation

string

projectLocation

string

includePrivate

boolean

Appends private boards to the end of the list. The name and type fields are excluded for security reasons.

negateLocationFiltering

boolean

If set to true, negate filters used for querying by location. By default false.

orderBy

string

Ordering of the results by a given field. If not provided, values will not be sorted. Valid values: name.

expand

string

List of fields to expand for each board. Valid values: admins, permissions.

Header parameters
force-account-id

boolean

Default: false

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested boards, 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
{
  "maxResults": 2,
  "startAt": 1,
  "total": 5,
  "isLast": false,
  "values": [
    {
      "id": 84,
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/84",
      "name": "scrum board",
      "type": "scrum"
    },
    {
      "id": 92,
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/92",
      "name": "kanban board",
      "type": "kanban"
    }
  ]
}

Create board

POST /rest/agile/1.0/board

Creates a new board. Board name, type and filter ID is required.

  • name - Must be less than 255 characters.
  • type - Valid values: scrum, kanban
  • filterId - ID of a filter that the user has permissions to view. Note, if the user does not have the 'Create shared objects' permission and tries to create a shared board, a private board will be created instead (remember that board sharing depends on the filter sharing).
  • location - The container that the board will be located in. location must include the type property (Valid values: project, user). If choosing 'project', then a project must be specified by a projectKeyOrId property in location. If choosing 'user', the current user is chosen by default. The projectKeyOrId property should not be provided.

Note:

  • If you want to create a new project with an associated board, use the Jira platform REST API. For more information, see the Create project method. The projectTypeKey for software boards must be 'software' and the projectTemplateKey must be either com.pyxis.greenhopper.jira:gh-kanban-template or com.pyxis.greenhopper.jira:gh-scrum-template.
  • You can create a filter using the Jira REST API. For more information, see the Create filter method.
  • If you do not ORDER BY the Rank field for the filter of your board, you will not be able to reorder issues on the board.

App scope requiredWRITE

Request

Body parameters
name

string

type

string

filterId

integer

Format: int64
location

object

Example

1
2
3
4
5
6
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data 'null'

Responses

Returns the created board.

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
{
  "id": 84,
  "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/84",
  "name": "scrum board",
  "type": "scrum"
}

Get board

GET /rest/agile/1.0/board/{boardId}

Returns the board for the given board ID. This board will only be returned if the user has permission to view it. Admins without the view permission will see the board as a private one, so will see only a subset of the board's data (board location for instance).

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the requested board.

Format: int64

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested board.

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "id": 84,
  "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/84",
  "name": "scrum board",
  "type": "scrum",
  "location": {
    "projectId": 10040,
    "userId": 10040,
    "userAccountId": "99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
    "name": "Example Project",
    "projectName": "Example Project",
    "projectKey": "Example Project Key",
    "projectTypeKey": "KEY"
  }
}

Delete board

DELETE /rest/agile/1.0/board/{boardId}

Deletes the board. Admin without the view permission can still remove the board.

App scope requiredDELETE

Request

Path parameters
boardId Required

integer

ID of the board to be deleted

Format: int64

Example

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the board has been successfully removed.

Get issues for backlog

GET /rest/agile/1.0/board/{boardId}/backlog

Returns all issues from the board's backlog, for the given board ID. This only includes issues that the user has permission to view. The backlog contains incomplete issues that are not assigned to any future or active sprint. Note, if the user does not have permission to view the board, no issues will be returned at all. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that has the backlog containing the requested issues.

Format: int64
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.

validateQuery

boolean

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

fields

Array<string>

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

expand

string

This parameter is currently not used.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/backlog' \
  --user 'email@example.com:<api_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
{
  "expand": "names,schema",
  "startAt": 0,
  "maxResults": 50,
  "total": 1,
  "issues": [
    {
      "expand": "",
      "id": "10001",
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001",
      "key": "HSP-1",
      "fields": {
        "flagged": true,
        "sprint": {
          "id": 37,
          "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/13",
          "state": "future",
          "name": "sprint 2",
          "goal": "sprint 2 goal"
        },
        "closedSprints": [
          {
            "id": 37,
            "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/project/EX",
          "id": "10000",
          "key": "EX",
          "name": "Example",
          "avatarUrls": {
            "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
            "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
            "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
            "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
          },
          "projectCategory": {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
            "id": "10000",
            "name": "FIRST",
            "description": "First Project Category"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000",
            "id": "10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "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": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2018-09-14T03:03:07.240+0000",
            "updated": "2018-09-14T03:03:07.240+0000",
            "visibility": {
              "type": "role",
              "value": "Administrators"
            }
          }
        ],
        "epic": {
          "id": 37,
          "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "updateAuthor": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "comment": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-09-14T03:03:07.248+0000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-09-14T03:03:07.248+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
        }
      }
    }
  ]
}

Get configuration

GET /rest/agile/1.0/board/{boardId}/configuration

Get the board configuration. The response contains the following fields:

  • id - ID of the board.
  • name - Name of the board.
  • filter - Reference to the filter used by the given board.
  • location - Reference to the container that the board is located in. Includes the container type (Valid values: project, user).
  • subQuery (Kanban only) - JQL subquery used by the given board.
  • columnConfig - The column configuration lists the columns for the board, in the order defined in the column configuration. For each column, it shows the issue status mapping as well as the constraint type (Valid values: none, issueCount, issueCountExclSubs) for the min/max number of issues. Note, the last column with statuses mapped to it is treated as the "Done" column, which means that issues in that column will be marked as already completed.
  • estimation (Scrum only) - Contains information about type of estimation used for the board. Valid values: none, issueCount, field. If the estimation type is "field", the ID and display name of the field used for estimation is also returned. Note, estimates for an issue can be updated by a PUT /rest/api/~ver~/issue/{issueIdOrKey} request, however the fields must be on the screen. "timeoriginalestimate" field will never be on the screen, so in order to update it "originalEstimate" in "timetracking" field should be updated.
  • ranking - Contains information about custom field used for ranking in the given board.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board for which configuration is requested.

Format: int64

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/configuration' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the configuration of the board for given boardId.

Content typeValue
application/json

object

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
{
  "id": 10000,
  "name": "Board",
  "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/84/config",
  "location": {
    "type": "project",
    "key": "PROJ",
    "id": "10010",
    "self": "http://your-domain.atlassian.net/rest/api/~ver~/project/10010",
    "name": "name"
  },
  "filter": {
    "id": "1001",
    "self": "http://your-domain.atlassian.net/filter/1001"
  },
  "columnConfig": {
    "columns": [
      {
        "name": "To Do",
        "statuses": [
          {
            "id": "1",
            "self": "http://your-domain.atlassian.net/status/1"
          },
          {
            "id": "4",
            "self": "http://your-domain.atlassian.net/status/4"
          }
        ]
      },
      {
        "name": "In progress",
        "statuses": [
          {
            "id": "3",
            "self": "http://your-domain.atlassian.net/status/3"
          }
        ],
        "min": 2,
        "max": 4
      },
      {
        "name": "Done",
        "statuses": [
          {
            "id": "5",
            "self": "http://your-domain.atlassian.net/status/5"
          }
        ]
      }
    ],
    "constraintType": "issueCount"
  },
  "estimation": {
    "type": "field",
    "field": {
      "fieldId": "customfield_10002",
      "displayName": "Story Points"
    }
  },
  "ranking": {
    "rankCustomFieldId": 10020
  }
}

Get epics

GET /rest/agile/1.0/board/{boardId}/epic

Returns all epics from the board, for the given board ID. This only includes epics that the user has permission to view. Note, if the user does not have permission to view the board, no epics will be returned at all.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested epics.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

The maximum number of epics to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.

Format: int32
done

string

Filters results to epics that are either done or not done. Valid values: true, false.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/epic' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested epics, 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
{
  "maxResults": 2,
  "startAt": 1,
  "total": 5,
  "isLast": false,
  "values": [
    {
      "id": 37,
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/epic/23",
      "name": "epic 1",
      "summary": "epic 1 summary",
      "color": {
        "key": "color_4"
      },
      "done": true
    },
    {
      "id": 37,
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/epic/13",
      "name": "epic 2",
      "summary": "epic 2 summary",
      "color": {
        "key": "color_2"
      },
      "done": false
    }
  ]
}

Get issues without epic

GET /rest/agile/1.0/board/{boardId}/epic/none/issue

Returns all issues that do not belong to any epic on a board, for a given board 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.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested issues.

Format: int64
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.

validateQuery

boolean

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

fields

Array<string>

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.net/rest/agile/1.0/board/{boardId}/epic/none/issue' \
  --user 'email@example.com:<api_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
{
  "expand": "names,schema",
  "startAt": 0,
  "maxResults": 50,
  "total": 1,
  "issues": [
    {
      "expand": "",
      "id": "10001",
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001",
      "key": "HSP-1",
      "fields": {
        "flagged": true,
        "sprint": {
          "id": 37,
          "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/13",
          "state": "future",
          "name": "sprint 2",
          "goal": "sprint 2 goal"
        },
        "closedSprints": [
          {
            "id": 37,
            "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/project/EX",
          "id": "10000",
          "key": "EX",
          "name": "Example",
          "avatarUrls": {
            "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
            "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
            "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
            "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
          },
          "projectCategory": {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
            "id": "10000",
            "name": "FIRST",
            "description": "First Project Category"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000",
            "id": "10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "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": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2018-09-14T03:03:07.240+0000",
            "updated": "2018-09-14T03:03:07.240+0000",
            "visibility": {
              "type": "role",
              "value": "Administrators"
            }
          }
        ],
        "epic": {
          "id": 37,
          "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "updateAuthor": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "comment": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-09-14T03:03:07.248+0000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-09-14T03:03:07.248+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
        }
      }
    }
  ]
}

Get issues for epic

GET /rest/agile/1.0/board/{boardId}/epic/{epicId}/issue

Returns all issues that belong to an epic on the board, for the given epic ID and the board 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.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested issues.

Format: int64
epicId Required

integer

The ID of the epic that contains the requested issues.

Format: int64
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.

validateQuery

boolean

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

fields

Array<string>

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.net/rest/agile/1.0/board/{boardId}/epic/{epicId}/issue' \
  --user 'email@example.com:<api_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
{
  "expand": "names,schema",
  "startAt": 0,
  "maxResults": 50,
  "total": 1,
  "issues": [
    {
      "expand": "",
      "id": "10001",
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001",
      "key": "HSP-1",
      "fields": {
        "flagged": true,
        "sprint": {
          "id": 37,
          "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/13",
          "state": "future",
          "name": "sprint 2",
          "goal": "sprint 2 goal"
        },
        "closedSprints": [
          {
            "id": 37,
            "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/project/EX",
          "id": "10000",
          "key": "EX",
          "name": "Example",
          "avatarUrls": {
            "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
            "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
            "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
            "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
          },
          "projectCategory": {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
            "id": "10000",
            "name": "FIRST",
            "description": "First Project Category"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000",
            "id": "10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "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": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2018-09-14T03:03:07.240+0000",
            "updated": "2018-09-14T03:03:07.240+0000",
            "visibility": {
              "type": "role",
              "value": "Administrators"
            }
          }
        ],
        "epic": {
          "id": 37,
          "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "updateAuthor": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "comment": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-09-14T03:03:07.248+0000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-09-14T03:03:07.248+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
        }
      }
    }
  ]
}

Get features for board

GET /rest/agile/1.0/board/{boardId}/features

App scope requiredREAD

Request

Path parameters
boardId Required

integer

Format: int64

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/features' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

200 response

Content typeValue
application/json

object

Toggle features

PUT /rest/agile/1.0/board/{boardId}/features

App scope requiredWRITE

Request

Path parameters
boardId Required

integer

Format: int64
Body parameters
boardId

integer

Format: int64
feature

string

enabling

boolean

Example

1
2
3
4
5
6
7
8
9
10
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/features' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "boardId": 2154,
  "feature": "<string>",
  "enabling": true
}'

Responses

200 response

Content typeValue
application/json

object

Get issues for board

GET /rest/agile/1.0/board/{boardId}/issue

Returns all issues from a board, for a given board ID. This only includes issues that the user has permission to view. An issue belongs to the board if its status is mapped to the board's column. Epic issues do not belongs to the scrum boards. Note, if the user does not have permission to view the board, no issues will be returned at all. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested issues.

Format: int64
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.

validateQuery

boolean

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

fields

Array<string>

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

expand

string

This parameter is currently not used.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/issue' \
  --user 'email@example.com:<api_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
{
  "expand": "names,schema",
  "startAt": 0,
  "maxResults": 50,
  "total": 1,
  "issues": [
    {
      "expand": "",
      "id": "10001",
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001",
      "key": "HSP-1",
      "fields": {
        "flagged": true,
        "sprint": {
          "id": 37,
          "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/13",
          "state": "future",
          "name": "sprint 2",
          "goal": "sprint 2 goal"
        },
        "closedSprints": [
          {
            "id": 37,
            "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/project/EX",
          "id": "10000",
          "key": "EX",
          "name": "Example",
          "avatarUrls": {
            "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
            "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
            "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
            "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
          },
          "projectCategory": {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
            "id": "10000",
            "name": "FIRST",
            "description": "First Project Category"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000",
            "id": "10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "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": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2018-09-14T03:03:07.240+0000",
            "updated": "2018-09-14T03:03:07.240+0000",
            "visibility": {
              "type": "role",
              "value": "Administrators"
            }
          }
        ],
        "epic": {
          "id": 37,
          "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "updateAuthor": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "comment": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-09-14T03:03:07.248+0000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-09-14T03:03:07.248+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 board

POST /rest/agile/1.0/board/{boardId}/issue

Move issues from the backog to the board (if they are already in the backlog of that board).
This operation either moves an issue(s) onto a board from the backlog (by adding it to the issueList for the board) Or transitions the issue(s) to the first column for a kanban board with backlog. At most 50 issues may be moved at once.

App scope requiredWRITE

Request

Path parameters
boardId Required

integer

Format: int64
Body parameters
issues

Array<string>

rankBeforeIssue

string

rankAfterIssue

string

rankCustomFieldId

integer

Format: int64

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "issues": [
    "PR-1",
    "10001",
    "PR-3"
  ],
  "rankBeforeIssue": "PR-4",
  "rankCustomFieldId": 10521
}'

Responses

Empty response is returned if operation was successful.

Get projects

GET /rest/agile/1.0/board/{boardId}/project

Returns all projects that are associated with the board, for the given board ID. If the user does not have permission to view the board, no projects will be returned at all. Returned projects are ordered by the name.

A project is associated with a board if the board filter contains reference the project or there is an issue from the project that belongs to the board.

The board filter contains reference the project only if JQL query guarantees that returned issues will be returned from the project set defined in JQL. For instance the query project in (ABC, BCD) AND reporter = admin have reference to ABC and BCD projects but query project in (ABC, BCD) OR reporter = admin doesn't have reference to any project.

An issue belongs to the board if its status is mapped to the board's column. Epic issues do not belongs to the scrum boards.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains returned projects.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

The maximum number of projects to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.

Format: int32

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/project' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the board's projects, 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
{
  "maxResults": 10,
  "startAt": 0,
  "total": 2,
  "isLast": true,
  "values": [
    {
      "self": "http://your-domain.atlassian.net/rest/api/~ver~/project/EX",
      "id": "10000",
      "key": "EX",
      "name": "Example",
      "avatarUrls": {
        "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
        "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
        "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
        "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
      },
      "projectCategory": {
        "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
        "id": "10000",
        "name": "FIRST",
        "description": "First Project Category"
      },
      "simplified": false
    },
    {
      "self": "http://your-domain.atlassian.net/rest/api/~ver~/project/ABC",
      "id": "10001",
      "key": "ABC",
      "name": "Alphabetical",
      "avatarUrls": {
        "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10001",
        "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10001",
        "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10001",
        "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10001"
      },
      "projectCategory": {
        "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
        "id": "10000",
        "name": "FIRST",
        "description": "First Project Category"
      },
      "simplified": false
    }
  ]
}

Get projects full

GET /rest/agile/1.0/board/{boardId}/project/full

Returns all projects that are statically associated with the board, for the given board ID. Returned projects are ordered by the name.

A project is associated with a board if the board filter contains reference the project.

The board filter contains reference the project only if JQL query guarantees that returned issues will be returned from the project set defined in JQL. For instance the query project in (ABC, BCD) AND reporter = admin have reference to ABC and BCD projects but query project in (ABC, BCD) OR reporter = admin doesn't have reference to any project.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains returned projects.

Format: int64

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/project/full' \
  --user 'email@example.com:<api_token>'

Responses

Returns the board's projects, at the specified page of the results.

A schema has not been defined for this response code.

Get board property keys

GET /rest/agile/1.0/board/{boardId}/properties

Returns the keys of all properties for the board identified by the id. The user who retrieves the property keys is required to have permissions to view the board.

App scope requiredREAD

Request

Path parameters
boardId Required

string

the ID of the board from which property keys will be returned.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/properties' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returned if the board with given id exists.

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
8
{
  "keys": [
    {
      "self": "http://your-domain.atlassian.net/jira/rest/api/~ver~/issue/EX-2/properties/issue.support",
      "key": "issue.support"
    }
  ]
}

Get board property

GET /rest/agile/1.0/board/{boardId}/properties/{propertyKey}

Returns the value of the property with a given key from the board identified by the provided id. The user who retrieves the property is required to have permissions to view the board.

App scope requiredREAD

Request

Path parameters
boardId Required

string

the ID of the board from which the property will be returned.

propertyKey Required

string

the key of the property to return.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returned if the board exists and the property was found.

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
{
  "key": "issue.support",
  "value": {
    "stride.conversation.id": "b1bf38be-5e94-4b40-a3b8-9278735ee1e6",
    "support.time": "1m"
  }
}

Set board property

PUT /rest/agile/1.0/board/{boardId}/properties/{propertyKey}

Sets the value of the specified board's property. You can use this resource to store a custom data against the board identified by the id. The user who stores the data is required to have permissions to modify the board.

App scope requiredWRITE

Request

Path parameters
boardId Required

string

the ID of the board on which the property will be set.

propertyKey Required

string

the key of the board's property. The maximum length of the key is 255 bytes.

Example

1
2
3
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the board property is successfully updated.

A schema has not been defined for this response code.

Delete board property

DELETE /rest/agile/1.0/board/{boardId}/properties/{propertyKey}

Removes the property from the board identified by the id. Ths user removing the property is required to have permissions to modify the board.

App scope requiredDELETE

Request

Path parameters
boardId Required

string

the id of the board from which the property will be removed.

propertyKey Required

string

the key of the property to remove.

Example

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the board property was removed successfully.

Get all quick filters

GET /rest/agile/1.0/board/{boardId}/quickfilter

Returns all quick filters from a board, for a given board ID.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested quick filters.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

The maximum number of sprints to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.

Format: int32

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/quickfilter' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested quick filters, at the specified page of the results. Quick filters will be ordered first by position.

Content typeValue
application/json

object

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
{
  "maxResults": 2,
  "startAt": 1,
  "total": 5,
  "isLast": false,
  "values": [
    {
      "id": 1,
      "boardId": 1,
      "name": "Bugs",
      "jql": "issueType = bug",
      "description": "Issues of type bug",
      "position": 0
    },
    {
      "id": 2,
      "boardId": 1,
      "name": "Tasks",
      "jql": "issueType = task",
      "description": "Issues of type task",
      "position": 0
    }
  ]
}

Get quick filter

GET /rest/agile/1.0/board/{boardId}/quickfilter/{quickFilterId}

Returns the quick filter for a given quick filter ID. The quick filter will only be returned if the user can view the board that the quick filter belongs to.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

Format: int64
quickFilterId Required

integer

The ID of the requested quick filter.

Format: int64

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/quickfilter/{quickFilterId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested quick filter.

Content typeValue
application/json

object

Example response (application/json)

1
2
3
4
5
6
7
8
{
  "id": 1,
  "boardId": 1,
  "name": "Bugs",
  "jql": "issueType = bug",
  "description": "Issues of type bug",
  "position": 0
}

Get reports for board

GET /rest/agile/1.0/board/{boardId}/reports

App scope requiredREAD

Request

Path parameters
boardId Required

integer

Format: int64

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/reports' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

200 response

Content typeValue
application/json

object

Get all sprints

GET /rest/agile/1.0/board/{boardId}/sprint

Returns all sprints from a board, for a given board ID. This only includes sprints that the user has permission to view.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested sprints.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

The maximum number of sprints to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.

Format: int32
state

string

Filters results to sprints in specified states. Valid values: future, active, closed. You can define multiple states separated by commas, e.g. state=active,closed

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/sprint' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested sprints, at the specified page of the results. Sprints will be ordered first by state (i.e. closed, active, future) then by their position in the backlog.

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
{
  "maxResults": 2,
  "startAt": 1,
  "total": 5,
  "isLast": false,
  "values": [
    {
      "id": 37,
      "self": "http://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",
      "originBoardId": 5,
      "goal": "sprint 1 goal"
    },
    {
      "id": 72,
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/73",
      "state": "future",
      "name": "sprint 2",
      "goal": "sprint 2 goal"
    }
  ]
}

Get issues for sprint

GET /rest/agile/1.0/board/{boardId}/sprint/{sprintId}/issue

Get all issues you have access to that belong to the sprint from the board. Issue returned from this resource contains additional fields like: sprint, closedSprints, flagged and epic. Issues are returned ordered by rank. JQL order has higher priority than default rank.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains requested issues.

Format: int64
sprintId Required

integer

The ID of the sprint that contains requested issues.

Format: int64
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.

validateQuery

boolean

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

fields

Array<string>

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.net/rest/agile/1.0/board/{boardId}/sprint/{sprintId}/issue' \
  --user 'email@example.com:<api_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
{
  "expand": "names,schema",
  "startAt": 0,
  "maxResults": 50,
  "total": 1,
  "issues": [
    {
      "expand": "",
      "id": "10001",
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001",
      "key": "HSP-1",
      "fields": {
        "flagged": true,
        "sprint": {
          "id": 37,
          "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/13",
          "state": "future",
          "name": "sprint 2",
          "goal": "sprint 2 goal"
        },
        "closedSprints": [
          {
            "id": 37,
            "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/project/EX",
          "id": "10000",
          "key": "EX",
          "name": "Example",
          "avatarUrls": {
            "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
            "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
            "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
            "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
          },
          "projectCategory": {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
            "id": "10000",
            "name": "FIRST",
            "description": "First Project Category"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000",
            "id": "10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "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": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2018-09-14T03:03:07.240+0000",
            "updated": "2018-09-14T03:03:07.240+0000",
            "visibility": {
              "type": "role",
              "value": "Administrators"
            }
          }
        ],
        "epic": {
          "id": 37,
          "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "updateAuthor": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "comment": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-09-14T03:03:07.248+0000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-09-14T03:03:07.248+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
        }
      }
    }
  ]
}

Get all versions

GET /rest/agile/1.0/board/{boardId}/version

Returns all versions from a board, for a given board ID. This only includes versions that the user has permission to view. Note, if the user does not have permission to view the board, no versions will be returned at all. Returned versions are ordered by the name of the project from which they belong and then by sequence defined by user.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested versions.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

The maximum number of versions to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.

Format: int32
released

string

Filters results to versions that are either released or unreleased. Valid values: true, false.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/version' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested versions, 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
{
  "maxResults": 2,
  "startAt": 1,
  "total": 5,
  "isLast": false,
  "values": [
    {
      "self": "http://your-domain.atlassian.net/version/10000",
      "id": 10000,
      "projectId": 10000,
      "name": "Version 1",
      "description": "A first version",
      "archived": false,
      "released": true,
      "releaseDate": "2015-04-20T01:02:00.000+10:00"
    },
    {
      "self": "http://your-domain.atlassian.net/version/10010",
      "id": 10010,
      "projectId": 10000,
      "name": "Next Version",
      "description": "Minor Bugfix version",
      "archived": false,
      "released": false
    }
  ]
}

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.

App scope requiredREAD

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. 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.

validateQuery

boolean

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

fields

Array<string>

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.net/rest/agile/1.0/epic/none/issue' \
  --user 'email@example.com:<api_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
{
  "expand": "names,schema",
  "startAt": 0,
  "maxResults": 50,
  "total": 1,
  "issues": [
    {
      "expand": "",
      "id": "10001",
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001",
      "key": "HSP-1",
      "fields": {
        "flagged": true,
        "sprint": {
          "id": 37,
          "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/13",
          "state": "future",
          "name": "sprint 2",
          "goal": "sprint 2 goal"
        },
        "closedSprints": [
          {
            "id": 37,
            "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/project/EX",
          "id": "10000",
          "key": "EX",
          "name": "Example",
          "avatarUrls": {
            "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
            "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
            "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
            "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
          },
          "projectCategory": {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
            "id": "10000",
            "name": "FIRST",
            "description": "First Project Category"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000",
            "id": "10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "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": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2018-09-14T03:03:07.240+0000",
            "updated": "2018-09-14T03:03:07.240+0000",
            "visibility": {
              "type": "role",
              "value": "Administrators"
            }
          }
        ],
        "epic": {
          "id": 37,
          "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "updateAuthor": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "comment": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-09-14T03:03:07.248+0000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-09-14T03:03:07.248+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.

App scope requiredWRITE

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.net/rest/agile/1.0/epic/none/issue' \
  --user 'email@example.com:<api_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.

App scope requiredREAD

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.net/rest/agile/1.0/epic/{epicIdOrKey}' \
  --user 'email@example.com:<api_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": "http://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.

App scope requiredWRITE

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.net/rest/agile/1.0/epic/{epicIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "epic 2",
  "summary": "epic 2 summary",
  "color": {
    "key": "color_6"
  },
  "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": "http://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.

App scope requiredREAD

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.

validateQuery

boolean

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

fields

Array<string>

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.net/rest/agile/1.0/epic/{epicIdOrKey}/issue' \
  --user 'email@example.com:<api_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
{
  "expand": "names,schema",
  "startAt": 0,
  "maxResults": 50,
  "total": 1,
  "issues": [
    {
      "expand": "",
      "id": "10001",
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001",
      "key": "HSP-1",
      "fields": {
        "flagged": true,
        "sprint": {
          "id": 37,
          "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/13",
          "state": "future",
          "name": "sprint 2",
          "goal": "sprint 2 goal"
        },
        "closedSprints": [
          {
            "id": 37,
            "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/project/EX",
          "id": "10000",
          "key": "EX",
          "name": "Example",
          "avatarUrls": {
            "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
            "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
            "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
            "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
          },
          "projectCategory": {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
            "id": "10000",
            "name": "FIRST",
            "description": "First Project Category"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000",
            "id": "10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "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": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2018-09-14T03:03:07.240+0000",
            "updated": "2018-09-14T03:03:07.240+0000",
            "visibility": {
              "type": "role",
              "value": "Administrators"
            }
          }
        ],
        "epic": {
          "id": 37,
          "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000",
            "author": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "updateAuthor": {
              "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
              "name": "mia",
              "displayName": "Mia Krystof",
              "active": false
            },
            "comment": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-09-14T03:03:07.248+0000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-09-14T03:03:07.248+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.

App scope requiredWRITE

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.net/rest/agile/1.0/epic/{epicIdOrKey}/issue' \
  --user 'email@example.com:<api_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.

App scope requiredWRITE

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.net/rest/agile/1.0/epic/{epicIdOrKey}/rank' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "rankBeforeEpic": "10000",
  "rankCustomFieldId": 10521
}'

Responses

Empty response is returned if operation was successful.

Issue

Apis related to issues

Rank issues

PUT /rest/agile/1.0/issue/rank

Moves (ranks) issues before or after a given issue. At most 50 issues may be ranked at once.

This operation may fail for some issues, although this will be rare. In that case the 207 status code is returned for the whole response and detailed information regarding each issue is available in the response body.

If rankCustomFieldId is not defined, the default rank field will be used.

App scope requiredWRITE

Request

Body parameters
issues

Array<string>

rankBeforeIssue

string

rankAfterIssue

string

rankCustomFieldId

integer

Format: int64

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/issue/rank' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "issues": [
    "PR-1",
    "10001",
    "PR-3"
  ],
  "rankBeforeIssue": "PR-4",
  "rankCustomFieldId": 10521
}'

Responses

Empty response is returned if operation was successful.

Get issue

GET /rest/agile/1.0/issue/{issueIdOrKey}

Returns a single issue, for a given issue ID or issue key. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic.

App scope requiredREAD

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the requested issue.

Query parameters
fields

Array<string>

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.

updateHistory

boolean

A boolean indicating whether the issue retrieved by this method should be added to the current user's issue history

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested issue.

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
{
  "expand": "",
  "id": "10001",
  "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001",
  "key": "HSP-1",
  "fields": {
    "flagged": true,
    "sprint": {
      "id": 37,
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/13",
      "state": "future",
      "name": "sprint 2",
      "goal": "sprint 2 goal"
    },
    "closedSprints": [
      {
        "id": 37,
        "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/project/EX",
      "id": "10000",
      "key": "EX",
      "name": "Example",
      "avatarUrls": {
        "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
        "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
        "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
        "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
      },
      "projectCategory": {
        "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
        "id": "10000",
        "name": "FIRST",
        "description": "First Project Category"
      },
      "simplified": false
    },
    "comment": [
      {
        "self": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000",
        "id": "10000",
        "author": {
          "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
          "name": "mia",
          "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": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
          "name": "mia",
          "displayName": "Mia Krystof",
          "active": false
        },
        "created": "2018-09-14T03:03:07.240+0000",
        "updated": "2018-09-14T03:03:07.240+0000",
        "visibility": {
          "type": "role",
          "value": "Administrators"
        }
      }
    ],
    "epic": {
      "id": 37,
      "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000",
        "author": {
          "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
          "name": "mia",
          "displayName": "Mia Krystof",
          "active": false
        },
        "updateAuthor": {
          "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
          "name": "mia",
          "displayName": "Mia Krystof",
          "active": false
        },
        "comment": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "I did some work here."
                }
              ]
            }
          ]
        },
        "updated": "2018-09-14T03:03:07.248+0000",
        "visibility": {
          "type": "group",
          "value": "jira-developers"
        },
        "started": "2018-09-14T03:03:07.248+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
    }
  }
}

Get issue estimation for board

GET /rest/agile/1.0/issue/{issueIdOrKey}/estimation

Returns the estimation of the issue and a fieldId of the field that is used for it. boardId param is required. This param determines which field will be updated on a issue.

Original time internally stores and returns the estimation as a number of seconds.

The field used for estimation on the given board can be obtained from board configuration resource. More information about the field are returned by edit meta resource or field resource.

App scope requiredREAD

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the requested issue.

Query parameters
boardId

integer

The ID of the board required to determine which field is used for estimation.

Format: int64

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/issue/{issueIdOrKey}/estimation' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the estimation of the issue and a fieldId of the field that is used for it.

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
{
  "fieldId": "customfield_12532",
  "value": "8.0"
}

Estimate issue for board

PUT /rest/agile/1.0/issue/{issueIdOrKey}/estimation

Updates the estimation of the issue. boardId param is required. This param determines which field will be updated on a issue.

Note that this resource changes the estimation field of the issue regardless of appearance the field on the screen.

Original time tracking estimation field accepts estimation in formats like "1w", "2d", "3h", "20m" or number which represent number of minutes. However, internally the field stores and returns the estimation as a number of seconds.

The field used for estimation on the given board can be obtained from board configuration resource. More information about the field are returned by edit meta resource or field resource.

App scope requiredWRITE

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the requested issue.

Query parameters
boardId

integer

The ID of the board required to determine which field is used for estimation.

Format: int64
Body parameters
value

string

Example

1
2
3
4
5
6
7
8
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/issue/{issueIdOrKey}/estimation' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "value": "8.0"
}'

Responses

Returns the estimation of the issue and a fieldId of the field that is used for it.

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
{
  "fieldId": "customfield_12532",
  "value": "8.0"
}

Sprint

Apis related to sprints

Create sprint

POST /rest/agile/1.0/sprint

Creates a future sprint. Sprint name and origin board id are required. Start date, end date, and goal are optional. Note, the sprint name is trimmed.

App scope requiredWRITE

Request

Body parameters
name

string

startDate

string

endDate

string

originBoardId

integer

Format: int64
goal

string

Example

1
2
3
4
5
6
7
8
9
10
11
12
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "sprint 1",
  "startDate": "2015-04-11T15:22:00.000+10:00",
  "endDate": "2015-04-20T01:22:00.000+10:00",
  "originBoardId": 5,
  "goal": "sprint 1 goal"
}'

Responses

Created sprint

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
{
  "id": 37,
  "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/23",
  "state": "future",
  "name": "sprint 1",
  "startDate": "2015-04-11T15:22:00.000+10:00",
  "endDate": "2015-04-20T01:22:00.000+10:00",
  "originBoardId": 5,
  "goal": "sprint 1 goal"
}

Get sprint

GET /rest/agile/1.0/sprint/{sprintId}

Returns the sprint for a given sprint ID. The sprint will only be returned if the user can view the board that the sprint was created on, or view at least one of the issues in the sprint.

App scope requiredREAD

Request

Path parameters
sprintId Required

integer

The ID of the requested sprint.

Format: int64

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested sprint.

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
{
  "id": 37,
  "self": "http://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",
  "originBoardId": 5,
  "goal": "sprint 1 goal"
}

Update sprint

PUT /rest/agile/1.0/sprint/{sprintId}

Performs a full update of a sprint. A full update means that the result will be exactly the same as the request body. Any fields not present in the request JSON will be set to null.

Notes:

  • Sprints that are in a closed state cannot be updated.
  • A sprint can be started by updating the state to 'active'. This requires the sprint to be in the 'future' state and have a startDate and endDate set.
  • A sprint can be completed by updating the state to 'closed'. This action requires the sprint to be in the 'active' state. This sets the completeDate to the time of the request.
  • Other changes to state are not allowed.
  • The completeDate field cannot be updated manually.

App scope requiredWRITE

Request

Path parameters
sprintId Required

integer

the ID of the sprint to update.

Format: int64
Body parameters
id

integer

Format: int64
self

string

Format: uri
state

string

name

string

startDate

string

endDate

string

completeDate

string

originBoardId

integer

Format: int64
goal

string

Example

1
2
3
4
5
6
7
8
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "new name"
}'

Responses

Updated sprint

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
{
  "id": 37,
  "self": "http://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",
  "originBoardId": 5,
  "goal": "sprint 1 goal"
}

Partially update sprint

POST /rest/agile/1.0/sprint/{sprintId}

Performs a partial update of a sprint. A partial update means that fields not present in the request JSON will not be updated.

Notes:

  • Sprints that are in a closed state cannot be updated.
  • A sprint can be started by updating the state to 'active'. This requires the sprint to be in the 'future' state and have a startDate and endDate set.
  • A sprint can be completed by updating the state to 'closed'. This action requires the sprint to be in the 'active' state. This sets the completeDate to the time of the request.
  • Other changes to state are not allowed.
  • The completeDate field cannot be updated manually.

App scope requiredWRITE

Request

Path parameters
sprintId Required

integer

The ID of the sprint to update.

Format: int64
Body parameters
id

integer

Format: int64
self

string

Format: uri
state

string

name

string

startDate

string

endDate

string

completeDate

string

originBoardId

integer

Format: int64
goal

string

Example

1
2
3
4
5
6
7
8
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "new name"
}'

Responses

Updated sprint

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
{
  "id": 37,
  "self": "http://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",
  "originBoardId": 5,
  "goal": "sprint 1 goal"
}

Delete sprint

DELETE /rest/agile/1.0/sprint/{sprintId}

Deletes a sprint. Once a sprint is deleted, all open issues in the sprint will be moved to the backlog.

App scope requiredDELETE

Request

Path parameters
sprintId Required

integer

The ID of the sprint to delete.

Format: int64

Example

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the sprint was deleted successfully

Get issues for sprint

GET /rest/agile/1.0/sprint/{sprintId}/issue

Returns all issues in a sprint, for a given sprint ID. This only includes issues that the user has permission to view. By default, the returned issues are ordered by rank.

App scope requiredREAD

Request

Path parameters
sprintId Required

integer

The ID of the sprint that contains the requested issues.

Format: int64
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.

validateQuery

boolean

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

fields

Array<string>

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.net/rest/agile/1.0/sprint/{sprintId}/issue' \
  --user 'email@example.com:<api_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
{
  "expand": "",
  "id": "10001",
  "self": "http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001",
  "key": "HSP-1",
  "fields": {
    "flagged": true,
    "sprint": {
      "id": 37,
      "self": "http://your-domain.atlassian.net/rest/agile/1.0/sprint/13",
      "state": "future",
      "name": "sprint 2",
      "goal": "sprint 2 goal"
    },
    "closedSprints": [
      {
        "id": 37,
        "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/project/EX",
      "id": "10000",
      "key": "EX",
      "name": "Example",
      "avatarUrls": {
        "48x48": "http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
        "24x24": "http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
        "16x16": "http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
        "32x32": "http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
      },
      "projectCategory": {
        "self": "http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000",
        "id": "10000",
        "name": "FIRST",
        "description": "First Project Category"
      },
      "simplified": false
    },
    "comment": [
      {
        "self": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000",
        "id": "10000",
        "author": {
          "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
          "name": "mia",
          "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": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
          "name": "mia",
          "displayName": "Mia Krystof",
          "active": false
        },
        "created": "2018-09-14T03:03:07.240+0000",
        "updated": "2018-09-14T03:03:07.240+0000",
        "visibility": {
          "type": "role",
          "value": "Administrators"
        }
      }
    ],
    "epic": {
      "id": 37,
      "self": "http://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": "http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000",
        "author": {
          "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
          "name": "mia",
          "displayName": "Mia Krystof",
          "active": false
        },
        "updateAuthor": {
          "self": "http://your-domain.atlassian.net/rest/api/~ver~/user?accoundId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
          "name": "mia",
          "displayName": "Mia Krystof",
          "active": false
        },
        "comment": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "I did some work here."
                }
              ]
            }
          ]
        },
        "updated": "2018-09-14T03:03:07.248+0000",
        "visibility": {
          "type": "group",
          "value": "jira-developers"
        },
        "started": "2018-09-14T03:03:07.248+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 sprint and rank

POST /rest/agile/1.0/sprint/{sprintId}/issue

Moves issues to a sprint, for a given sprint ID. Issues can only be moved to open or active sprints. The maximum number of issues that can be moved in one operation is 50.

App scope requiredWRITE

Request

Path parameters
sprintId Required

integer

The ID of the sprint that you want to assign issues to.

Format: int64
Body parameters
issues

Array<string>

rankBeforeIssue

string

rankAfterIssue

string

rankCustomFieldId

integer

Format: int64

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "issues": [
    "PR-1",
    "10001",
    "PR-3"
  ],
  "rankBeforeIssue": "PR-4",
  "rankCustomFieldId": 10521
}'

Responses

Empty response is returned if operation was successful.

Get properties keys

GET /rest/agile/1.0/sprint/{sprintId}/properties

Returns the keys of all properties for the sprint identified by the id. The user who retrieves the property keys is required to have permissions to view the sprint.

App scope requiredREAD

Request

Path parameters
sprintId Required

string

the ID of the sprint from which property keys will be returned.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/properties' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returned if the sprint with given id exists.

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
8
{
  "keys": [
    {
      "self": "http://your-domain.atlassian.net/jira/rest/api/~ver~/issue/EX-2/properties/issue.support",
      "key": "issue.support"
    }
  ]
}

Get property

GET /rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}

Returns the value of the property with a given key from the sprint identified by the provided id. The user who retrieves the property is required to have permissions to view the sprint.

App scope requiredREAD

Request

Path parameters
sprintId Required

string

the ID of the sprint from which the property will be returned.

propertyKey Required

string

the key of the property to return.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returned if the sprint exists and the property was found.

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
{
  "key": "issue.support",
  "value": {
    "stride.conversation.id": "b1bf38be-5e94-4b40-a3b8-9278735ee1e6",
    "support.time": "1m"
  }
}

Set property

PUT /rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}

Sets the value of the specified sprint's property. You can use this resource to store a custom data against the sprint identified by the id. The user who stores the data is required to have permissions to modify the sprint.

App scope requiredWRITE

Request

Path parameters
sprintId Required

string

the ID of the sprint on which the property will be set.

propertyKey Required

string

the key of the sprint's property. The maximum length of the key is 255 bytes.

Example

1
2
3
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the sprint property is successfully updated.

A schema has not been defined for this response code.

Delete property

DELETE /rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}

Removes the property from the sprint identified by the id. Ths user removing the property is required to have permissions to modify the sprint.

App scope requiredDELETE

Request

Path parameters
sprintId Required

string

the ID of the sprint from which the property will be removed.

propertyKey Required

string

the key of the property to remove.

Example

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the sprint property was removed successfully.

Swap sprint

POST /rest/agile/1.0/sprint/{sprintId}/swap

Swap the position of the sprint with the second sprint.

App scope requiredWRITE

Request

Path parameters
sprintId Required

integer

The ID of the sprint to swap.

Format: int64
Body parameters
sprintToSwapWith

integer

Format: int64

Example

1
2
3
4
5
6
7
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/swap' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sprintToSwapWith": 3
}'

Responses

Returned if the sprint swap was performed successfully

Development Information

Apis related to integrating development information (commits, branches and pull requests) with Jira. These apis are only available to Atlassian Connect apps. To use these apis you must have the Development Tool module (see https://developer.atlassian.com/cloud/jira/software/modules/development-tool/) in your app's descriptor

Store development information

POST /rest/devinfo/0.10/bulk

Stores development information provided in the request to make it available when viewing issues in JIRA. Existing repository and entity data for the same ID will be replaced if the updateSequenceId of existing data is less than the incoming data. Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are available within a short period of time, but may take some time during peak load and/or maintenance times.

App scope requiredWRITE

Request

Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Body parameters

Request object for development information push operations, entities are grouped by repository

repositories Required

Array<object>

List of repositories containing development information. Must not contain duplicates. Maximum number of entities across all repositories is 1000

Max items: 100
preventTransitions

boolean

Flag to prevent automatic issue transitions and smart commits being fired, default is false

properties

object

Arbitrary properties to tag the submitted repositories with. These properties can be used for delete operations to e.g. clean up all development information associated with an account in the event that the account is removed from the provider system. Note that these properties will never be returned with repository or entity data. They are not intended for use as metadata to associate with a repository. Maximum length of each key or value is 255 characters. Maximum allowed number of properties key/value pairs is 5. Properties keys cannot start with '_' character. Properties keys cannot contain ':' character.

Example

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
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/bulk' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "repositories": [
    {
      "name": "atlassian-connect-jira-example",
      "description": "The repository which stores code of the Atlassian Connect Add-on Devinfo application.",
      "forkOf": "56c7c750-cee2-48e2-b920-d7706dfd11f7",
      "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example",
      "commits": [
        {
          "id": "c6c7c750-cee2-48e2-b920-d7706dfd11f9",
          "issueKeys": [
            "<string>"
          ],
          "updateSequenceId": 1523494301248,
          "hash": "a7727ee6350c33cdf90826dc21abaa26a5704370",
          "flags": [
            "MERGE_COMMIT"
          ],
          "message": "README.md edited online with Bitbucket",
          "author": {
            "name": "Jane Doe",
            "email": "jane_doe@atlassian.com",
            "username": "jdoe",
            "url": "https://atlassian.com/account/jane_doe",
            "avatar": "https://atlassian.com/account/jane_doe/avatar/32"
          },
          "fileCount": 1,
          "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/commits/a7727ee6350c33cdf90826dc21abaa26a5704370",
          "files": [
            {
              "path": "/home/user/src/atlassian-connect-jira-example/README.md",
              "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/src/a7727ee6350c33cdf90826dc21abaa26a5704370/README.md",
              "changeType": "MODIFIED",
              "linesAdded": 0,
              "linesRemoved": 1
            }
          ],
          "authorTimestamp": "2016-10-31T23:27:25+00:00",
          "displayId": "a7727ee"
        }
      ],
      "branches": [
        {
          "id": "c6c7c750-cee2-48e2-b920-d7706dfd11f9",
          "issueKeys": [
            "<string>"
          ],
          "updateSequenceId": 1523494301248,
          "name": "master",
          "lastCommit": {
            "id": "c6c7c750-cee2-48e2-b920-d7706dfd11f9",
            "issueKeys": [
              "<string>"
            ],
            "updateSequenceId": 1523494301248,
            "hash": "a7727ee6350c33cdf90826dc21abaa26a5704370",
            "flags": [
              "MERGE_COMMIT"
            ],
            "message": "README.md edited online with Bitbucket",
            "author": {
              "name": "Jane Doe",
              "email": "jane_doe@atlassian.com",
              "username": "jdoe",
              "url": "https://atlassian.com/account/jane_doe",
              "avatar": "https://atlassian.com/account/jane_doe/avatar/32"
            },
            "fileCount": 1,
            "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/commits/a7727ee6350c33cdf90826dc21abaa26a5704370",
            "files": [
              {
                "path": "/home/user/src/atlassian-connect-jira-example/README.md",
                "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/src/a7727ee6350c33cdf90826dc21abaa26a5704370/README.md",
                "changeType": "MODIFIED",
                "linesAdded": 0,
                "linesRemoved": 1
              }
            ],
            "authorTimestamp": "2016-10-31T23:27:25+00:00",
            "displayId": "a7727ee"
          },
          "createPullRequestUrl": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/pull-requests/new",
          "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/branch/master"
        }
      ],
      "pullRequests": [
        {
          "id": "c6c7c750-cee2-48e2-b920-d7706dfd11f9",
          "issueKeys": [
            "<string>"
          ],
          "updateSequenceId": 1523494301248,
          "status": "OPEN",
          "title": "Pull request 2, fixing all the issues caused by pull request #1",
          "author": {
            "name": "Jane Doe",
            "email": "jane_doe@atlassian.com",
            "username": "jdoe",
            "url": "https://atlassian.com/account/jane_doe",
            "avatar": "https://atlassian.com/account/jane_doe/avatar/32"
          },
          "commentCount": 42,
          "sourceBranch": "ISSUE-1-feature-branch",
          "sourceBranchUrl": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/branch/ISSUE-1-feature-branch",
          "lastUpdate": "2016-10-31T23:27:25+00:00",
          "destinationBranch": "master",
          "reviewers": [
            {
              "name": "Jane Doe",
              "approvalStatus": "APPROVED",
              "url": "https://atlassian.com/account/jane_doe",
              "avatar": "https://atlassian.com/account/jane_doe/avatar/32"
            }
          ],
          "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/pull-requests/2",
          "displayId": "Pull request 2"
        }
      ],
      "avatar": "http://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/avatar/32",
      "avatarDescription": "Avatar description",
      "id": "c6c7c750-cee2-48e2-b920-d7706dfd11f9",
      "updateSequenceId": 1523494301248
    }
  ],
  "preventTransitions": true,
  "properties": {}
}'

Responses

Submission accepted. Each submitted repository and entity that is of a valid format will be eventually available in Jira.

Content typeValue
application/json

object

Get repository

GET /rest/devinfo/0.10/repository/{repositoryId}

For the specified repository ID, retrieves the repository and the most recent 400 development information entities. The result will be what is currently stored, ignoring any pending updates or deletes.

App scope requiredREAD

Request

Path parameters
repositoryId Required

string

The ID of repository to fetch

Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/repository/{repositoryId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

The repository data currently stored for the given ID.

Content typeValue
application/json

object

Delete repository

DELETE /rest/devinfo/0.10/repository/{repositoryId}

Deletes the repository data stored by the given ID and all related development information entities. Deletion is performed asynchronously.

App scope requiredDELETE

Request

Path parameters
repositoryId Required

string

The ID of repository to delete

Query parameters
_updateSequenceId

integer

An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together.

Format: int64
Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Example

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/repository/{repositoryId}' \
  --user 'email@example.com:<api_token>'

Responses

Delete request has been accepted. Data will eventually be removed from Jira if it exists.

A schema has not been defined for this response code.

Delete development information by properties

DELETE /rest/devinfo/0.10/bulkByProperties

Deletes development information entities which have all the provided properties. Entities will be deleted that match ALL of the properties (i.e. treated as an AND). For example if request is DELETE bulk?accountId=123&projectId=ABC entities which have properties accountId=123 and projectId=ABC will be deleted. Special property '_updateSequenceId' can be used to delete all entities with updateSequenceId less or equal than the value specified. In addition to the optional '_updateSequenceId', one or more query params must be supplied to specify properties to delete by. Deletion is performed asynchronously: specified entities will eventually be removed from Jira.

App scope requiredDELETE

Request

Query parameters
_updateSequenceId

integer

An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together.

Format: int64
Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Example

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/bulkByProperties' \
  --user 'email@example.com:<api_token>'

Responses

Delete accepted. Data will eventually be removed from Jira.

A schema has not been defined for this response code.

Check if data exists for the supplied properties

GET /rest/devinfo/0.10/existsByProperties

Checks if development information which have all the provided properties exists. For example, if request is GET existsByProperties?accountId=123&projectId=ABC then result will be positive only if there is at least one entity or repository with both properties accountId=123 and projectId=ABC. Special property '_updateSequenceId' can be used to filter all entities with updateSequenceId less or equal than the value specified. In addition to the optional '_updateSequenceId', one or more query params must be supplied to specify properties to search by.

App scope requiredREAD

Request

Query parameters
_updateSequenceId

integer

An optional property. Filters out entities and repositories which have updateSequenceId greater than specified.

Format: int64
Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/existsByProperties' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns whether data exists for the specified properties.

Content typeValue
application/json

object

Delete development information entity

DELETE /rest/devinfo/0.10/repository/{repositoryId}/{entityType}/{entityId}

Deletes particular development information entity. Deletion is performed asynchronously.

App scope requiredDELETE

Request

Path parameters
repositoryId Required

string

entityType Required

string

Valid values: commit, branch, pull_request

entityId Required

string

Query parameters
_updateSequenceId

integer

An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together.

Format: int64
Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Example

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/repository/{repositoryId}/{entityType}/{entityId}' \
  --user 'email@example.com:<api_token>'

Responses

Delete request has been accepted. Data will eventually be removed from Jira if it exists.

A schema has not been defined for this response code.

Feature Flags

Apis related to integrating Feature Flags with Jira Software. These apis are only available to Atlassian Connect apps. To use these apis you must have the Feature Flag module (see https://developer.atlassian.com/cloud/jira/software/modules/feature-flag/) in your app's descriptor

Submit Feature Flag data

POST /rest/featureflags/0.1/bulk

Update / insert Feature Flag data. Feature Flags are identified by their ID, and existing Feature Flag data for the same ID will be replaced if it exists and the updateSequenceId of existing data is less than the incoming data. Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are available within a short period of time, but may take some time during peak load and/or maintenance times. The getFeatureFlagById operation can be used to confirm that data has been stored successfully (if needed). In the case of multiple Feature Flags being submitted in one request, each is validated individually prior to submission. Details of which Feature Flags failed submission (if any) are available in the response object. Only apps that define the Feature Flags module can access this resource. This resource requires the 'WRITE' scope.

App scope requiredWRITE

Request

Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define Feature Flags module it will be rejected with a 403.

See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Pattern: JWT \S+
Body parameters

The payload used to submit (update / insert) Feature Flag data.

properties

object

Arbitrary properties to tag the submitted Feature Flags with. These properties can be used for delete operations to e.g. clean up all Feature Flags associated with an account in the event that the account is removed from the Provider system. Note that these properties will never be returned with Feature Flag data. They are not intended for use as metadata to associate with a Feature Flag. Internally they are stored as a hash so that personal information etc. is never stored within Jira.

flags Required

Array<object>

A list of Feature Flags to submit to Jira. Each Feature Flag may be associated with 1 or more Jira issue keys, and will be associated with any properties included in this request.

Min items: 1

Example

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
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/featureflags/0.1/bulk' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "properties": {
    "accountId": "account-234",
    "projectId": "project-123"
  },
  "flags": [
    {
      "schemaVersion": "1.0",
      "id": "111-222-333",
      "key": "my-awesome-feature",
      "updateSequenceId": 1523494301448,
      "displayName": "Enable awesome feature",
      "issueKeys": [
        "ISSUE-123"
      ],
      "summary": {
        "url": "https://example.com/project/feature-123/summary",
        "status": {
          "enabled": true,
          "defaultValue": "Disabled",
          "rollout": {
            "percentage": 80
          }
        },
        "lastUpdated": "2018-01-20T23:27:25+00:00"
      },
      "details": [
        {
          "url": "https://example.com/project/feature-123/production",
          "lastUpdated": "2018-01-20T23:27:25+00:00",
          "environment": {
            "name": "prod-us-west",
            "type": "production"
          },
          "status": {
            "enabled": true,
            "defaultValue": "Disabled",
            "rollout": {
              "percentage": 80
            }
          }
        }
      ]
    }
  ]
}'

Responses

Submission accepted. Each submitted Feature Flag that is of a valid format will be eventually available in Jira. Details of which Feature Flags were submitted and which failed submission (due to data format problems etc.) are available in the response object.

Content typeValue
application/json

object

Delete Feature Flags by Property

DELETE /rest/featureflags/0.1/bulkByProperties

Bulk delete all Feature Flags that match the given request. In addition to the optional updateSequenceId, one or more query params must be supplied to specify Properties to delete by. If more than one Property is provided, data will be deleted that matches ALL of the Properties (e.g. treated as an AND). See the documentation for the submitFeatureFlags operation for more details. e.g. DELETE /bulkByProperties?accountId=account-123&createdBy=user-456 Deletion is performed asynchronously. The getFeatureFlagById operation can be used to confirm that data has been deleted successfully (if needed). Only apps that define the Feature Flags module can access this resource. This resource requires the 'DELETE' scope.

App scope requiredDELETE

Request

Query parameters
_updateSequenceId

integer

An optional updateSequenceId to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used help ensure submit/delete requests are applied correctly if issued close together. If not provided, all stored data that matches the request will be deleted.

Format: int64
Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define Feature Flags module it will be rejected with a 403.

See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Pattern: JWT \S+

Example

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/featureflags/0.1/bulkByProperties' \
  --user 'email@example.com:<api_token>'

Responses

Delete accepted. Data will eventually be removed from Jira.

A schema has not been defined for this response code.

Get a Feature Flag by ID

GET /rest/featureflags/0.1/flag/{featureFlagId}

Retrieve the currently stored Feature Flag data for the given ID. The result will be what is currently stored, ignoring any pending updates or deletes. Only apps that define the Feature Flags module can access this resource. This resource requires the 'READ' scope.

App scope requiredREAD

Request

Path parameters
featureFlagId Required

string

The ID of the Feature Flag to fetch.

Max length: 255
Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define Feature Flags module it will be rejected with a 403.

See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Pattern: JWT \S+

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/featureflags/0.1/flag/{featureFlagId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

The Feature Flag data currently stored for the given ID.

Content typeValue
application/json

object

Delete a Feature Flag by ID

DELETE /rest/featureflags/0.1/flag/{featureFlagId}

Delete the Feature Flag data currently stored for the given ID. Deletion is performed asynchronously. The getFeatureFlagById operation can be used to confirm that data has been deleted successfully (if needed). Only apps that define the Feature Flags module can access this resource. This resource requires the 'DELETE' scope.

App scope requiredDELETE

Request

Path parameters
featureFlagId Required

string

The ID of the Feature Flag to delete.

Max length: 255
Query parameters
_updateSequenceId

integer

An optional updateSequenceId to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used help ensure submit/delete requests are applied correctly if issued close together.

Format: int64
Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define Feature Flags module it will be rejected with a 403.

See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Pattern: JWT \S+

Example

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/featureflags/0.1/flag/{featureFlagId}' \
  --user 'email@example.com:<api_token>'

Responses

Delete has been accepted. Data will eventually be removed from Jira if it exists.

A schema has not been defined for this response code.