Introduction

Welcome to the Jira Software Cloud 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 Cloud, 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 Cloud platform is here: Jira Cloud platform REST API.

Authentication

Authentication for Atlassian Connect add-ons

If you are integrating with the Jira REST APIs via an Atlassian Connect add-on, API calls are authenticated via JWT (JSON Web Tokens). This is built into the supported Atlassian Connect libraries. At a high level, authentication works by the add-on exchanging a security context with the application. This context is used to create and validate JWT tokens, embedded in API calls. To learn more, read the Atlassian Connect authentication documentation.

Authentication for REST API requests

If you are integrating directly with the REST APIs, rather than via an Atlassian Connect add-on, use one of the authentication methods listed below:

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

Copy
1
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 Cloud instance. For example, if you wanted to retrieve the JSON representation of a board with boardId=123, from a Jira Software Cloud instance at https://jira.atlassian.net, you would access:

Copy
1
https://jira.atlassian.net/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 metadata, like this:

Request

Copy
1
http://host:port/context/rest/api-name/api-version/resource-name?startAt=0&maxResults=10

Response

Copy
1
2
3
4
5
6
7
8
9
10
{
    "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: no-check' header.

Jira Software field input formats

Jira Software provides a number of custom fields, which are made available in the Jira platform REST API. The custom fields are: Sprint, Epic link, Epic name, and Story points.

You can read and edit these custom fields via the issue resource of the Jira Platform REST API. In order to identify the custom field that you want to read or edit, you'll need the custom field id. To obtain the custom field id, retrieve the list of fields from the fields resource and search for the custom field. It's better to find the field based on the schema where possible (e.g. the Sprint field is identified by "com.pyxis.greenhopper.jira:gh-sprint"), as custom field names are mutable. The custom field id will be in the id, (e.g. id: customfield_10007).

If you only need to get the value of the custom field for a single issue, you may want to use the issue resource provided by the Jira Software REST API instead. This resource returns the issue with all Jira Software-specific fields, including the fields listed above. These fields will also be formatted as proper fields with keys, in the response.

Note, Jira Software also has a number of internal custom fields, which are: Epic Color, Epic Status, Flag, Rank. These internal fields shouldn't be read or updated using the REST API and are not documented below.

Sprint custom field

The Sprint custom field contains a list of sprints for a given issue. This list includes the active/future sprint that the issue is currently in, as well as any closed sprints that the issue was in previously.

For legacy reasons, the Get issue (Jira platform) method returns the Sprint custom field with sprints in a toString format, which is difficult to parse. See the example below.

Deprecation notice: The toString representation of sprints in the Sprint custom field that is returned by Get issue (Jira platform) will soon be removed. See the notice.

Example - Get issue (Jira platform) response
Copy
1
2
3
4
customfield_11458": [
    "com.atlassian.greenhopper.service.sprint.Sprint@1bf75fd[id=1,rapidViewId=1,state=CLOSED,name=Sprint 1,goal=Sprint 1 goal,startDate=2016-06-06T21:30:53.537+10:00,endDate=2016-06-20T21:30:00.000+10:00,completeDate=2016-06-06T21:30:57.523+10:00,sequence=1]",
    "com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=<null>,endDate=<null>,completeDate=<null>,sequence=2]"
]

If you want to parse the sprint information, use either the Get issue (Jira Software) method or Get issue (Jira platform) method with expanded versionedRepresentations instead, both of which return sprints in a proper format. See the example below.

Example - Get issue (Jira platform) response with expanded versionedRepresentations
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
"customfield_10021": {
    "1": [
        "com.atlassian.greenhopper.service.sprint.Sprint@1bf75fd[id=1,rapidViewId=1,state=CLOSED,name=Sprint 1,goal=Sprint 1 goal,startDate=2016-06-06T21:30:53.537+10:00,endDate=2016-06-20T21:30:00.000+10:00,completeDate=2016-06-06T21:30:57.523+10:00,sequence=1]",
        "com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=<null>,endDate=<null>,completeDate=<null>,sequence=2]"
    ],
    "2": [
        {
            "id": 1,
            "name": "Sprint 1",
            "state": "closed",
            "boardId": 1
        },
        {
            "id": 2,
            "name": "Sprint 2",
            "state": "future",
            "boardId": 1
        }
    ]
}

If you want to update a sprint, you need to know the sprint id, which is a number. See the example below. Note, an issue can only be in one active or future sprint at a time, and only the active/future sprint can edited.

Example - Update issue request
Copy
1
"customfield_10021": 2
Epic link custom field

The Epic link custom field contains the key of an epic that a given issue belongs to. Be aware that only the issue key of the existing epic can be set. Also, the Epic link cannot be set for sub-tasks and epics.

Example
Copy
1
"customfield_11458": "EPIC-1"
Epic Name

The Epic name custom field contains the name of an epic that a given issue belongs to. Be aware that only the issue key of the existing epic can be set. Also, the epic link cannot be set for sub-tasks and epics.

Example
Copy
1
"customfield_11410": "Epic Name"
Estimation

Jira Software provides a Story Points custom field, however the field is just a regular numeric field. The type of estimation and field used for estimation is determined by the board configuration. You can get this from the board configuration resource. Note that if the estimation field is not on a screen, it cannot be edited, and you should use the Estimate issue for board method instead.

Feature Flags

This api requires the feature flag module to be defined by the app that is invoking the api.

Update / insert feature flag data.

POST /rest/featureflags/1.0/bulk

feature flags are identified by their ID, and existing feature flag data for the same ID will be replaced if it exists and the updateSequenceId of existing data is less than the incoming data.

Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are available within a short period of time, but may take some time during peak load and/or maintenance times. The getFeatureFlagById operation can be used to confirm that data has been stored successfully (if needed).

In the case of multiple feature flags being submitted in one request, each is validated individually prior to submission. Details of which feature flags failed submission (if any) are available in the response object.

Only apps that define the feature flag module can access this resource. This resource requires the ‘WRITE’ scope.

Response content type: application/json

Request

Body parameters

flags An array of FeatureFlagData, must have at least one entry

Each feature flag may be associated with 1 or more Jira issue keys, and will be associated with any properties included in this request.

properties An object holding key/value pairs, a maximum of 100 can be supplied

FeatureFlagData

Data related to a single feature flag, across any environment that the flag is present in.

schemaVersion string.

The FeatureFlagData schema version used for this flag data. Placeholder to support potential schema changes in the future.

id string. maxLength 255.

The identifier for the feature flag. Must be unique for a given provider.

key string. maxLength 255.

The identifier that users would use to reference the feature flag in their source code etc. Will be made available via the UI for users to copy into their source code etc.

updateSequenceId integer.

An ID used to apply an ordering to updates for this feature flag in the case of out-of-order receipt of update requests.

This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each feature flag and increment that on each update to Jira).

Updates for a feature flag that are received with an updateSqeuenceId lower than what is currently stored will be ignored.

displayName string. maxLength 255.

The human-readable name for the feature flag. Will be shown in the UI.

If not provided, will use the ID for display.

issueKeys string array. min items 1. Max items 255

