JIRA Agile 6.7.11

This is the reference document for the REST API and resources provided by JIRA Agile. The REST APIs are developers who want to integrate JIRA Agile with other standalone or web applications, and administrators who want to script interactions with the JIRA Agile.

If you are after an introductory, high-level view of the JIRA REST APIs, like the JIRA Agile REST API, rather than an exhaustive reference document, then the best place to start is the JIRA REST API home.

Structure of the REST URIs

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 Agile instance. As an example, if you wanted to retrieve the JSON representation of the Teams in Space board (boardId=123) from an example JIRA Agile instance https://jira.example.com, you would access:

https://jira.example.com/rest/agile/latest/board/123

Authentication

Any authentication that works against JIRA Agile will work against the REST API. The prefered authentication methods are OAuth and HTTP Basic (when using SSL), which are both documented in the JIRA REST API Tutorials. Other supported methods include: HTTP Cookies, and Trusted Applications.

The login page uses cookie-based authentication, so if you are using JIRA Agile in a browser you can call REST from JavaScript on the page and rely on the authentication that the browser has established. Callers wanting to reproduce the behaviour of the JIRA Agile login page (for example, to display authentication error messages to users) or who are calling both the REST and SOAP API can POST to the /auth/1/session resource as per the documentation below.

You can find OAuth code samples in several programming languages at bitbucket.org/atlassian_tutorial/atlassian-oauth-examples.

Pagination

JIRA Agile uses pagination 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:

{
    "startAt" : 0,
    "maxResults" : 10,
    "total": 200,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
    ]
}

Clients can use the startAt and maxResults parameters to retrieve the desired numbers of results.

The maxResults parameter indicates how many results to return per page. Each API may have a different limit for number of items returned.

The startAt parameter indicates which item should be used as the first item in the page of results.

Important: The response contains a total field. This indicates, how many items to which calling user has permissions are in the system. This number may change while client requests 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. In cases, when calculating this value is too expensive we may not include this in response.

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.

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.

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.

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

Returns the board for a 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.

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

Returns all issues from a board's backlog, for a 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":{"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400},"project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"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","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"}},"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},"updated":1,"description":"example bug report","flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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":"2015-08-26T11:27:04.182+0200","updated":"2015-08-26T11:27:04.184+0200","visibility":{"type":"role","value":"Administrators"}}],"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"}],"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.","visibility":{"type":"group","value":"jira-developers"},"started":"2015-08-26T11:27:04.187+0200","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}]}}]}

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. Configuration contains fields:

filter - reference to the filter used by the given board
columnConfig - the column configuration with list of columns with the issue status mapping and constraint type for number of issues in column. Constraint type may be May be: none, issueCount, issueCountExclSubs. Each column may contains constraint of minimal and maximal number of issues. Columns are returned in order defined in configuration. The last column with statuses is treated like "done" column which means that issues from that column will be marked as already completed.
estimation - contains information about type of estimation used in board. May be: none, issueCount, field. For field type it contains field "field" with id and display name of the field used for estimation. Note that estimation can be updated by PUT /rest/api/2/issue/{issueIdOrKey} request but 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. Only Scrum boards have estimation.
ranking - contains information about custom field used for ranking in the given board.

Responses

Status 200 - application/json

Example

{"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. 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":{"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400},"project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"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","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"}},"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},"updated":1,"description":"example bug report","flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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":"2015-08-26T11:27:04.182+0200","updated":"2015-08-26T11:27:04.184+0200","visibility":{"type":"role","value":"Administrators"}}],"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"}],"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.","visibility":{"type":"group","value":"jira-developers"},"started":"2015-08-26T11:27:04.187+0200","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}]}}]}

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 a board, for a 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 a board, for a given epic Id and 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":{"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400},"project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"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","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"}},"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},"updated":1,"description":"example bug report","flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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":"2015-08-26T11:27:04.182+0200","updated":"2015-08-26T11:27:04.184+0200","visibility":{"type":"role","value":"Administrators"}}],"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"}],"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.","visibility":{"type":"group","value":"jira-developers"},"started":"2015-08-26T11:27:04.187+0200","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}]}}]}

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}/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},{"id":72,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/73","state":"future","name":"sprint 2"}]}

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":{"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400},"project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"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","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"}},"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},"updated":1,"description":"example bug report","flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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":"2015-08-26T11:27:04.182+0200","updated":"2015-08-26T11:27:04.184+0200","visibility":{"type":"role","value":"Administrators"}}],"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"}],"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.","visibility":{"type":"group","value":"jira-developers"},"started":"2015-08-26T11:27:04.187+0200","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}]}}]}

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

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

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.

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":{"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400},"project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"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","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"}},"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},"updated":1,"description":"example bug report","flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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":"2015-08-26T11:27:04.182+0200","updated":"2015-08-26T11:27:04.184+0200","visibility":{"type":"role","value":"Administrators"}}],"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"}],"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.","visibility":{"type":"group","value":"jira-developers"},"started":"2015-08-26T11:27:04.187+0200","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}]}}

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

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 and end date 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}

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}

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.

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}

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.

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

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}

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}

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.

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":{"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400},"project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"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","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"}},"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},"updated":1,"description":"example bug report","flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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":"2015-08-26T11:27:04.182+0200","updated":"2015-08-26T11:27:04.184+0200","visibility":{"type":"role","value":"Administrators"}}],"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"}],"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.","visibility":{"type":"group","value":"jira-developers"},"started":"2015-08-26T11:27:04.187+0200","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}]}}

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.

Structure of the REST URIs

Authentication

Pagination

Experimental methods

Query parameters

Special Request and Response headers

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

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

Responses

Example

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 all sprintsGET /rest/agile/1.0/board/{boardId}/sprint

Request

query parameters

Responses

Example

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

Request

query parameters

Responses

Example

Get all versionsGET /rest/agile/1.0/board/{boardId}/version

Request

query parameters

Responses

Example

Get epicGET /rest/agile/1.0/epic/{epicId}

Responses

Example

Get issueGET /rest/agile/1.0/issue/{issueIdOrKey}

Request

query parameters

Responses

Example

Rank issuesPUT /rest/agile/1.0/issue/rank

Request

Example

Responses

Example

Create sprintPOST /rest/agile/1.0/sprint

Request

Example

Responses

Example

Get sprintGET /rest/agile/1.0/sprint/{sprintId}

Responses

Example

Update sprintPUT /rest/agile/1.0/sprint/{sprintId}

Request

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

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

Get board`GET /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 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`

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

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

Rank issues`PUT /rest/agile/1.0/issue/rank`

Create sprint`POST /rest/agile/1.0/sprint`

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

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

Partially update sprint`POST /rest/agile/1.0/sprint/{sprintId}`

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

Move issues to sprint`POST /rest/agile/1.0/sprint/{sprintId}/issue`

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