Jira Agile Server REST API reference

Jira Agile 8.13.1

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

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

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

Authentication

The following authentication methods are supported for the JIRA REST APIs:

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

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

URI structure

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

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

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

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

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

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

Pagination

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

Request

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

Response

{
    "startAt" : 0,
    "maxResults" : 10,
    "total": 200,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
    ]
}
  • startAt - the item used as the first item in the page of results.
  • maxResults - how many results to return per page.
  • total - the number of items that the calling user has permissions for. This number may change while the client requests the next pages. A client should always assume that the requested page can be empty. REST API consumers should also consider the field to be optional. This value may not be included in the response, if it is too expensive to calculate.

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

Experimental methods

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

Query parameters

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

Special Request and Response headers

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

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.

projectKeyOrIdstring

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

Responses
  • Status 200 - application/json

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

    Returns the requested boards, at the specified page of the results.
  • Status 400
    Returned if the request is invalid.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not have valid license.

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

  • name - Must be less than 255 characters.
  • type - Valid values: scrum, kanban
  • filterId - Id of a filter that the user has permissions to view. Note, if the user does not have the 'Create shared objects' permission and tries to create a shared board, a private board will be created instead (remember that board sharing depends on the filter sharing).
p> Note:
  • If you want to create a new project with an associated board, use the JIRA platform REST API. For more information, see the Create project method. The projectTypeKey for software boards must be 'software' and the projectTemplateKey must be either com.pyxis.greenhopper.jira:gh-kanban-template or com.pyxis.greenhopper.jira:gh-scrum-template.
  • You can create a filter using the JIRA REST API. For more information, see the Create filter method.
  • If you do not ORDER BY the Rank field for the filter of your board, you will not be able to reorder issues on the board.

Request

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

Responses
  • Status 201 - application/json

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

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

Returns the board for the given board Id. This board will only be returned if the user has permission to view it.

Responses
  • Status 200 - application/json

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

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

Deletes the board.

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

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

Request
query parameters
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":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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","activatedDate":"2015-04-11T15:22:00.000+10:00"}],"description":"example bug report","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2020-11-02T20:27:11.121+0000","updated":"2020-11-02T20:27:11.125+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2020-11-02T20:27:11.129+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2020-11-02T20:27:11.129+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}],"updated":1,"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400}}}]}

    Returns the requested issues, at the specified page of the results.
  • Status 400
    Returned if the request is invalid.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not a have valid license.
  • Status 404
    Returned if the board does not exist or the user does not have permission to view it.

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

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

Responses
  • Status 200 - application/json

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

    Returns the configuration of the board for given boardId.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if user does not a have valid license.
  • Status 404
    Returned if board does not exist or the user cannot view it.

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":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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","activatedDate":"2015-04-11T15:22:00.000+10:00"}],"description":"example bug report","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2020-11-02T20:27:11.121+0000","updated":"2020-11-02T20:27:11.125+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2020-11-02T20:27:11.129+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2020-11-02T20:27:11.129+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}],"updated":1,"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400}}}]}

    Returns the requested issues, at the specified page of the results.
  • Status 400
    Returned if the request is invalid.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not a have valid license.
  • Status 404
    Returned if the board does not exist or the user does not have permission to view it.

agile/1.0/board/{boardId}/epic

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

Request
query parameters
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 the board, for the given epic Id and the board Id. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.

Request
query parameters
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":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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","activatedDate":"2015-04-11T15:22:00.000+10:00"}],"description":"example bug report","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2020-11-02T20:27:11.121+0000","updated":"2020-11-02T20:27:11.125+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2020-11-02T20:27:11.129+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2020-11-02T20:27:11.129+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}],"updated":1,"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400}}}]}

    Returns the requested issues, at the specified page of the results.
  • Status 400
    Returned if the request is invalid.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not a have valid license.
  • Status 404
    Returned if the board does not exist or the user does not have permission to view it.

Returns all issues that do not belong to any epic on a board, for a given board Id. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.

Request
query parameters
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":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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","activatedDate":"2015-04-11T15:22:00.000+10:00"}],"description":"example bug report","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2020-11-02T20:27:11.121+0000","updated":"2020-11-02T20:27:11.125+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2020-11-02T20:27:11.129+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2020-11-02T20:27:11.129+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}],"updated":1,"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400}}}]}

    Returns the requested issues, at the specified page of the results.
  • Status 400
    Returned if the request is invalid.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not a have valid license.
  • Status 404
    Returned if the board does not exist or the user does not have permission to view it.

agile/1.0/board/{boardId}/project

Returns all projects that are associated with the board, for the given board Id. A project is associated with a board only if the board filter explicitly filters issues by the project and guaranties that all issues will come for one of those projects e.g. board's filter with "project in (PR-1, PR-1) OR reporter = admin" jql Projects are returned only if user can browse all projects that are associated with the board.

Note, if the user does not have permission to view the board, no projects will be returned at all. Returned projects are ordered by the name.

Request
query parameters
parametertypedescription
startAtlong

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

maxResultsint

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

Responses
  • Status 200 - application/json

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

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

agile/1.0/board/{boardId}/properties

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

Responses
  • Status 200 - application/json

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

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

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

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

Sets the value of the specified board's property.

You can use this resource to store a custom data against the board identified by the id. The user who stores the data is required to have permissions to modify the board.

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

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

Responses
  • Status 200 - application/json

    Example
    {"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}

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

agile/1.0/board/{boardId}/settings

Returns the value of the setting for refined velocity chart

Responses
  • Status 200 - application/json
    Returned if the board exists and the property was found.
  • Status 400
    Returned if the boardId is invalid (negative or not a number).
  • Status 403
    Returned if the user does not have valid license.
  • Status 404
    Returned if the board with given id does not exist or if the property with given key is not found or the user doesn't have permissions to see it.

Sets the value of the specified board's refined velocity setting.

Request
Responses
  • Status 200
    Returned if the board property is successfully updated.
  • Status 201
    Returned if the board property is successfully created.
  • Status 400
    Returned if the boardId is invalid (negative or not a number).
  • Status 403
    Returned if the user does not have valid license.
  • Status 404
    Returned if the board with given id does not exist or if the property with given key is not found or the user doesn't have permissions to see it.

agile/1.0/board/{boardId}/sprint

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","activatedDate":"2015-04-11T15:22:00.000+10:00","originBoardId":5,"goal":"I'm making a note here: HUGE SUCCESS."},{"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":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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","activatedDate":"2015-04-11T15:22:00.000+10:00"}],"description":"example bug report","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2020-11-02T20:27:11.121+0000","updated":"2020-11-02T20:27:11.125+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2020-11-02T20:27:11.129+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2020-11-02T20:27:11.129+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}],"updated":1,"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400}}}]}

    Returns the requested issues, at the specified page of the results.
  • Status 400
    Returned if the request is invalid.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not a have valid license.
  • Status 404
    Returned if the board does not exist or the user does not have permission to view it.

agile/1.0/board/{boardId}/version

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

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

To create new epic use JIRA resource POST /rest/api/2/issue.
Note issueType must be set to epic and Epic Name custom field is mandatory. You can obtain Epic Name custom field id with JIRA resource GET /rest/api/2/field.
To update issue specific fields of an epic use JIRA resource PUT /rest/api/2/issue/{issueIdOrKey}.
To remove an epic use JIRA resource DELETE /rest/api/2/issue/{issueIdOrKey}.

Performs a partial update of the epic. A partial update means that fields not present in the request JSON will not be updated. Valid values for color are color_1 to color_9.

Request

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

Responses
  • Status 200 - application/json

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

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

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.

Moves issues to an epic, for a given epic id. Issues can be only in a single epic at the same time. That means that already assigned issues to an epic, will not be assigned to the previous epic anymore. The user needs to have the edit issue permission for all issue they want to move and to the epic. The maximum number of issues that can be moved in one operation is 50.

Request

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

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

Returns all issues that belong to the epic, for the given epic Id. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.

Request
query parameters
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":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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","activatedDate":"2015-04-11T15:22:00.000+10:00"}],"description":"example bug report","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2020-11-02T20:27:11.121+0000","updated":"2020-11-02T20:27:11.125+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2020-11-02T20:27:11.129+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2020-11-02T20:27:11.129+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}],"updated":1,"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400}}}]}

    Returns the requested issues, at the specified page of the results.
  • Status 400
    Returned if the request is invalid.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not a have valid license.
  • Status 404
    Returned if the epic does not exist or the user does not have permission to view it.