The Jira issue keys to associate the feature flag information with.

summary FeatureFlagSummary

details An array of FeatureFlagDetails

FeatureFlagSummary

Summary information for a single feature flag. This is the summary information that will be presented to the user on e.g. the Jira issue screen.

url string. maxLength 2000

A URL users can use to link to a summary view of this flag, if appropriate.

This could be any location that makes sense in the provider system (e.g. if the summary information comes from a specific environment, it might make sense to link the user to the flag in that environment).

lastUpdated string in date time format. Example 2018-01-20T23:27:25+00:00

The last-updated timestamp to present to the user as a summary of the state of the feature flag.

Providers may choose to supply the last-updated timestamp from a specific environment, or the ‘most recent’ last-updated timestamp across all environments - whatever makes sense in the provider system.

Expected format is an RFC3339 formated string.

status A FeatureFlagStatus

FeatureFlagStatus

Status information about a single feature flag.

enabled boolean

Whether the feature flag is enabled in the given environment (or in summary).

Enabled may imply a partial rollout, which can be described using the ‘rollout’ field.

defaultValue string. maxLength 255

The value served by this feature flag when it is disabled. This could be the actual value or an alias, as appropriate.

This value may be presented to the user in the UI.

rollout A FeatureFlagRollout

FeatureFlagRollout

Information about the rollout of a feature flag in an environment (or in summary).

Only one of 'percentage’, 'text’, or ‘rules’ should be provided. They will be used in that order if multiple are present.

This information may be presented to the user in the UI.

percentage number. minimum 0

If the feature flag rollout is a simple percentage rollout

text string. maxLength 255

A text status to display that represents the rollout. This could be e.g. a named cohort.

rules integer. minimum 0

A count of the number of rules active for this feature flag in an environment.

FeatureFlagDetails

Details of a feature flag for a single environment.

url string. maxLength 2000

A URL users can use to link to a summary view of this flag, if appropriate.

lastUpdated string in date time format. Example 2018-01-20T23:27:25+00:00

The last-updated timestamp to present to the user as a summary of the state of the feature flag.

Providers may choose to supply the last-updated timestamp from a specific environment, or the ‘most recent’ last-updated timestamp across all environments - whatever makes sense in the provider system.

Expected format is an RFC3339 formated string.

environment An EnvironmentDetails

status A FeatureFlagStatus

EnvironmentDetails

Details of a single environment. At the simplest this must be the name of the environment. Ideally there is also type information which may be used to group data from multiple feature flags and other entities for visualisation in the UI.

name string. maxLength 255

The name of the environment.

type string enum.

The ‘type’ or ‘category’ of environment this environment belongs to.

Valid values are development, testing, staging, production

Example Request

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
  "flags": [
    {
      "schemaVersion": "1.0",
      "id": "111-222-333",
      "key": "my-awesome-feature",
      "updateSequenceId": 1523494301448,
      "displayName": "Enable awesome feature",
      "issueKeys": [
        "ISSUE-123"
      ],
      "summary": {
        "url": "https://example.com/project/feature-123/summary",
        "status": {
          "enabled": true,
          "defaultValue": "Disabled",
          "rollout": {
            "percentage": 80
          }
        },
        "lastUpdated": "2018-01-20T23:27:25+00:00"
      },
      "details": [
        {
          "url": "https://example.com/project/feature-123/production",
          "lastUpdated": "2018-01-20T23:27:25+00:00",
          "environment": {
            "name": "prod-us-west",
            "type": "production"
          },
          "status": {
            "enabled": true,
            "defaultValue": "Disabled",
            "rollout": {
              "percentage": 80
            }
          }
        }
      ]
    }
  ],
  "properties": {
    "key": "value",
    "foo": "bah"
  }
}

Response

202 Submission accepted. Each submitted feature flag that is of a valid format will be eventually available in Jira.

Details of which feature flags were submitted and which failed submission (due to data format problems etc.) are available in the response object.

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "acceptedFeatureFlags": [
    "111-222-333",
    "444-555-666"
  ],
  "failedFeatureFlags": {
    "additionalProp1": [
      {
        "message": "string",
        "errorTraceId": "string"
      }
    ],
    "additionalProp2": [
      {
        "message": "string",
        "errorTraceId": "string"
      }
    ],
    "additionalProp3": [
      {
        "message": "string",
        "errorTraceId": "string"
      }
    ]
  },
  "unknownIssueKeys": [
    "ISSUE-123"
  ]
}

400 Request has incorrect format.

Note that in the case of an individual feature flag having an invalid format (rather than the request as a whole) the response for the request will be a 202 and details of the invalid feature flag will be contained in the response object.

Example

Copy
1
2
3
4
5
6
[
  {
    "message": "string",
    "errorTraceId": "string"
  }
]

401 Missing a JWT token, or token is invalid.

403 The JWT token used does not correspond to an app that defines the feature flags module, or the app does not define the ‘WRITE’ scope.

413 Data is too large. Submit fewer feature flags in each payload.

429 API rate limit has been exceeded.

503 Service is unavailable due to maintenance or other reasons.

Delete Feature flags by Property

DELETE /rest/featureflags/1.0/bulkByProperties

Bulk delete all feature flags that match the given request.

In addition to the optional updateSequenceId, one or more query params must be supplied to specify Properties to delete by. If more than one Property is provided, data will be deleted that matches ALL of the Properties (e.g. treated as an AND). See the documentation for the submitFeatureFlags operation for more details.

e.g. DELETE /bulkByProperties?accountId=account-123&createdBy=user-456

Deletion is performed asynchronously. The getFeatureFlagById operation can be used to confirm that data has been deleted successfully (if needed).

Only apps that define the feature flags module can access this resource. This resource requires the ‘DELETE’ scope.

Request

Query Parameters

_updateSequenceId An optional updateSequenceId to use to control deletion.

Only stored data with an updateSequenceId less than or equal to that provided will be deleted.

This can be used help ensure submit/delete requests are applied correctly if issued close together.

If not provided, all stored data that matches the request will be deleted.

Response

202 Delete accepted. Data will eventually be removed from Jira.

400 Request has incorrect format e.g. missing at least one Property param.

Example

Copy
1
2
3
4
5
6
[
  {
    "message": "string",
    "errorTraceId": "string"
  }
]

401 Missing a JWT token, or token is invalid.

403 The JWT token used does not correspond to an app that defines the feature flags module, or the app does not define the ‘WRITE’ scope.

413 Data is too large. Submit fewer feature flags in each payload.

429 API rate limit has been exceeded.

503 Service is unavailable due to maintenance or other reasons.

Get a feature flag by ID

GET /rest/featureflags/1.0/flag/{featureFlagId}

Retrieve the currently stored feature flag data for the given ID.

The result will be what is currently stored, ignoring any pending updates or deletes.

Only apps that define the feature flags module can access this resource. This resource requires the ‘READ’ scope.

Request

Query Parameters

featureFlagId The ID of the feature flag to fetch.

Response

200 The feature flag data currently stored for the given ID.

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "schemaVersion": "1.0",
  "id": "111-222-333",
  "key": "my-awesome-feature",
  "updateSequenceId": 1523494301448,
  "displayName": "Enable awesome feature",
  "issueKeys": [
    "ISSUE-123"
  ],
  "summary": {
    "url": "https://example.com/project/feature-123/summary",
    "status": {
      "enabled": true,
      "defaultValue": "Disabled",
      "rollout": {
        "percentage": 80
      }
    },
    "lastUpdated": "2018-01-20T23:27:25+00:00"
  },
  "details": [
    {
      "url": "https://example.com/project/feature-123/production",
      "lastUpdated": "2018-01-20T23:27:25+00:00",
      "environment": {
        "name": "prod-us-west",
        "type": "production"
      },
      "status": {
        "enabled": true,
        "defaultValue": "Disabled",
        "rollout": {
          "percentage": 80
        }
      }
    }
  ]
}

401 Missing a JWT token, or token is invalid.

403 The JWT token used does not correspond to an app that defines the feature flags module, or the app does not define the ‘WRITE’ scope.

413 Data is too large. Submit fewer feature flags in each payload.

429 API rate limit has been exceeded.

503 Service is unavailable due to maintenance or other reasons.

Delete a feature flag by ID

DELETE /rest/featureflags/1.0/flag/{featureFlagId}

Delete the feature flag data currently stored for the given ID.

Deletion is performed asynchronously. The getFeatureFlagById operation can be used to confirm that data has been deleted successfully (if needed).

Only apps that define the feature flags module can access this resource. This resource requires the ‘DELETE’ scope.

Request

Query Parameters

featureFlagId The ID of the feature flag to fetch.

Response

202 Delete has been accepted. Data will eventually be removed from Jira if it exists.

401 Missing a JWT token, or token is invalid.

403 The JWT token used does not correspond to an app that defines the feature flags module, or the app does not define the ‘WRITE’ scope.

413 Data is too large. Submit fewer feature flags in each payload.

429 API rate limit has been exceeded.

503 Service is unavailable due to maintenance or other reasons.

Backlog

Apis related to the backlog

Move issues to backlog

POST /rest/agile/1.0/backlog/issue

Move issues to the backlog.
This operation is equivalent to remove future and active sprints from a given set of issues. At most 50 issues may be moved at once.

App scope requiredWRITE

Request

Body parameters
issues

Array<string>

Unique items: true

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/backlog/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "issues": [
    "PR-1",
    "10001",
    "PR-3"
  ]
}'

Responses

Empty response is returned if operation was successful.

Board

Apis related to boards

Get all boards

GET /rest/agile/1.0/board

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

App scope requiredREAD

Request

Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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

Format: int32
type

string

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

name

string

Filters results to boards that match or partially match the specified name.

projectKeyOrId

string

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

userkeyLocation

string

usernameLocation

string

projectLocation

string

includePrivate

boolean

Appends private boards to the end of the list. The name and type fields are excluded for security reasons.

orderBy

string

Ordering of the results by a given field. If not provided, values will not be sorted. Valid values: name.

expand

string

List of fields to expand for each board. Valid values: admins, permissions.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested boards, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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"
    }
  ]
}

Create board

POST /rest/agile/1.0/board

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).
  • location - The container that the board will be located in. location must include the type property (Valid values: project, user). If choosing 'project', then a project must be specified by a projectKeyOrId property in location. If choosing 'user', the current user is chosen by default. The projectKeyOrId property should not be provided.

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.

App scope requiredWRITE

Request

Body parameters
name

string

type

string

filterId

integer

Format: int64
location

LocationBean

Example

Copy
1
2
3
4
5
6
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data 'null'

Responses

Returns the created board.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
{
  "id": 84,
  "self": "http://www.example.com/jira/rest/agile/1.0/board/84",
  "name": "scrum board",
  "type": "scrum"
}

Get board

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

Returns the board for the given board ID. This board will only be returned if the user has permission to view it. Admins without the view permission will see the board as a private one, so will see only a subset of the board's data (board location for instance).

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the requested board.

Format: int64

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested board.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
{
  "id": 84,
  "self": "http://www.example.com/jira/rest/agile/1.0/board/84",
  "name": "scrum board",
  "type": "scrum",
  "location": {
    "projectId": 10040,
    "userId": 10040,
    "name": "Example Project",
    "projectTypeKey": "KEY"
  }
}

Delete board

DELETE /rest/agile/1.0/board/{boardId}

Deletes the board. Admin without the view permission can still remove the board.

App scope requiredDELETE

Request

Path parameters
boardId Required

integer

ID of the board to be deleted

Format: int64

Example

Copy
1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the board has been successfully removed.

Get issues for backlog

GET /rest/agile/1.0/board/{boardId}/backlog

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.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that has the backlog containing the requested issues.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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.

Format: int32
jql

string

Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues.

validateQuery

boolean

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

fields

Array<string>

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

expand

string

This parameter is currently not used.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/backlog' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested issues, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
{
  "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",
          "goal": "sprint 2 goal"
        },
        "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",
            "goal": "sprint 1 goal"
          }
        ],
        "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"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://www.example.com/jira/rest/api/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "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": "2018-06-25T12:49:15.057+1000",
            "updated": "2018-06-25T12:49:15.057+1000",
            "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/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-06-25T12:49:15.118+1000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-06-25T12:49:15.118+1000",
            "timeSpent": "3h 20m",
            "timeSpentSeconds": 12000,
            "id": "100028",
            "issueId": "10002"
          }
        ],
        "updated": 1,
        "timetracking": {
          "originalEstimate": "10m",
          "remainingEstimate": "3m",
          "timeSpent": "6m",
          "originalEstimateSeconds": 600,
          "remainingEstimateSeconds": 200,
          "timeSpentSeconds": 400
        }
      }
    }
  ]
}

Get configuration

GET /rest/agile/1.0/board/{boardId}/configuration

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.
  • location - Reference to the container that the board is located in. Includes the container type (Valid values: project, user).
  • 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.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board for which configuration is requested.

Format: int64

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/configuration' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the configuration of the board for given boardId.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
{
  "id": 10000,
  "name": "Board",
  "self": "http://www.example.com/jira/rest/agile/1.0/board/84/config",
  "location": {
    "type": "project",
    "key": "PROJ",
    "id": "10010",
    "self": "http://www.example.com/jira/rest/api/2/project/10010"
  },
  "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
  }
}

Get epics

GET /rest/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.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested epics.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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

Format: int32
done

string

Filters results to epics that are either done or not done. Valid values: true, false.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/epic' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested epics, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "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
    }
  ]
}

Get issues without epic

GET /rest/agile/1.0/board/{boardId}/epic/none/issue

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.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested issues.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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.

Format: int32
jql

string

Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues.

validateQuery

boolean

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

fields

Array<string>

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

expand

string

A comma-separated list of the parameters to expand.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/epic/none/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested issues, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
{
  "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",
          "goal": "sprint 2 goal"
        },
        "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",
            "goal": "sprint 1 goal"
          }
        ],
        "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"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://www.example.com/jira/rest/api/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "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": "2018-06-25T12:49:15.057+1000",
            "updated": "2018-06-25T12:49:15.057+1000",
            "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/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-06-25T12:49:15.118+1000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-06-25T12:49:15.118+1000",
            "timeSpent": "3h 20m",
            "timeSpentSeconds": 12000,
            "id": "100028",
            "issueId": "10002"
          }
        ],
        "updated": 1,
        "timetracking": {
          "originalEstimate": "10m",
          "remainingEstimate": "3m",
          "timeSpent": "6m",
          "originalEstimateSeconds": 600,
          "remainingEstimateSeconds": 200,
          "timeSpentSeconds": 400
        }
      }
    }
  ]
}

Get issues for epic

GET /rest/agile/1.0/board/{boardId}/epic/{epicId}/issue

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.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested issues.

Format: int64
epicId Required

integer

The ID of the epic that contains the requested issues.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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.

Format: int32
jql

string

Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues.

validateQuery

boolean

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

fields

Array<string>

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

expand

string

A comma-separated list of the parameters to expand.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/epic/{epicId}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested issues, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
{
  "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",
          "goal": "sprint 2 goal"
        },
        "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",
            "goal": "sprint 1 goal"
          }
        ],
        "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"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://www.example.com/jira/rest/api/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "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": "2018-06-25T12:49:15.057+1000",
            "updated": "2018-06-25T12:49:15.057+1000",
            "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/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-06-25T12:49:15.118+1000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-06-25T12:49:15.118+1000",
            "timeSpent": "3h 20m",
            "timeSpentSeconds": 12000,
            "id": "100028",
            "issueId": "10002"
          }
        ],
        "updated": 1,
        "timetracking": {
          "originalEstimate": "10m",
          "remainingEstimate": "3m",
          "timeSpent": "6m",
          "originalEstimateSeconds": 600,
          "remainingEstimateSeconds": 200,
          "timeSpentSeconds": 400
        }
      }
    }
  ]
}

Get features for board

GET /rest/agile/1.0/board/{boardId}/features

App scope requiredREAD

Request

Path parameters
boardId Required

integer

Format: int64

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/features' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

200 response

Content typeValue
application/json

BoardFeatureResponseBean

Toggle features

PUT /rest/agile/1.0/board/{boardId}/features

App scope requiredWRITE

Request

Path parameters
boardId Required

integer

Format: int64
Body parameters
boardId

integer

Format: int64
feature

string

enabling

boolean

Example

Copy
1
2
3
4
5
6
7
8
9
10
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/features' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "boardId": 2154,
  "feature": "<string>",
  "enabling": true
}'

Responses

200 response

Content typeValue
application/json

BoardFeatureResponseBean

Get issues for board

GET /rest/agile/1.0/board/{boardId}/issue

Returns all issues from a board, for a given board ID. This only includes issues that the user has permission to view. An issue belongs to the board if its status is mapped to the board's column. Epic issues do not belongs to the scrum boards. 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.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested issues.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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.

Format: int32
jql

string

Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues.

validateQuery

boolean

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

fields

Array<string>

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

expand

string

This parameter is currently not used.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested issues, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
{
  "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",
          "goal": "sprint 2 goal"
        },
        "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",
            "goal": "sprint 1 goal"
          }
        ],
        "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"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://www.example.com/jira/rest/api/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "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": "2018-06-25T12:49:15.057+1000",
            "updated": "2018-06-25T12:49:15.057+1000",
            "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/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-06-25T12:49:15.118+1000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-06-25T12:49:15.118+1000",
            "timeSpent": "3h 20m",
            "timeSpentSeconds": 12000,
            "id": "100028",
            "issueId": "10002"
          }
        ],
        "updated": 1,
        "timetracking": {
          "originalEstimate": "10m",
          "remainingEstimate": "3m",
          "timeSpent": "6m",
          "originalEstimateSeconds": 600,
          "remainingEstimateSeconds": 200,
          "timeSpentSeconds": 400
        }
      }
    }
  ]
}

Get projects

GET /rest/agile/1.0/board/{boardId}/project

Returns all projects that are associated with the board, for the given board ID. 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.

A project is associated with a board if the board filter contains reference the project or there is an issue from the project that belongs to the board.

The board filter contains reference the project only if JQL query guarantees that returned issues will be returned from the project set defined in JQL. For instance the query project in (ABC, BCD) AND reporter = admin have reference to ABC and BCD projects but query project in (ABC, BCD) OR reporter = admin doesn't have reference to any project.

An issue belongs to the board if its status is mapped to the board's column. Epic issues do not belongs to the scrum boards.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains returned projects.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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

Format: int32

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/project' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the board's projects, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
  "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"
      },
      "simplified": false
    },
    {
      "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"
      },
      "simplified": false
    }
  ]
}

Get projects full

GET /rest/agile/1.0/board/{boardId}/project/full

Returns all projects that are statically associated with the board, for the given board ID. Returned projects are ordered by the name.

A project is associated with a board if the board filter contains reference the project.

The board filter contains reference the project only if JQL query guarantees that returned issues will be returned from the project set defined in JQL. For instance the query project in (ABC, BCD) AND reporter = admin have reference to ABC and BCD projects but query project in (ABC, BCD) OR reporter = admin doesn't have reference to any project.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains returned projects.

Format: int64

Example

Copy
1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/project/full' \
  --user 'email@example.com:<api_token>'

Responses

Returns the board's projects, at the specified page of the results.

A schema has not been defined for this response code.

Get board property keys

GET /rest/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.

App scope requiredREAD

Request

Path parameters
boardId Required

string

the ID of the board from which property keys will be returned.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/properties' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returned if the board with given id exists.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
{
  "keys": [
    {
      "self": "http://your-domain.atlassian.net/jira/rest/api/2/issue/EX-2/properties/issue.support",
      "key": "issue.support"
    }
  ]
}

Get board property

GET /rest/agile/1.0/board/{boardId}/properties/{propertyKey}

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.

App scope requiredREAD

Request

Path parameters
boardId Required

string

the ID of the board from which the property will be returned.

propertyKey Required

string

the key of the property to return.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returned if the board exists and the property was found.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
{
  "key": "issue.support",
  "value": {
    "stride.conversation.id": "b1bf38be-5e94-4b40-a3b8-9278735ee1e6",
    "support.time": "1m"
  }
}

Set board property

PUT /rest/agile/1.0/board/{boardId}/properties/{propertyKey}

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.

App scope requiredWRITE

Request

Path parameters
boardId Required

string

the ID of the board on which the property will be set.

propertyKey Required

string

the key of the board's property. The maximum length of the key is 255 bytes.

Example

Copy
1
2
3
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the board property is successfully updated.

A schema has not been defined for this response code.

Delete board property

DELETE /rest/agile/1.0/board/{boardId}/properties/{propertyKey}

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

App scope requiredDELETE

Request

Path parameters
boardId Required

string

the id of the board from which the property will be removed.

propertyKey Required

string

the key of the property to remove.

Example

Copy
1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the board property was removed successfully.

Get all quick filters

GET /rest/agile/1.0/board/{boardId}/quickfilter

Returns all quick filters from a board, for a given board ID.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested quick filters.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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

Format: int32

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/quickfilter' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested quick filters, at the specified page of the results. Quick filters will be ordered first by position.

Content typeValue
application/json

PageBeanQuickFilterBean

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "maxResults": 2,
  "startAt": 1,
  "total": 5,
  "isLast": false,
  "values": [
    {
      "id": 1,
      "boardId": 1,
      "name": "Bugs",
      "jql": "issueType = bug",
      "description": "Issues of type bug",
      "position": 0
    },
    {
      "id": 2,
      "boardId": 1,
      "name": "Tasks",
      "jql": "issueType = task",
      "description": "Issues of type task",
      "position": 0
    }
  ]
}

Get quick filter

GET /rest/agile/1.0/board/{boardId}/quickfilter/{quickFilterId}

Returns the quick filter for a given quick filter ID. The quick filter will only be returned if the user can view the board that the quick filter belongs to.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

Format: int64
quickFilterId Required

integer

The ID of the requested quick filter.

Format: int64

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/quickfilter/{quickFilterId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested quick filter.

Content typeValue
application/json

QuickFilterBean

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
{
  "id": 1,
  "boardId": 1,
  "name": "Bugs",
  "jql": "issueType = bug",
  "description": "Issues of type bug",
  "position": 0
}

Get reports for board

GET /rest/agile/1.0/board/{boardId}/reports

App scope requiredREAD

Request

Path parameters
boardId Required

integer

Format: int64

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/reports' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

200 response

Content typeValue
application/json

ReportsResponseBean

Get all sprints

GET /rest/agile/1.0/board/{boardId}/sprint

Returns all sprints from a board, for a given board ID. This only includes sprints that the user has permission to view.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested sprints.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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

Format: int32
state

string

Filters results to sprints in specified states. Valid values: future, active, closed. You can define multiple states separated by commas, e.g. state=active,closed

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/sprint' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

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.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "maxResults": 2,
  "startAt": 1,
  "total": 5,
  "isLast": false,
  "values": [
    {
      "id": 37,
      "self": "http://www.example.com/jira/rest/agile/1.0/sprint/23",
      "state": "closed",
      "name": "sprint 1",
      "startDate": "2015-04-11T15:22:00.000+10:00",
      "endDate": "2015-04-20T01:22:00.000+10:00",
      "completeDate": "2015-04-20T11:04:00.000+10:00",
      "originBoardId": 5,
      "goal": "sprint 1 goal"
    },
    {
      "id": 72,
      "self": "http://www.example.com/jira/rest/agile/1.0/sprint/73",
      "state": "future",
      "name": "sprint 2",
      "goal": "sprint 2 goal"
    }
  ]
}

Get issues for sprint

GET /rest/agile/1.0/board/{boardId}/sprint/{sprintId}/issue

Get all issues you have access to that belong to the sprint from the board. Issue returned from this resource contains additional fields like: sprint, closedSprints, flagged and epic. Issues are returned ordered by rank. JQL order has higher priority than default rank.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains requested issues.

Format: int64
sprintId Required

integer

The ID of the sprint that contains requested issues.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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.

Format: int32
jql

string

Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues.

validateQuery

boolean

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

fields

Array<string>

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

expand

string

A comma-separated list of the parameters to expand.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/sprint/{sprintId}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested issues, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
{
  "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",
          "goal": "sprint 2 goal"
        },
        "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",
            "goal": "sprint 1 goal"
          }
        ],
        "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"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://www.example.com/jira/rest/api/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "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": "2018-06-25T12:49:15.057+1000",
            "updated": "2018-06-25T12:49:15.057+1000",
            "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/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-06-25T12:49:15.118+1000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-06-25T12:49:15.118+1000",
            "timeSpent": "3h 20m",
            "timeSpentSeconds": 12000,
            "id": "100028",
            "issueId": "10002"
          }
        ],
        "updated": 1,
        "timetracking": {
          "originalEstimate": "10m",
          "remainingEstimate": "3m",
          "timeSpent": "6m",
          "originalEstimateSeconds": 600,
          "remainingEstimateSeconds": 200,
          "timeSpentSeconds": 400
        }
      }
    }
  ]
}

Get all versions

GET /rest/agile/1.0/board/{boardId}/version

Returns all versions from a board, for a given board ID. This only includes versions that the user has permission to view. Note, if the user does not have permission to view the board, no versions will be returned at all. Returned versions are ordered by the name of the project from which they belong and then by sequence defined by user.

App scope requiredREAD

Request

Path parameters
boardId Required

integer

The ID of the board that contains the requested versions.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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

Format: int32
released

string

Filters results to versions that are either released or unreleased. Valid values: true, false.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/board/{boardId}/version' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested versions, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "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
    }
  ]
}

Epic

Apis related to epics

Get issues without epic

GET /rest/agile/1.0/epic/none/issue

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.

App scope requiredREAD

Request

Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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.

Format: int32
jql

string

Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues.

validateQuery

boolean

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

fields

Array<string>

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

expand

string

A comma-separated list of the parameters to expand.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/epic/none/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested issues, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
{
  "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",
          "goal": "sprint 2 goal"
        },
        "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",
            "goal": "sprint 1 goal"
          }
        ],
        "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"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://www.example.com/jira/rest/api/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "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": "2018-06-25T12:49:15.057+1000",
            "updated": "2018-06-25T12:49:15.057+1000",
            "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/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-06-25T12:49:15.118+1000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-06-25T12:49:15.118+1000",
            "timeSpent": "3h 20m",
            "timeSpentSeconds": 12000,
            "id": "100028",
            "issueId": "10002"
          }
        ],
        "updated": 1,
        "timetracking": {
          "originalEstimate": "10m",
          "remainingEstimate": "3m",
          "timeSpent": "6m",
          "originalEstimateSeconds": 600,
          "remainingEstimateSeconds": 200,
          "timeSpentSeconds": 400
        }
      }
    }
  ]
}

Remove issues from epic

POST /rest/agile/1.0/epic/none/issue

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.

App scope requiredWRITE

Request

Body parameters
issues

Array<string>

Unique items: true

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/epic/none/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "issues": [
    "PR-1",
    "10001",
    "PR-3"
  ]
}'

Responses

Empty response is returned if operation was successful.

Get epic

GET /rest/agile/1.0/epic/{epicIdOrKey}

Returns the epic for a given epic ID. This epic will only be returned if the user has permission to view it.

App scope requiredREAD

Request

Path parameters
epicIdOrKey Required

string

