Jira Agile Data Center REST API reference

Welcome to the Jira Software Data Center 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 Data Center, 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 Software Cloud REST API
• List of all Jira Software REST APIs

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 platform is here: Jira platform REST API.

Authentication

The following authentication methods are supported for the Jira Software REST APIs:

• Recommended:
• OAuth 2.0 - This method provides APIs to allow external services to access resources on a user’s behalf with the OAuth 2.0 protocol. This protocol is not compatible with Oauth 1.0a.
• Personal access token (PAT) - This method incorporates the user account in the access token. It is a safe alternative to using username and password for authentication with various services.
• Other:
• OAuth 1.0a - This method provides APIs to allow external services to access resources on a user’s behalf with the OAuth 1.0 protocol. This protocol is deprecated.
• Basic HTTP - This method is only recommended for tools like scripts or bots. It is easier to implement but much less secure.

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

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 Data Center instance. For example, if you wanted to retrieve the JSON representation of a board with boardId=123, from a Jira Software Data Center 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

{"id":"https://docs.atlassian.com/jira/REST/schema/issue-assign-request#","title":"Issue Assign Request","type":"object","properties":{"issues":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/board-create#","title":"Board Create","type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"filterId":{"type":"integer"}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/boolean-setting#","title":"Boolean Setting","type":"object","properties":{"value":{"type":"boolean"}},"additionalProperties":false,"required":["value"]}

{"id":"https://docs.atlassian.com/jira/REST/schema/boolean-setting#","title":"Boolean Setting","type":"object","properties":{"value":{"type":"boolean"}},"additionalProperties":false,"required":["value"]}

{"id":"https://docs.atlassian.com/jira/REST/schema/epic-update#","title":"Epic Update","type":"object","properties":{"name":{"type":"string"},"summary":{"type":"string"},"color":{"title":"Color","type":"object","properties":{"key":{"type":"string","enum":["color_1","color_2","color_3","color_4","color_5","color_6","color_7","color_8","color_9","color_10","color_11","color_12","color_13","color_14"]}},"additionalProperties":false},"done":{"type":"boolean"}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/issue-assign-request#","title":"Issue Assign Request","type":"object","properties":{"issues":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/epic-rank-request#","title":"Epic Rank Request","type":"object","properties":{"rankBeforeEpic":{"type":"string"},"rankAfterEpic":{"type":"string"},"rankCustomFieldId":{"type":"integer"}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/issue-assign-request#","title":"Issue Assign Request","type":"object","properties":{"issues":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/field-edit#","title":"Field Edit","type":"object","properties":{"value":{"type":"string"}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/issue-rank-request#","title":"Issue Rank Request","type":"object","properties":{"issues":{"type":"array","items":{"type":"string"}},"rankBeforeIssue":{"type":"string"},"rankAfterIssue":{"type":"string"},"rankCustomFieldId":{"type":"integer"}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/sprint-create#","title":"Sprint Create","type":"object","properties":{"name":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"originBoardId":{"type":"integer"},"goal":{"type":"string"},"autoStartStop":{"type":"boolean"},"synced":{"type":"boolean"},"incompleteIssuesDestinationId":{"type":"integer"},"userProfileTimeZone":{"type":"string"}},"additionalProperties":false,"required":["autoStartStop","synced"]}

{"id":"https://docs.atlassian.com/jira/REST/schema/sprint#","title":"Sprint","type":"object","properties":{"id":{"type":"integer"},"state":{"type":"string"},"name":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"completeDate":{"type":"string"},"activatedDate":{"type":"string"},"originBoardId":{"type":"integer"},"goal":{"type":"string"},"synced":{"type":"boolean"},"autoStartStop":{"type":"boolean"},"incompleteIssuesDestinationId":{"type":"integer"}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/sprint#","title":"Sprint","type":"object","properties":{"id":{"type":"integer"},"state":{"type":"string"},"name":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"completeDate":{"type":"string"},"activatedDate":{"type":"string"},"originBoardId":{"type":"integer"},"goal":{"type":"string"},"synced":{"type":"boolean"},"autoStartStop":{"type":"boolean"},"incompleteIssuesDestinationId":{"type":"integer"}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/issue-assign-request#","title":"Issue Assign Request","type":"object","properties":{"issues":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/sprint-swap#","title":"Sprint Swap","type":"object","properties":{"sprintToSwapWith":{"type":"integer"}},"additionalProperties":false}

{"id":"https://docs.atlassian.com/jira/REST/schema/unmap-sprints#","title":"Unmap Sprints","type":"object","properties":{"sprintIds":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false}