Jira Agile Data Center 9.14.0 REST API reference (2024)

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

agile/1.0/backlog

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

Request
Schema
{"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}
Responses
  • application/json

agile/1.0/board

Get all boardsGET/rest/agile/1.0/board

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
typestring
namestring
projectKeyOrIdstring
Responses
  • application/json

Create boardPOST/rest/agile/1.0/board

Request
Schema
{"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}
Responses
  • application/json

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

Responses
  • application/json

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

Responses
  • application/json

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

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
jqlstring
validateQueryboolean
fieldsstring
expandstring
Responses
  • application/json

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

Responses
  • application/json

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

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
jqlstring
validateQueryboolean
fieldsstring
expandstring
Responses
  • application/json

agile/1.0/board/{boardId}/epic

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

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
donestring
Responses
  • application/json

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

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
jqlstring
validateQueryboolean
fieldsstring
expandstring
Responses
  • application/json

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

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
jqlstring
validateQueryboolean
fieldsstring
expandstring
Responses
  • application/json

agile/1.0/board/{boardId}/project

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

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
Responses
  • application/json

agile/1.0/board/{boardId}/properties

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

Responses
  • application/json

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

Responses
  • application/json

Set propertyPUT/rest/agile/1.0/board/{boardId}/properties/{propertyKey}

Responses
  • application/json

Get propertyGET/rest/agile/1.0/board/{boardId}/properties/{propertyKey}

Responses
  • application/json

agile/1.0/board/{boardId}/settings

Get refined velocityGET/rest/agile/1.0/board/{boardId}/settings/refined-velocity

Responses
  • application/json

Set refined velocityPUT/rest/agile/1.0/board/{boardId}/settings/refined-velocity

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

agile/1.0/board/{boardId}/sprint

Get all sprintsGET/rest/agile/1.0/board/{boardId}/sprint

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
statestring
Responses
  • application/json

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

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
jqlstring
validateQueryboolean
fieldsstring
expandstring
Responses
  • application/json

agile/1.0/board/{boardId}/version

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

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
releasedstring
Responses
  • application/json

agile/1.0/epic

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

Responses
  • application/json

Partially update epicPOST/rest/agile/1.0/epic/{epicIdOrKey}

Request
Schema
{"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}
Responses
  • application/json

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

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
jqlstring
validateQueryboolean
fieldsstring
expandstring
Responses
  • application/json

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

Request
Schema
{"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}
Responses
  • application/json

Rank epicsPUT/rest/agile/1.0/epic/{epicIdOrKey}/rank

Request
Schema
{"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}
Responses
  • application/json

Remove issues from epicPOST/rest/agile/1.0/epic/none/issue

Request
Schema
{"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}
Responses
  • application/json

Get issues without epicGET/rest/agile/1.0/epic/none/issue

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
jqlstring
validateQueryboolean
fieldsstring
expandstring
Responses
  • application/json

agile/1.0/issue

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

Request
query parameters
parametertypedescription
fieldsstring
expandstring
updateHistoryboolean
Responses
  • application/json

Get issue estimation for boardGET/rest/agile/1.0/issue/{issueIdOrKey}/estimation

Request
query parameters
parametertypedescription
boardIdlong
Responses
  • application/json

Estimate issue for boardPUT/rest/agile/1.0/issue/{issueIdOrKey}/estimation

Request
query parameters
parametertypedescription
boardIdlong
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/field-edit#","title":"Field Edit","type":"object","properties":{"value":{"type":"string"}},"additionalProperties":false}
Responses
  • application/json

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

Request
Schema
{"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}
Responses
  • application/json

agile/1.0/sprint

Create sprintPOST/rest/agile/1.0/sprint

Request
Schema
{"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"]}
Responses
  • application/json

Partially update sprintPOST/rest/agile/1.0/sprint/{sprintId}

Request
Schema
{"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}
Responses
  • application/json

Delete sprintDELETE/rest/agile/1.0/sprint/{sprintId}

Responses
  • application/json

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

Responses
  • application/json

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

Request
Schema
{"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}
Responses
  • application/json

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

Request
query parameters
parametertypedescription
startAtlong
maxResultsint
jqlstring
validateQueryboolean
fieldsstring
expandstring
Responses
  • application/json

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

Request
Schema
{"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}
Responses
  • application/json

Swap sprintPOST/rest/agile/1.0/sprint/{sprintId}/swap

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

Unmap sprints experimentalPUT/rest/agile/1.0/sprint/unmap

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

Unmap all sprints experimentalPUT/rest/agile/1.0/sprint/unmap-all

Responses
  • application/json

agile/1.0/sprint/{sprintId}/properties

Get properties keysGET/rest/agile/1.0/sprint/{sprintId}/properties

Responses
  • application/json

Delete propertyDELETE/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}

Responses
  • application/json

Set propertyPUT/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}

Responses
  • application/json

Get propertyGET/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}

Responses
  • application/json
Jira Agile Data Center 9.14.0 REST API reference (2024)
Top Articles
Latest Posts
Article information

Author: Manual Maggio

Last Updated:

Views: 6578

Rating: 4.9 / 5 (49 voted)

Reviews: 88% of readers found this page helpful

Author information

Name: Manual Maggio

Birthday: 1998-01-20

Address: 359 Kelvin Stream, Lake Eldonview, MT 33517-1242

Phone: +577037762465

Job: Product Hospitality Supervisor

Hobby: Gardening, Web surfing, Video gaming, Amateur radio, Flag Football, Reading, Table tennis

Introduction: My name is Manual Maggio, I am a thankful, tender, adventurous, delightful, fantastic, proud, graceful person who loves writing and wants to share my knowledge and understanding with you.