Moves (ranks) an epic before or after a given epic.

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

Request

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

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

Removes issues from epics. The user needs to have the edit issue permission for all issue they want to remove from epics. The maximum number of issues that can be moved in one operation is 50.

Request

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

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

Returns all issues that do not belong to any epic. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.

Request
query parameters
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":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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","activatedDate":"2015-04-11T15:22:00.000+10:00"}],"description":"example bug report","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2020-11-02T20:27:11.121+0000","updated":"2020-11-02T20:27:11.125+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2020-11-02T20:27:11.129+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2020-11-02T20:27:11.129+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}],"updated":1,"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400}}}]}

    Returns the requested issues, at the specified page of the results.
  • Status 400
    Returned if the request is invalid.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not a have valid license.

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.

updateHistoryboolean

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

Responses
  • Status 200 - application/json

    Example
    {"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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","activatedDate":"2015-04-11T15:22:00.000+10:00"}],"description":"example bug report","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2020-11-02T20:27:11.121+0000","updated":"2020-11-02T20:27:11.125+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2020-11-02T20:27:11.129+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2020-11-02T20:27:11.129+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}],"updated":1,"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400}}}

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

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

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

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

Request
query parameters
parametertypedescription
boardIdlong

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

Responses
  • Status 200

    Example
    {"fieldId":"customfield_12532","value":"8.0"}

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

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

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

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

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

Request
query parameters
parametertypedescription
boardIdlong

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

Example
{"value":"8.0"}

Responses
  • Status 200

    Example
    {"fieldId":"customfield_12532","value":"8.0"}

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

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

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,"goal":"Now these points of data make a beautiful line. And we're out of beta, we're releasing on time.","autoStartStop":false}

Responses
  • Status 201 - application/json

    Example
    {"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/23","state":"future","name":"sprint 1","startDate":"2015-04-11T15:22:00.000+10:00","endDate":"2015-04-20T01:22:00.000+10:00","originBoardId":5,"goal":"You just keep on trying till you run out of cake."}

    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","activatedDate":"2015-04-11T15:22:00.000+10:00","originBoardId":5,"goal":"I'm making a note here: HUGE SUCCESS."}

    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","goal":"We do what we must because we can."}

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","activatedDate":"2015-04-11T15:22:00.000+10:00","originBoardId":5,"goal":"I'm making a note here: HUGE SUCCESS."}

    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.
  • Sprint goal can be removed by updating it's value to empty string

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","activatedDate":"2015-04-11T15:22:00.000+10:00","originBoardId":5,"goal":"I'm making a note here: HUGE SUCCESS."}

    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
    {"expand":"","id":"10001","self":"http://www.example.com/jira/rest/agile/1.0/board/92/issue/10001","key":"HSP-1","fields":{"flagged":true,"sprint":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/sprint/13","state":"future","name":"sprint 2"},"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","activatedDate":"2015-04-11T15:22:00.000+10:00"}],"description":"example bug report","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"comment":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2020-11-02T20:27:11.121+0000","updated":"2020-11-02T20:27:11.125+0000","visibility":{"type":"role","value":"Administrators"}}],"epic":{"id":37,"self":"http://www.example.com/jira/rest/agile/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","updated":"2020-11-02T20:27:11.129+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2020-11-02T20:27:11.129+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}],"updated":1,"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400}}}

    Returns the requested issues, at the specified page of the results.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not a have valid license.
  • Status 404
    Returned if sprint does not exist or the user cannot view it.

Swap the position of the sprint with the second sprint.

Request

Example
{"sprintToSwapWith":3}

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

agile/1.0/sprint/{sprintId}/properties

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

Responses
  • Status 200 - application/json

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

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

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

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

Sets the value of the specified sprint's property.

You can use this resource to store a custom data against the sprint identified by the id. The user who stores the data is required to have permissions to modify the sprint.

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

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

Responses
  • Status 200 - application/json

    Example
    {"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}

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