JIRA Agile REST API Reference

JIRA Agile 6.7.12

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

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

Request
query parameters
parametertypedescription
startAtlong

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

maxResultsint

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

typestring

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

namestring

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.

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.

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
parametertypedescription
startAtlong

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

maxResultsint

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.

jqlstring

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.

validateQueryboolean

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

fieldsstring

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

expandstring

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-12-15T03:29:24.374+0000","updated":"2015-12-15T03:29:24.376+0000","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-12-15T03:29:24.380+0000","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 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.

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
parametertypedescription
startAtlong

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

maxResultsint

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.

jqlstring

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.

validateQueryboolean

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

fieldsstring

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

expandstring

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-12-15T03:29:24.374+0000","updated":"2015-12-15T03:29:24.376+0000","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-12-15T03:29:24.380+0000","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

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
parametertypedescription
startAtlong

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

maxResultsint

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

donestring

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.

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
parametertypedescription
startAtlong

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

maxResultsint

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.

jqlstring

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.

validateQueryboolean

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

fieldsstring

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

expandstring

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-12-15T03:29:24.374+0000","updated":"2015-12-15T03:29:24.376+0000","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-12-15T03:29:24.380+0000","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

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
parametertypedescription
startAtlong

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

maxResultsint

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

statestring

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 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
parametertypedescription
startAtlong

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

maxResultsint

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.

jqlstring

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.

validateQueryboolean

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

fieldsstring

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

expandstring

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-12-15T03:29:24.374+0000","updated":"2015-12-15T03:29:24.376+0000","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-12-15T03:29:24.380+0000","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

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
parametertypedescription
startAtlong

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

maxResultsint

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

releasedstring

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

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

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
parametertypedescription
fieldsstring

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

expandstring

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-12-15T03:29:24.374+0000","updated":"2015-12-15T03:29:24.376+0000","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-12-15T03:29:24.380+0000","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

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

This is a fragile operation and may succeed for some issues but fail for others. 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.

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

Creates a future sprint. The sprint name and state are required. 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.

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.

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.

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.

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.

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.

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
parametertypedescription
startAtlong

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

maxResultsint

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.

jqlstring

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.

validateQueryboolean

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

fieldsstring

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

expandstring

A comma-separated list of the parameters to expand.

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