The id or key of the requested epic.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/epic/{epicIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested epic.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
{
  "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
}

Partially update epic

POST /rest/agile/1.0/epic/{epicIdOrKey}

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.

App scope requiredWRITE

Request

Path parameters
epicIdOrKey Required

string

The id or key of the epic to update.

Body parameters
name

string

summary

string

color

ColorBean

done

boolean

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/epic/{epicIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "epic 2",
  "summary": "epic 2 summary",
  "color": {
    "key": "color_6"
  },
  "done": true
}'

Responses

Updated epic

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
{
  "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
}

Get issues for epic

GET /rest/agile/1.0/epic/{epicIdOrKey}/issue

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.

App scope requiredREAD

Request

Path parameters
epicIdOrKey Required

string

The id or key of the epic that contains the requested issues.

Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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.

Format: int32
jql

string

Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues.

validateQuery

boolean

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

fields

Array<string>

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

expand

string

A comma-separated list of the parameters to expand.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/epic/{epicIdOrKey}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested issues, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
{
  "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",
          "goal": "sprint 2 goal"
        },
        "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",
            "goal": "sprint 1 goal"
          }
        ],
        "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"
          },
          "simplified": false
        },
        "comment": [
          {
            "self": "http://www.example.com/jira/rest/api/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "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": "2018-06-25T12:49:15.057+1000",
            "updated": "2018-06-25T12:49:15.057+1000",
            "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/3.beta/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": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2018-06-25T12:49:15.118+1000",
            "visibility": {
              "type": "group",
              "value": "jira-developers"
            },
            "started": "2018-06-25T12:49:15.118+1000",
            "timeSpent": "3h 20m",
            "timeSpentSeconds": 12000,
            "id": "100028",
            "issueId": "10002"
          }
        ],
        "updated": 1,
        "timetracking": {
          "originalEstimate": "10m",
          "remainingEstimate": "3m",
          "timeSpent": "6m",
          "originalEstimateSeconds": 600,
          "remainingEstimateSeconds": 200,
          "timeSpentSeconds": 400
        }
      }
    }
  ]
}

Move issues to epic

POST /rest/agile/1.0/epic/{epicIdOrKey}/issue

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.

App scope requiredWRITE

Request

Path parameters
epicIdOrKey Required

string

The id or key of the epic that you want to assign issues to.

Body parameters
issues

Array<string>

Unique items: true

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/epic/{epicIdOrKey}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "issues": [
    "PR-1",
    "10001",
    "PR-3"
  ]
}'

Responses

Empty response is returned if operation was successful.

Rank epics

PUT /rest/agile/1.0/epic/{epicIdOrKey}/rank

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

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

App scope requiredWRITE

Request

Path parameters
epicIdOrKey Required

string

The id or key of the epic to rank.

Body parameters
rankBeforeEpic

string

rankAfterEpic

string

rankCustomFieldId

integer

Format: int64

Example

Copy
1
2
3
4
5
6
7
8
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/epic/{epicIdOrKey}/rank' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "rankBeforeEpic": "10000",
  "rankCustomFieldId": 10521
}'

Responses

Empty response is returned if operation was successful.

Issue

Apis related to issues

Rank issues

PUT /rest/agile/1.0/issue/rank

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

This operation may fail for some issues, although this will be rare. In that case the 207 status code is returned for the whole response and detailed information regarding each issue is available in the response body.

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

App scope requiredWRITE

Request

Body parameters
issues

Array<string>

rankBeforeIssue

string

rankAfterIssue

string

rankCustomFieldId

integer

Format: int64

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/issue/rank' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "issues": [
    "PR-1",
    "10001",
    "PR-3"
  ],
  "rankBeforeIssue": "PR-4",
  "rankCustomFieldId": 10521
}'

Responses

Empty response is returned if operation was successful.

Get issue

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

Returns a single issue, for a given issue ID or issue key. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic.

App scope requiredREAD

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the requested issue.

Query parameters
fields

Array<string>

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

expand

string

A comma-separated list of the parameters to expand.

updateHistory

boolean

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

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested issue.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
{
  "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",
      "goal": "sprint 2 goal"
    },
    "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",
        "goal": "sprint 1 goal"
      }
    ],
    "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"
      },
      "simplified": false
    },
    "comment": [
      {
        "self": "http://www.example.com/jira/rest/api/3.beta/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": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "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": "2018-06-25T12:49:15.057+1000",
        "updated": "2018-06-25T12:49:15.057+1000",
        "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/3.beta/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": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "I did some work here."
                }
              ]
            }
          ]
        },
        "updated": "2018-06-25T12:49:15.118+1000",
        "visibility": {
          "type": "group",
          "value": "jira-developers"
        },
        "started": "2018-06-25T12:49:15.118+1000",
        "timeSpent": "3h 20m",
        "timeSpentSeconds": 12000,
        "id": "100028",
        "issueId": "10002"
      }
    ],
    "updated": 1,
    "timetracking": {
      "originalEstimate": "10m",
      "remainingEstimate": "3m",
      "timeSpent": "6m",
      "originalEstimateSeconds": 600,
      "remainingEstimateSeconds": 200,
      "timeSpentSeconds": 400
    }
  }
}

Get issue estimation for board

GET /rest/agile/1.0/issue/{issueIdOrKey}/estimation

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.

App scope requiredREAD

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the requested issue.

Query parameters
boardId

integer

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

Format: int64

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/issue/{issueIdOrKey}/estimation' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the estimation of the issue and a fieldId of the field that is used for it.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
{
  "fieldId": "customfield_12532",
  "value": "8.0"
}

Estimate issue for board

PUT /rest/agile/1.0/issue/{issueIdOrKey}/estimation

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.

App scope requiredWRITE

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the requested issue.

Query parameters
boardId

integer

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

Format: int64
Body parameters
value

string

Example

Copy
1
2
3
4
5
6
7
8
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/issue/{issueIdOrKey}/estimation' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "value": "8.0"
}'

Responses

Returns the estimation of the issue and a fieldId of the field that is used for it.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
{
  "fieldId": "customfield_12532",
  "value": "8.0"
}

Sprint

Apis related to sprints

Create sprint

POST /rest/agile/1.0/sprint

Creates a future sprint. Sprint name and origin board id are required. Start date, end date, and goal are optional.

Note, the sprint name is trimmed.

App scope requiredWRITE

Request

Body parameters
name

string

startDate

string

endDate

string

originBoardId

integer

Format: int64
goal

string

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
12
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "sprint 1",
  "startDate": "2015-04-11T15:22:00.000+10:00",
  "endDate": "2015-04-20T01:22:00.000+10:00",
  "originBoardId": 5,
  "goal": "sprint 1 goal"
}'

Responses

Created sprint

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
{
  "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": "sprint 1 goal"
}

Get sprint

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

Returns the sprint for a given sprint ID. The sprint will only be returned if the user can view the board that the sprint was created on, or view at least one of the issues in the sprint.

App scope requiredREAD

Request

Path parameters
sprintId Required

integer

The ID of the requested sprint.

Format: int64

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested sprint.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
{
  "id": 37,
  "self": "http://www.example.com/jira/rest/agile/1.0/sprint/23",
  "state": "closed",
  "name": "sprint 1",
  "startDate": "2015-04-11T15:22:00.000+10:00",
  "endDate": "2015-04-20T01:22:00.000+10:00",
  "completeDate": "2015-04-20T11:04:00.000+10:00",
  "originBoardId": 5,
  "goal": "sprint 1 goal"
}

Update sprint

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

Performs a full update of a sprint. A full update means that the result will be exactly the same as the request body. Any fields not present in the request JSON will be set to null.

Notes:

  • Sprints that are in a closed state cannot be updated.
  • A sprint can be started by updating the state to 'active'. This requires the sprint to be in the 'future' state and have a startDate and endDate set.
  • A sprint can be completed by updating the state to 'closed'. This action requires the sprint to be in the 'active' state. This sets the completeDate to the time of the request.
  • Other changes to state are not allowed.
  • The completeDate field cannot be updated manually.

App scope requiredWRITE

Request

Path parameters
sprintId Required

integer

the ID of the sprint to update.

Format: int64
Body parameters
id

integer

Format: int64
self

string

Format: uri
state

string

name

string

startDate

string

endDate

string

completeDate

string

originBoardId

integer

Format: int64
goal

string

Example

Copy
1
2
3
4
5
6
7
8
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "new name"
}'

Responses

Updated sprint

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
{
  "id": 37,
  "self": "http://www.example.com/jira/rest/agile/1.0/sprint/23",
  "state": "closed",
  "name": "sprint 1",
  "startDate": "2015-04-11T15:22:00.000+10:00",
  "endDate": "2015-04-20T01:22:00.000+10:00",
  "completeDate": "2015-04-20T11:04:00.000+10:00",
  "originBoardId": 5,
  "goal": "sprint 1 goal"
}

Partially update sprint

POST /rest/agile/1.0/sprint/{sprintId}

Performs a partial update of a sprint. A partial update means that fields not present in the request JSON will not be updated.

Notes:

  • Sprints that are in a closed state cannot be updated.
  • A sprint can be started by updating the state to 'active'. This requires the sprint to be in the 'future' state and have a startDate and endDate set.
  • A sprint can be completed by updating the state to 'closed'. This action requires the sprint to be in the 'active' state. This sets the completeDate to the time of the request.
  • Other changes to state are not allowed.
  • The completeDate field cannot be updated manually.

App scope requiredWRITE

Request

Path parameters
sprintId Required

integer

The ID of the sprint to update.

Format: int64
Body parameters
id

integer

Format: int64
self

string

Format: uri
state

string

name

string

startDate

string

endDate

string

completeDate

string

originBoardId

integer

Format: int64
goal

string

Example

Copy
1
2
3
4
5
6
7
8
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "new name"
}'

Responses

Updated sprint

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
{
  "id": 37,
  "self": "http://www.example.com/jira/rest/agile/1.0/sprint/23",
  "state": "closed",
  "name": "sprint 1",
  "startDate": "2015-04-11T15:22:00.000+10:00",
  "endDate": "2015-04-20T01:22:00.000+10:00",
  "completeDate": "2015-04-20T11:04:00.000+10:00",
  "originBoardId": 5,
  "goal": "sprint 1 goal"
}

Delete sprint

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

Deletes a sprint. Once a sprint is deleted, all open issues in the sprint will be moved to the backlog.

App scope requiredDELETE

Request

Path parameters
sprintId Required

integer

The ID of the sprint to delete.

Format: int64

Example

Copy
1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the sprint was deleted successfully

Get issues for sprint

GET /rest/agile/1.0/sprint/{sprintId}/issue

Returns all issues in a sprint, for a given sprint ID. This only includes issues that the user has permission to view. By default, the returned issues are ordered by rank.

App scope requiredREAD

Request

Path parameters
sprintId Required

integer

The ID of the sprint that contains the requested issues.

Format: int64
Query parameters
startAt

integer

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

Format: int64
maxResults

integer

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.

Format: int32
jql

string

Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues.

validateQuery

boolean

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

fields

Array<string>

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

expand

string

A comma-separated list of the parameters to expand.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested issues, at the specified page of the results.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
{
  "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",
      "goal": "sprint 2 goal"
    },
    "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",
        "goal": "sprint 1 goal"
      }
    ],
    "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"
      },
      "simplified": false
    },
    "comment": [
      {
        "self": "http://www.example.com/jira/rest/api/3.beta/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": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "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": "2018-06-25T12:49:15.057+1000",
        "updated": "2018-06-25T12:49:15.057+1000",
        "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/3.beta/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": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "I did some work here."
                }
              ]
            }
          ]
        },
        "updated": "2018-06-25T12:49:15.118+1000",
        "visibility": {
          "type": "group",
          "value": "jira-developers"
        },
        "started": "2018-06-25T12:49:15.118+1000",
        "timeSpent": "3h 20m",
        "timeSpentSeconds": 12000,
        "id": "100028",
        "issueId": "10002"
      }
    ],
    "updated": 1,
    "timetracking": {
      "originalEstimate": "10m",
      "remainingEstimate": "3m",
      "timeSpent": "6m",
      "originalEstimateSeconds": 600,
      "remainingEstimateSeconds": 200,
      "timeSpentSeconds": 400
    }
  }
}

Move issues to sprint

POST /rest/agile/1.0/sprint/{sprintId}/issue

Moves issues to a sprint, for a given sprint ID. Issues can only be moved to open or active sprints. The maximum number of issues that can be moved in one operation is 50.

App scope requiredWRITE

Request

Path parameters
sprintId Required

integer

The ID of the sprint that you want to assign issues to.

Format: int64
Body parameters
issues

Array<string>

Unique items: true

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "issues": [
    "PR-1",
    "10001",
    "PR-3"
  ]
}'

Responses

Empty response is returned if operation was successful.

Get properties keys

GET /rest/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.

App scope requiredREAD

Request

Path parameters
sprintId Required

string

the ID of the sprint from which property keys will be returned.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/properties' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returned if the sprint with given id exists.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
{
  "keys": [
    {
      "self": "http://your-domain.atlassian.net/jira/rest/api/2/issue/EX-2/properties/issue.support",
      "key": "issue.support"
    }
  ]
}

Get property

GET /rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}

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.

App scope requiredREAD

Request

Path parameters
sprintId Required

string

the ID of the sprint from which the property will be returned.

propertyKey Required

string

the key of the property to return.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

Returned if the sprint exists and the property was found.

Content typeValue
application/json

anything

Example response (application/json)

Copy
1
2
3
4
5
6
7
{
  "key": "issue.support",
  "value": {
    "stride.conversation.id": "b1bf38be-5e94-4b40-a3b8-9278735ee1e6",
    "support.time": "1m"
  }
}

Set property

PUT /rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}

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.

App scope requiredWRITE

Request

Path parameters
sprintId Required

string

the ID of the sprint on which the property will be set.

propertyKey Required

string

the key of the sprint's property. The maximum length of the key is 255 bytes.

Example

Copy
1
2
3
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the sprint property is successfully updated.

A schema has not been defined for this response code.

Delete property

DELETE /rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}

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

App scope requiredDELETE

Request

Path parameters
sprintId Required

string

the ID of the sprint from which the property will be removed.

propertyKey Required

string

the key of the property to remove.

Example

Copy
1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}' \
  --user 'email@example.com:<api_token>'

Responses

Returned if the sprint property was removed successfully.

Swap sprint

POST /rest/agile/1.0/sprint/{sprintId}/swap

Swap the position of the sprint with the second sprint.

App scope requiredWRITE

Request

Path parameters
sprintId Required

integer

The ID of the sprint to swap.

Format: int64
Body parameters
sprintToSwapWith

integer

Format: int64

Example

Copy
1
2
3
4
5
6
7
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/agile/1.0/sprint/{sprintId}/swap' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sprintToSwapWith": 3
}'

Responses

Returned if the sprint swap was performed successfully

DevInfo

Apis related to development information

Store development information

POST /rest/devinfo/0.10/bulk

Stores development information provided in the request to make it available when viewing issues in JIRA. Existing repository and entity data for the same ID will be replaced if the updateSequenceId of existing data is less than the incoming data. Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are available within a short period of time, but may take some time during peak load and/or maintenance times.

App scope requiredWRITE

Request

Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Body parameters

Request object for development information push operations, entities are grouped by repository

repositories Required

Array<Repository>

List of repositories containing development information. Must not contain duplicates. Maximum number of entities across all repositories is 1000

Max items: 100
preventTransitions

boolean

Flag to prevent automatic issue transitions and smart commits being fired, default is false

properties

object

Arbitrary properties to tag the submitted repositories with. These properties can be used for delete operations to e.g. clean up all development information associated with an account in the event that the account is removed from the provider system. Note that these properties will never be returned with repository or entity data. They are not intended for use as metadata to associate with a repository. Maximum length of each key or value is 255 characters. Maximum allowed number of properties key/value pairs is 5. Properties keys cannot start with '_' character. Properties keys cannot contain ':' character.

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/bulk' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "repositories": [
    {
      "name": "atlassian-connect-jira-example",
      "description": "The repository which stores code of the Atlassian Connect Add-on Devinfo application.",
      "forkOf": "56c7c750-cee2-48e2-b920-d7706dfd11f7",
      "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example",
      "commits": [
        {
          "id": "c6c7c750-cee2-48e2-b920-d7706dfd11f9",
          "issueKeys": [
            "<string>"
          ],
          "updateSequenceId": 1523494301248,
          "hash": "a7727ee6350c33cdf90826dc21abaa26a5704370",
          "message": "README.md edited online with Bitbucket",
          "author": {
            "name": "Jane Doe"
          },
          "fileCount": 1,
          "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/commits/a7727ee6350c33cdf90826dc21abaa26a5704370",
          "authorTimestamp": "2016-10-31T23:27:25+00:00",
          "displayId": "a7727ee"
        }
      ],
      "branches": [
        {
          "id": "c6c7c750-cee2-48e2-b920-d7706dfd11f9",
          "issueKeys": [
            "<string>"
          ],
          "updateSequenceId": 1523494301248,
          "name": "master",
          "lastCommit": {
            "id": "c6c7c750-cee2-48e2-b920-d7706dfd11f9",
            "issueKeys": [
              "<string>"
            ],
            "updateSequenceId": 1523494301248,
            "hash": "a7727ee6350c33cdf90826dc21abaa26a5704370",
            "message": "README.md edited online with Bitbucket",
            "author": {
              "name": "Jane Doe"
            },
            "fileCount": 1,
            "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/commits/a7727ee6350c33cdf90826dc21abaa26a5704370",
            "authorTimestamp": "2016-10-31T23:27:25+00:00",
            "displayId": "a7727ee"
          },
          "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/branch/master"
        }
      ],
      "pullRequests": [
        {
          "id": "c6c7c750-cee2-48e2-b920-d7706dfd11f9",
          "issueKeys": [
            "<string>"
          ],
          "updateSequenceId": 1523494301248,
          "status": "OPEN",
          "title": "Pull request 2, fixing all the issues caused by pull request #1",
          "author": {
            "name": "Jane Doe"
          },
          "commentCount": 42,
          "sourceBranch": "ISSUE-1-feature-branch",
          "lastUpdate": "2016-10-31T23:27:25+00:00",
          "url": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/pull-requests/2",
          "displayId": "Pull request 2"
        }
      ],
      "avatar": "http://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/avatar/32",
      "avatarDescription": "Avatar description",
      "id": "c6c7c750-cee2-48e2-b920-d7706dfd11f9",
      "updateSequenceId": 1523494301248
    }
  ],
  "preventTransitions": true,
  "properties": {}
}'

Responses

Submission accepted. Each submitted repository and entity that is of a valid format will be eventually available in Jira.

Content typeValue
application/json

StoreDevinfoResult

Get repository

GET /rest/devinfo/0.10/repository/{repositoryId}

For the specified repository ID, retrieves the repository and the most recent 400 development information entities. The result will be what is currently stored, ignoring any pending updates or deletes.

App scope requiredREAD

Request

Path parameters
repositoryId Required

string

The ID of repository to fetch

Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/repository/{repositoryId}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

Responses

The repository data currently stored for the given ID.

Content typeValue
application/json

Repository

Delete repository

DELETE /rest/devinfo/0.10/repository/{repositoryId}

Deletes the repository data stored by the given ID and all related development information entities. Deletion is performed asynchronously.

App scope requiredDELETE

Request

Path parameters
repositoryId Required

string

The ID of repository to delete

Query parameters
_updateSequenceId

integer

An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together.

Format: int64
Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Example

Copy
1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/repository/{repositoryId}' \
  --user 'email@example.com:<api_token>'

Responses

Delete request has been accepted. Data will eventually be removed from Jira if it exists.

A schema has not been defined for this response code.

Delete development information by properties

DELETE /rest/devinfo/0.10/bulkByProperties

Deletes development information entities which have all the provided properties. Entities will be deleted that match ALL of the properties (i.e. treated as an AND). For example if request is DELETE bulk?accountId=123&projectId=ABC entities which have properties accountId=123 and projectId=ABC will be deleted. Special property '_updateSequenceId' can be used to delete all entities with updateSequenceId less or equal than the value specified. In addition to the optional '_updateSequenceId', one or more query params must be supplied to specify properties to delete by. Deletion is performed asynchronously: specified entities will eventually be removed from Jira.

App scope requiredDELETE

Request

Query parameters
_updateSequenceId

integer

An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together.

Format: int64
Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Example

Copy
1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/bulkByProperties' \
  --user 'email@example.com:<api_token>'

Responses

Delete accepted. Data will eventually be removed from Jira.

A schema has not been defined for this response code.

Delete development information entity

DELETE /rest/devinfo/0.10/repository/{repositoryId}/{entityType}/{entityId}

Deletes particular development information entity. Deletion is performed asynchronously.

App scope requiredDELETE

Request

Path parameters
repositoryId Required

string

entityType Required

string

Valid values: commit, branch, pull_request

entityId Required

string

Query parameters
_updateSequenceId

integer

An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together.

Format: int64
Header parameters
Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.

Example

Copy
1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/devinfo/0.10/repository/{repositoryId}/{entityType}/{entityId}' \
  --user 'email@example.com:<api_token>'

Responses

Delete request has been accepted. Data will eventually be removed from Jira if it exists.

A schema has not been defined for this response code.