Backlog
Board
Epic
Issue
Sprint
Development Information
Feature Flags
Deployments
Builds
Remote Links
Security Information
Other operations

Rate this page:

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 that the sprint name is trimmed. Also, when starting sprints from the UI, the "endDate" set through this call is ignored and instead the last sprint's duration is used to fill the form.

Connect app scope requiredWRITE

write:sprint:jira-software

Request

Body parameters
name

string

startDate

string

endDate

string

originBoardId

integer

Format: int64
goal

string

Example

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

Responses

Created sprint

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
{
  "id": 37,
  "self": "https://your-domain.atlassian.net/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.

Connect app scope requiredREAD

read:sprint:jira-software

Request

Path parameters
sprintId Required

integer

The ID of the requested sprint.

Format: int64

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.com/rest/agile/1.0/sprint/{sprintId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested sprint.

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
{
  "id": 37,
  "self": "https://your-domain.atlassian.net/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.

Connect app scope requiredWRITE

write:sprint:jira-software

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

createdDate

string

originBoardId

integer

Format: int64
goal

string

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request PUT \
  --url 'https://your-domain.atlassian.com/rest/agile/1.0/sprint/{sprintId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "goal": "sprint 1 goal",
  "endDate": "2015-04-16T14:01:00.000+10:00",
  "name": "sprint 1",
  "state": "closed",
  "startDate": "2015-04-11T15:36:00.000+10:00",
  "completeDate": "2015-04-20T11:11:28.008+10:00"
}'

Responses

Updated sprint

Content typeValue
application/json

anything

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
{
  "id": 37,
  "self": "https://your-domain.atlassian.net/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.

Connect app scope requiredWRITE

write:sprint:jira-software

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

createdDate

string

originBoardId

integer

Format: int64
goal

string

Example

1
2
3
4
5
6
7
8
curl --request POST \
  --url 'https://your-domain.atlassian.com/rest/agile/1.0/sprint/{sprintId}' \
  --header 'Authorization: Bearer <access_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)

1
2
3
4
5
6
7
8
9
10
11
{
  "id": 37,
  "self": "https://your-domain.atlassian.net/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.

Connect app scope requiredDELETE

delete:sprint:jira-software

Request

Path parameters
sprintId Required

integer

The ID of the sprint to delete.

Format: int64

Example

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.com/rest/agile/1.0/sprint/{sprintId}' \
  --header 'Authorization: Bearer <access_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.

Connect app scope requiredREAD

read:sprint:jira-software
, read:issue-details:jira, read:jql:jira

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. 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.
Note that username and userkey can't be used as search terms for this parameter due to privacy reasons. Use accountId instead.

validateQuery

boolean

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

fields

Array<object>

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

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.com/rest/agile/1.0/sprint/{sprintId}/issue' \
  --header 'Authorization: Bearer <access_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)

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
{
  "expand": "",
  "id": "10001",
  "self": "https://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001",
  "key": "HSP-1",
  "fields": {
    "flagged": true,
    "sprint": {
      "id": 37,
      "self": "https://your-domain.atlassian.net/rest/agile/1.0/sprint/13",
      "state": "future",
      "name": "sprint 2",
      "goal": "sprint 2 goal"
    },
    "closedSprints": [
      {
        "id": 37,
        "self": "https://your-domain.atlassian.net/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": "https://your-domain.atlassian.net/rest/api/3/project/EX",
      "id": "10000",
      "key": "EX",
      "name": "Example",
      "avatarUrls": {
        "48x48": "https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
        "24x24": "https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
        "16x16": "https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
        "32x32": "https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
      },
      "projectCategory": {
        "self": "https://your-domain.atlassian.net/rest/api/3/projectCategory/10000",
        "id": "10000",
        "name": "FIRST",
        "description": "First Project Category"
      },
      "simplified": false,
      "style": "classic",
      "insight": {
        "totalIssueCount": 100,
        "lastIssueUpdateTime": "2022-11-15T23:15:20.052+0000"
      }
    },
    "comment": [
      {
        "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000",
        "id": "10000",
        "author": {
          "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
          "accountId": "5b10a2844c20165700ede21g",
          "displayName": "Mia Krystof",
          "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": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
          "accountId": "5b10a2844c20165700ede21g",
          "displayName": "Mia Krystof",
          "active": false
        },
        "created": "2021-01-17T12:34:00.000+0000",
        "updated": "2021-01-18T23:45:00.000+0000",
        "visibility": {
          "type": "role",
          "value": "Administrators",
          "identifier": "Administrators"
        }
      }
    ],
    "epic": {
      "id": 37,
      "self": "https://your-domain.atlassian.net/rest/agile/1.0/epic/23",
      "name": "epic 1",
      "summary": "epic 1 summary",
      "color": {
        "key": "color_4"
      },
      "done": true
    },
    "worklog": [
      {
        "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000",
        "author": {
          "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
          "accountId": "5b10a2844c20165700ede21g",
          "displayName": "Mia Krystof",
          "active": false
        },
        "updateAuthor": {
          "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
          "accountId": "5b10a2844c20165700ede21g",
          "displayName": "Mia Krystof",
          "active": false
        },
        "comment": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "I did some work here."
                }
              ]
            }
          ]
        },
        "updated": "2021-01-18T23:45:00.000+0000",
        "visibility": {
          "type": "group",
          "value": "jira-developers",
          "identifier": "276f955c-63d7-42c8-9520-92d01dca0625"
        },
        "started": "2021-01-17T12:34:00.000+0000",
        "timeSpent": "3h 20m",
        "timeSpentSeconds": 12000,
        "id": "100028",
        "issueId": "10002"
      }
    ],
    "updated": 1,
    "timetracking": {
      "originalEstimate": "10m",
      "remainingEstimate": "3m",
      "timeSpent": "6m",
      "originalEstimateSeconds": 600,
      "remainingEstimateSeconds": 200,
      "timeSpentSeconds": 400
    }
  }
}

Move issues to sprint and rank

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.

Connect app scope requiredWRITE

write:sprint:jira-software

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>

rankBeforeIssue

string

rankAfterIssue

string

rankCustomFieldId

integer

Format: int64

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request POST \
  --url 'https://your-domain.atlassian.com/rest/agile/1.0/sprint/{sprintId}/issue' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "rankBeforeIssue": "PR-4",
  "rankCustomFieldId": 10521,
  "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.

Connect app scope requiredREAD

read:sprint:jira-software

Request

Path parameters
sprintId Required

string

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

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.com/rest/agile/1.0/sprint/{sprintId}/properties' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returned if the sprint with given id exists.

Content typeValue
application/json

anything

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.

Connect app scope requiredREAD

read:sprint:jira-software

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

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.com/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returned if the sprint exists and the property was found.

Content typeValue
application/json

anything

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.

Connect app scope requiredWRITE

write:sprint:jira-software

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

1
2
3
curl --request PUT \
  --url 'https://your-domain.atlassian.com/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}' \
  --header 'Authorization: Bearer <access_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.

Connect app scope requiredDELETE

delete:sprint:jira-software

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

1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.com/rest/agile/1.0/sprint/{sprintId}/properties/{propertyKey}' \
  --header 'Authorization: Bearer <access_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.

Connect app scope requiredWRITE

write:sprint:jira-software

Request

Path parameters
sprintId Required

integer

The ID of the sprint to swap.

Format: int64
Body parameters
sprintToSwapWith

integer

Format: int64

Example

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

Responses

Returned if the sprint swap was performed successfully

Rate this page: