JIRA Software Cloud REST API reference

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.

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:

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:

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 metada, like this:

Request

http://host:port/context/rest/api-name/api-version/resource-name?start=0&limit=10

Response

{
    "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: nocheck' 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 resources 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.

Due to 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

"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

"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

"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

"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

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

Resources

agile/1.0/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.

Request

Example

{"issues":["PR-1","10001","PR-3"]}

Responses

Status 204
Empty response is returned if operation was successful.
Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if user does not a have valid license or does not have permission to assign issues.
Status 404
Returned if sprint does not exist or the user cannot view it.

agile/1.0/board

Get all boards`GET /rest/agile/1.0/board`

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

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned boards. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	The maximum number of boards to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.
`type`	string	Filters results to boards of the specified type. Valid values: scrum, kanban.
`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.

Responses

Status 200 - application/json

Example

{"maxResults":2,"startAt":1,"total":5,"isLast":false,"values":[{"id":84,"self":"http://www.example.com/jira/rest/agile/1.0/board/84","name":"scrum board","type":"scrum"},{"id":92,"self":"http://www.example.com/jira/rest/agile/1.0/board/92","name":"kanban board","type":"kanban"}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not have valid license.

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

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.

Request

Example

{"name":"scrum board","type":"scrum","filterId":10040}

Responses

Status 201 - application/json

Example

{"id":84,"self":"http://www.example.com/jira/rest/agile/1.0/board/84","name":"scrum board","type":"scrum"}

Returns the created board.

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.

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.

Responses

Status 200 - application/json

Example

{"id":84,"self":"http://www.example.com/jira/rest/agile/1.0/board/84","name":"scrum board","type":"scrum"}

Returns the requested board.

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the board does not exist or the user does not have permission to view it.

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

Deletes the board.

Responses

Status 204
Returned if the board has been successfully removed.
Status 403
Returned if the user does not a have valid license, or when the user does not have the permission to delete the board. The user has to be a JIRA Administrator or a board administrator to remove the board.
Status 404
Returned if a board with the given id does not exist or the user does not have the permission to view the board.

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	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.
`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`	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.

Responses

Status 200 - application/json

Example

{"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2","goal":"sprint 2 goal"},"closedSprints":[{"id":37,"self":"http://www.example.com/jira/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://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"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://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2017-03-08T23:31:08.127+0000","updated":"2017-03-08T23:31:08.241+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2017-03-08T23:31:08.245+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T23:31:08.245+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}}}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the board does not exist or the user does not have permission to view it.

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

Responses

Status 200 - application/json

Example

{"id":10000,"name":"Board","self":"http://www.example.com/jira/rest/agile/1.0/board/84/config","filter":{"id":"1001","self":"http://www.example.com/jira/filter/1001"},"columnConfig":{"columns":[{"name":"To Do","statuses":[{"id":"1","self":"http://www.example.com/jira/status/1"},{"id":"4","self":"http://www.example.com/jira/status/4"}]},{"name":"In progress","statuses":[{"id":"3","self":"http://www.example.com/jira/status/3"}],"min":2,"max":4},{"name":"Done","statuses":[{"id":"5","self":"http://www.example.com/jira/status/5"}]}],"constraintType":"issueCount"},"estimation":{"type":"field","field":{"fieldId":"customfield_10002","displayName":"Story Points"}},"ranking":{"rankCustomFieldId":10020}}

Returns the configuration of the board for given boardId.

Status 401
Returned if the user is not logged in.
Status 403
Returned if user does not a have valid license.
Status 404
Returned if board does not exist or the user cannot view it.

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	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.
`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`	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.

Responses

Status 200 - application/json

Example

{"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2","goal":"sprint 2 goal"},"closedSprints":[{"id":37,"self":"http://www.example.com/jira/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://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"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://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2017-03-08T23:31:08.127+0000","updated":"2017-03-08T23:31:08.241+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2017-03-08T23:31:08.245+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T23:31:08.245+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}}}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the board does not exist or the user does not have permission to view it.

agile/1.0/board/{boardId}/epic

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned epics. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	The maximum number of epics to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.
`done`	string	Filters results to epics that are either done or not done. Valid values: true, false.

Responses

Status 200 - application/json

Example

{"maxResults":2,"startAt":1,"total":5,"isLast":false,"values":[{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/13","name":"epic 2","summary":"epic 2 summary","color":{"key":"color_2"},"done":false}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not have valid license.
Status 404
Returned if board does not exist or the user does not have permission to view it.

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	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.
`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`	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.

Responses

Status 200 - application/json

Example

{"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2","goal":"sprint 2 goal"},"closedSprints":[{"id":37,"self":"http://www.example.com/jira/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://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"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://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2017-03-08T23:31:08.127+0000","updated":"2017-03-08T23:31:08.241+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2017-03-08T23:31:08.245+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T23:31:08.245+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}}}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the board does not exist or the user does not have permission to view it.

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	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.
`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`	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.

Responses

Status 200 - application/json

Example

{"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2","goal":"sprint 2 goal"},"closedSprints":[{"id":37,"self":"http://www.example.com/jira/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://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"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://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2017-03-08T23:31:08.127+0000","updated":"2017-03-08T23:31:08.241+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2017-03-08T23:31:08.245+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T23:31:08.245+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}}}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the board does not exist or the user does not have permission to view it.

agile/1.0/board/{boardId}/project

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned projects. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	The maximum number of projects to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.

Responses

Status 200 - application/json

Example

{"maxResults":10,"startAt":0,"total":2,"isLast":true,"values":[{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},{"self":"http://www.example.com/jira/rest/api/2/project/ABC","id":"10001","key":"ABC","name":"Alphabetical","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10001","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10001","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10001","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10001"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if board does not exist or the user does not have permission to access it.

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.

Responses

Status 200 - application/json
Returns the board's projects, at the specified page of the results.
Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if board does not exist or the user does not have permission to access it.

agile/1.0/board/{boardId}/properties

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

Responses

Status 200 - application/json

Example

{"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}

Returned if the board with given id exists.

Status 400
Returned if the boardId is invalid (negative or not a number).
Status 401
Returned if the calling user is not authenticated.
Status 404
Returned if the board with given id does not exist or if the property with given key is not found or the user doesn't have permissions to see it.

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

Responses

Status 204
Returned if the board property was removed successfully.
Status 400
Returned if the boardId is invalid (negative or not a number).
Status 401
Returned if the calling user is not authenticated.
Status 404
Returned if the board with given id does not exist or if the property with given key is not found or the user doesn't have permissions to see it.

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

Responses

Status 200
Returned if the board property is successfully updated.
Status 201
Returned if the board property is successfully created.
Status 400
Returned if the boardId is invalid (negative or not a number).
Status 401
Returned if the calling user is not authenticated.
Status 404
Returned if the board with given id does not exist or the user doesn't have permissions to see it.

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

Responses

Status 200 - application/json
Example
```
{"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}
```
Returned if the board exists and the property was found.
Status 400
Returned if the boardId is invalid (negative or not a number).
Status 401
Returned if the calling user is not authenticated.
Status 404
Returned if the board with given id does not exist or if the property with given key is not found or the user doesn't have permissions to see it.

agile/1.0/board/{boardId}/sprint

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned sprints. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	The maximum number of sprints to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.
`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

Responses

Status 200 - application/json

Example

{"maxResults":2,"startAt":1,"total":5,"isLast":false,"values":[{"id":37,"self":"http://www.example.com/jira/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://www.example.com/jira/rest/agile/1.0/sprint/73","state":"future","name":"sprint 2","goal":"sprint 2 goal"}]}

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.

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if board does not exist or the user does not have permission to view it.

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	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.
`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`	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.

Responses

Status 200 - application/json

Example

{"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2","goal":"sprint 2 goal"},"closedSprints":[{"id":37,"self":"http://www.example.com/jira/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://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"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://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2017-03-08T23:31:08.127+0000","updated":"2017-03-08T23:31:08.241+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2017-03-08T23:31:08.245+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T23:31:08.245+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}}}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the board does not exist or the user does not have permission to view it.

agile/1.0/board/{boardId}/version

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned versions. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	The maximum number of versions to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.
`released`	string	Filters results to versions that are either released or unreleased. Valid values: true, false.

Responses

Status 200 - application/json

Example

{"maxResults":2,"startAt":1,"total":5,"isLast":false,"values":[{"self":"http://www.example.com/jira/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://www.example.com/jira/version/10010","id":10010,"projectId":10000,"name":"Next Version","description":"Minor Bugfix version","archived":false,"released":false}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if board does not exist or the user does not have permission to view it.

agile/1.0/epic

Epic is an enriched JIRA issue. Due to split nature of the entity, in order to perform complete create, update, and delete, you must leverage JIRA REST API. JIRA resources will help you manage the issue part of an Epic, and the following Agile resources give you control over Agile specific aspects.

Create epic `POST /rest/api/2/issue`

To create new epic use JIRA resource POST /rest/api/2/issue.
Note issueType must be set to epic and Epic Name custom field is mandatory. You can obtain Epic Name custom field id with JIRA resource GET /rest/api/2/field.

Update issue specific fields of epic `PUT /rest/api/2/issue/{issueIdOrKey}`

To update issue specific fields of an epic use JIRA resource PUT /rest/api/2/issue/{issueIdOrKey}.

Delete epic `DELETE /rest/api/2/issue`

To remove an epic use JIRA resource DELETE /rest/api/2/issue/{issueIdOrKey}.

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.

Responses

Status 200 - application/json

Example

{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true}

Returns the requested epic.

Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the epic does not exist or the user does not have permission to view it.

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.

Request

Example

{"name":"epic 2","summary":"epic 2 summary","color":{"key":"color_6"},"done":true}

Responses

Status 200 - application/json

Example

{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true}

Updated epic

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license or edit issue permission.
Status 404
Returned if the epic does not exist or the user does not have permission to view it.

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	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.
`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`	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.

Responses

Status 200 - application/json

Example

{"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2","goal":"sprint 2 goal"},"closedSprints":[{"id":37,"self":"http://www.example.com/jira/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://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"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://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2017-03-08T23:31:08.127+0000","updated":"2017-03-08T23:31:08.241+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2017-03-08T23:31:08.245+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T23:31:08.245+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}}}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the epic does not exist or the user does not have permission to view it.

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.

Request

Example

{"issues":["PR-1","10001","PR-3"]}

Responses

Status 204
Empty response is returned if operation was successful.
Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license or does not have edit issue permission for all issues to assign or for the epic.
Status 404
Returned if the epic does not exist or the user does not have permission to view it.

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.

Request

Example

{"rankBeforeEpic":"10000","rankCustomFieldId":10521}

Responses

Status 204
Empty response is returned if operation was successful.
Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if user does not a have valid license or does not have permission to rank. To rank issues user have to have schedule issue permission for epics that they want to rank.
Status 404
Returned when the given epics in the path parameter or the request body do not exist.

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	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.
`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`	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.

Responses

Status 200 - application/json

Example

{"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2","goal":"sprint 2 goal"},"closedSprints":[{"id":37,"self":"http://www.example.com/jira/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://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"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://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2017-03-08T23:31:08.127+0000","updated":"2017-03-08T23:31:08.241+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2017-03-08T23:31:08.245+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T23:31:08.245+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}}}]}

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

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.

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.

Request

Example

{"issues":["PR-1","10001","PR-3"]}

Responses

Status 204
Empty response is returned if operation was successful.
Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license or does not have permission to assign issues.
Status 404
Returned if the epic does not exist or the user does not have permission to view it.

agile/1.0/issue

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.

Request

query parameters

parameter	type	description
`fields`	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.

Responses

Status 200 - application/json

Example

{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2","goal":"sprint 2 goal"},"closedSprints":[{"id":37,"self":"http://www.example.com/jira/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://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"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://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2017-03-08T23:31:08.127+0000","updated":"2017-03-08T23:31:08.241+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2017-03-08T23:31:08.245+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T23:31:08.245+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}}}

Returns the requested issue.

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned in these cases:
- the issue does not exist
- the user does not have permission to view issue

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.

Request

query parameters

parameter	type	description
`boardId`	long	The id of the board required to determine which field is used for estimation.

Responses

Status 200
Example
```
{"fieldId":"customfield_12532","value":"8.0"}
```
Returns the estimation of the issue and a fieldId of the field that is used for it.
Status 400
Returned if the boardId was not provided, field does not exists or value was in wrong format.
Status 401
Returned if the user is not logged in.
Status 403
Returned if user does not a have valid license or does not have permission to edit issue.
Status 404
Returned in these cases:
- the issue does not exist
- the user does not have permission to view issue
- the board does not exist
- the user does not have permission to view board
- the issue does not belong to the board

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.

Request

query parameters

parameter	type	description
`boardId`	long	The id of the board required to determine which field is used for estimation.

Example

{"value":"8.0"}

Responses

Status 200
Example
```
{"fieldId":"customfield_12532","value":"8.0"}
```
Returns the estimation of the issue and a fieldId of the field that is used for it.
Status 400
Returned if the boardId was not provided, field does not exists or value was in wrong format.
Status 401
Returned if the user is not logged in.
Status 403
Returned if user does not a have valid license or does not have permission to edit issue.
Status 404
Returned in these cases:
- the issue does not exist
- the user does not have permission to view issue
- the board does not exist
- the user does not have permission to view board
- the issue does not belong to the board

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.

Request

Example

{"issues":["PR-1","10001","PR-3"],"rankBeforeIssue":"PR-4","rankCustomFieldId":10521}

Responses

Status 204
Empty response is returned if operation was successful.

Status 207 - application/json

Example

{"entries":[{"issueId":10000,"issueKey":"PR-1","status":200},{"issueId":10001,"issueKey":"PR-2","status":200},{"issueId":10002,"issueKey":"PR-3","status":503,"errors":["JIRA Agile cannot execute the rank operation at this time. Please try again later."]}]}

Returns the list of issue with status of rank operation.

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if user does not a have valid license or does not have permission to rank. To rank issues user have to have schedule issue permission for issues that they want to rank.

agile/1.0/sprint

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.

Request

Example

{"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

Status 201 - application/json

Example

{"id":37,"self":"http://www.example.com/jira/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"}

Created sprint

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the board does not exist or the user does not have permission to view it.

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.

Request

Example

{"state":"closed","name":"sprint 1","startDate":"2015-04-11T15:36:00.000+10:00","endDate":"2015-04-16T14:01:00.000+10:00","completeDate":"2015-04-20T11:11:28.008+10:00","goal":"sprint 1 goal"}

Responses

Status 200 - application/json

Example

{"id":37,"self":"http://www.example.com/jira/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"}

Updated sprint

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the sprint does not exist.

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.

Request

Example

{"name":"new name"}

Responses

Status 200 - application/json

Example

{"id":37,"self":"http://www.example.com/jira/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"}

Updated sprint

Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the sprint does not exist.

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

Deletes a sprint. Once a sprint is deleted, all issues in the sprint will be moved to the backlog. Note, only future sprints can be deleted.

Responses

Status 204 - application/json
Returned if the sprint was deleted successfully
Status 400
Returned if the sprint is active or completed.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license or does not have permission to delete sprints.
Status 404
Returned if the sprint does not exist.

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.

Responses

Status 200 - application/json

Example

{"id":37,"self":"http://www.example.com/jira/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"}

Returns the requested sprint.

Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if the sprint does not exist or the user does not have permission to view it.

Move issues to sprint`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.

Request

Example

{"issues":["PR-1","10001","PR-3"]}

Responses

Status 204
Empty response is returned if operation was successful.
Status 400
Returned if the request is invalid.
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license or does not have permission to assign issues.
Status 404
Returned if the sprint does not exist or the user does not have permission to view it.

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.

Request

query parameters

parameter	type	description
`startAt`	long	The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.
`maxResults`	int	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.
`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`	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.

Responses

Status 200 - application/json

Example

{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2","goal":"sprint 2 goal"},"closedSprints":[{"id":37,"self":"http://www.example.com/jira/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://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"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://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2017-03-08T23:31:08.127+0000","updated":"2017-03-08T23:31:08.241+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2017-03-08T23:31:08.245+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T23:31:08.245+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}}}

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

Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license.
Status 404
Returned if sprint does not exist or the user cannot view it.

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

Swap the position of the sprint with the second sprint.

Request

Example

{"sprintToSwapWith":3}

Responses

Status 204 - application/json
Returned if the sprint swap was performed successfully
Status 401
Returned if the user is not logged in.
Status 403
Returned if the user does not a have valid license or does not have permission to at least one sprint.
Status 404
Returned if at least one sprint does not exist or user does not have permission to view to at least one sprint.

agile/1.0/sprint/{sprintId}/properties

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.

Responses

Status 200 - application/json

Example

{"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}

Returned if the sprint with given id exists.

Status 400
Returned if the sprintId is invalid (negative or not a number).
Status 401
Returned if the calling user is not authenticated.
Status 403
Returned if the calling user does not have permission to view the sprint.
Status 404
Returned if the sprint with given id does not exist.

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.

Responses

Status 204
Returned if the sprint property was removed successfully.
Status 400
Returned if the sprintId is invalid (negative or not a number).
Status 401
Returned if the calling user is not authenticated.
Status 403
Returned if the calling user does not have permission to modify the sprint.
Status 404
Returned if the sprint with given id does not exist or if the property with given key is not found.

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.

Responses

Status 200
Returned if the sprint property is successfully updated.
Status 201
Returned if the sprint property is successfully created.
Status 400
Returned if the sprintId is invalid (negative or not a number).
Status 401
Returned if the calling user is not authenticated.
Status 403
Returned if the calling user does not have permission to edit the sprint
Status 404
Returned if the sprint with given id does not exist.

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.

Responses

Status 200 - application/json
Example
```
{"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}
```
Returned if the sprint exists and the property was found.
Status 400
Returned if the sprintId is invalid (negative or not a number).
Status 401
Returned if the calling user is not authenticated.
Status 403
Returned if the calling user does not have permission to view the sprint.
Status 404
Returned if the sprint with a given id does not exist or if the property with given key is not found.

Authentication

Authentication for Atlassian Connect add-ons

Authentication for REST API requests

URI structure

Pagination

Request

Response

Experimental methods

Query parameters

Special Request and Response headers

JIRA Software field input formats

Sprint custom field

Example - Get issue (JIRA platform) response

Example - Get issue (JIRA platform) response with expanded versionedRepresentations

Example - Update issue request

Epic link custom field

Example

Epic Name

Example

Estimation

Resources

Move issues to backlogPOST /rest/agile/1.0/backlog/issue

Request

Example

Responses

Get all boardsGET /rest/agile/1.0/board

Request

query parameters

Responses

Example

Create boardPOST /rest/agile/1.0/board

Request

Example

Responses

Example

Get boardGET /rest/agile/1.0/board/{boardId}

Responses

Example

Delete boardDELETE /rest/agile/1.0/board/{boardId}

Responses

Get issues for backlogGET /rest/agile/1.0/board/{boardId}/backlog

Request

query parameters

Responses

Example

Get configurationGET /rest/agile/1.0/board/{boardId}/configuration

Responses

Example

Get issues for boardGET /rest/agile/1.0/board/{boardId}/issue

Request

query parameters

Responses

Example

Get epicsGET /rest/agile/1.0/board/{boardId}/epic

Request

query parameters

Responses

Example

Get issues for epicGET /rest/agile/1.0/board/{boardId}/epic/{epicId}/issue

Request

query parameters

Responses

Example

Get issues without epicGET /rest/agile/1.0/board/{boardId}/epic/none/issue

Request

query parameters

Responses

Example

Get projectsGET /rest/agile/1.0/board/{boardId}/project

Request

query parameters

Responses

Example

Get projects fullGET /rest/agile/1.0/board/{boardId}/project/full

Responses

Get properties keysGET /rest/agile/1.0/board/{boardId}/properties

Responses

Example

Delete propertyDELETE /rest/agile/1.0/board/{boardId}/properties/{propertyKey}

Responses

Move issues to backlog`POST /rest/agile/1.0/backlog/issue`

Get all boards`GET /rest/agile/1.0/board`

Create board`POST /rest/agile/1.0/board`

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

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

Get issues for backlog`GET /rest/agile/1.0/board/{boardId}/backlog`

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

Get issues for board`GET /rest/agile/1.0/board/{boardId}/issue`

Get epics`GET /rest/agile/1.0/board/{boardId}/epic`

Get issues for epic`GET /rest/agile/1.0/board/{boardId}/epic/{epicId}/issue`

Get issues without epic`GET /rest/agile/1.0/board/{boardId}/epic/none/issue`

Get projects`GET /rest/agile/1.0/board/{boardId}/project`

Get projects full`GET /rest/agile/1.0/board/{boardId}/project/full`

Get properties keys`GET /rest/agile/1.0/board/{boardId}/properties`

Delete property`DELETE /rest/agile/1.0/board/{boardId}/properties/{propertyKey}`

Set property`PUT /rest/agile/1.0/board/{boardId}/properties/{propertyKey}`

Get property`GET /rest/agile/1.0/board/{boardId}/properties/{propertyKey}`

Get all sprints`GET /rest/agile/1.0/board/{boardId}/sprint`

Get issues for sprint`GET /rest/agile/1.0/board/{boardId}/sprint/{sprintId}/issue`

Get all versions`GET /rest/agile/1.0/board/{boardId}/version`

Create epic `POST /rest/api/2/issue`

Update issue specific fields of epic `PUT /rest/api/2/issue/{issueIdOrKey}`

Delete epic `DELETE /rest/api/2/issue`

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

Partially update epic`POST /rest/agile/1.0/epic/{epicIdOrKey}`

Get issues for epic`GET /rest/agile/1.0/epic/{epicIdOrKey}/issue`

Move issues to epic`POST /rest/agile/1.0/epic/{epicIdOrKey}/issue`

Rank epics`PUT /rest/agile/1.0/epic/{epicIdOrKey}/rank`

Get issues without epic`GET /rest/agile/1.0/epic/none/issue`

Remove issues from epic`POST /rest/agile/1.0/epic/none/issue`

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

Get issue estimation for board`GET /rest/agile/1.0/issue/{issueIdOrKey}/estimation`