Jira API Documentation

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.

Request

Body parameters

issues

Array<string>

Unique items: TRUE

Example

curl --request POST \
  --url 'http://{baseurl}/rest/agile/1.0/backlog/issue' \
  --user 'email@example.com:<api_token>' \
  --header 'Content-Type: application/json'

// This code sample uses the 'node-fetch' library:
// https://www.npmjs.com/package/node-fetch
const fetch = require('node-fetch');

fetch('http://{baseurl}/rest/agile/1.0/backlog/issue', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${Buffer.from(
      'email@example.com:<api_token>'
    ).toString('base64')}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => {
    console.log(
      `Response: ${response.status} ${response.statusText}`
    );
    return response.text();
  })
  .then(text => console.log(text))
  .catch(err => console.error(err));

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth

url = "http://{baseurl}/rest/agile/1.0/backlog/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Content-Type": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(response.text)

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.

Request

Query parameters

expand

string

jql

string

maxResults

integer
Format: int32

validateQuery

boolean

fields

Array<StringList>

startAt

integer
Format: int64

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/epic/none/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

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.

Request

Body parameters

issues

Array<string>

Unique items: true

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth

url = "http://{baseurl}/rest/agile/1.0/epic/none/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Content-Type": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(response.text)

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.

Request

Path parameters

epicIdOrKey Required

string

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/epic/{epicIdOrKey}"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

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.

Request

Path parameters

epicIdOrKey Required

string

Body parameters

color

ColorBean

done

boolean

name

string

summary

string

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/epic/{epicIdOrKey}"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json",
  "Content-Type": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

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.

Request

Path parameters

epicIdOrKey Required

string

Query parameters

expand

string

jql

string

maxResults

integer
Format: int32

validateQuery

boolean

fields

Array<StringList>

startAt

integer
Format: int64

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth

url = "http://{baseurl}/rest/agile/1.0/epic/{epicIdOrKey}/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
"Content-Type": "application/json"
}

response = requests.request(
"POST",
url,
headers=headers,
auth=auth
)

print(response.text)

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.

Request

Path parameters

epicIdOrKey Required

string

Body parameters

issues

Array<string>

Unique items: true

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth

url = "http://{baseurl}/rest/agile/1.0/epic/{epicIdOrKey}/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Content-Type": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(response.text)

POST /rest/api/2/issue

Creates an issue or a sub-task from a JSON representation. The fields that can be set on create, in either the fields parameter or the update parameter can be determined using the /rest/api/2/issue/createmeta resource. If a field is not configured to appear on the create screen, then it will not be in the createmeta, and a field validation error will occur if it is submitted. Creating a sub-task is similar to creating a regular issue, with two important differences:

• the issueType field must correspond to a sub-task issue type (you can use /issue/createmeta to discover sub-task issue types), and
• you must provide a parent field in the issue create request containing the id or key of the parent issue. The updateHistory param adds the project that this issue is created in, to the current user's project history, if set to true (by default, the project history is not updated). You can view the project history in the Jira application, via the Projects dropdown.

Request

Query parameters

updateHistory

boolean
Default: false

Body parameters

fields

object

historyMetadata

HistoryMetadata

properties

Array<EntityPropertyBean>

transition

TransitionBean

update

object

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/api/2/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json",
  "Content-Type": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

POST /rest/api/2/issue/bulk

Creates issues or sub-tasks from a JSON representation. Creates many issues in one bulk operation. Creating a sub-task is similar to creating a regular issue. More details can be found in createIssue section.

Request

Body parameters

issueUpdates

Array<IssueUpdateBean>

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/api/2/issue/bulk"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json",
  "Content-Type": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

DELETE /rest/api/2/issue/{issueIdOrKey}

Deletes an issue. If the issue has subtasks you must set the parameter deleteSubtasks=true to delete the issue. You cannot delete an issue without its subtasks also being deleted.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

Query parameters

deleteSubtasks

string

A String of true or false indicating that any subtasks should also be deleted. If the issue has no subtasks this parameter is ignored. If the issue has subtasks and this parameter is missing or false, then the issue will not be deleted and an error will be returned.

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth

url = "http://{baseurl}/rest/api/2/issue/{issueIdOrKey}"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

response = requests.request(
   "DELETE",
   url,
   auth=auth
)

print(response.text)

PUT /rest/api/2/issue/{issueIdOrKey}/archive

Archives an issue.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

Query parameters

notifyUsers

string

Send the email with notification that the issue was updated to users that watch it. Admin or project admin permissions are required to disable the notification.

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth

url = "http://{baseurl}/rest/api/2/issue/{issueIdOrKey}/archive"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

response = requests.request(
   "PUT",
   url,
   auth=auth
)

print(response.text)

PUT /rest/api/2/issue/{issueIdOrKey}/assignee

Assign an issue to a user.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

Body parameters

active

boolean

applicationRoles

SimpleListWrapperApplicationRoleBean

avatarUrls

object

deleted

boolean

displayName

string

emailAddress

string

expand

string

groups

SimpleListWrapperGroupJsonBean

key

string

lastLoginTime

string

locale

string

name

string

self

string

Format: uri

timeZone

string

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth

url = "http://{baseurl}/rest/api/2/issue/{issueIdOrKey}/assignee"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Content-Type": "application/json"
}

response = requests.request(
   "PUT",
   url,
   headers=headers,
   auth=auth
)

print(response.text)

POST /rest/api/2/issue/{issueIdOrKey}/attachments

Add one or more attachments to an issue. This resource expects a multipart post. The media-type multipart/form-data is defined in RFC 1867. Most client libraries have classes that make dealing with multipart posts simple. For instance, in Java the Apache HTTP Components library provides a MultiPartEntity that makes it simple to submit a multipart POST. In order to protect against XSRF attacks, because this method accepts multipart/form-data, it has XSRF protection on it. This means you must submit a header of X-Atlassian-Token: no-check with the request, otherwise it will be blocked. The name of the multipart/form-data parameter that contains attachments must be file. A simple example to upload a file called "myfile.txt" to issue TEST-123: curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: no-check" -F "file=@myfile.txt" http://myhost/rest/api/2/issue/TEST-123/attachments

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

Body parameters

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/api/2/issue/{issueIdOrKey}/attachments"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

GET /rest/api/2/issue/{issueIdOrKey}/comment

Returns all comments for an issue. Results can be ordered by the 'created' field which means the date a comment was added.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

Query parameters

expand

string

Optional flags: renderedBody (provides body rendered in HTML)

maxResults

string

How many results on the page should be included. Defaults to 50.

orderBy

string

Ordering of the results

startAt

string

The page offset, if not specified then defaults to 0

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/api/2/issue/{issueIdOrKey}/comment"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

POST /rest/api/2/issue/{issueIdOrKey}/comment

Adds a new comment to an issue.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

Query parameters

expand

string

Optional flags: renderedBody (provides body rendered in HTML)

Body parameters

author

UserJsonBean

body

string

created

string

id

string

properties

Array<EntityPropertyBean>

renderedBody

string

self

string

updateAuthor

UserJsonBean

updated

string

visibility

VisibilityJsonBean

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/api/2/issue/{issueIdOrKey}/comment"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json",
  "Content-Type": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

PUT /rest/api/2/issue/{issueIdOrKey}/comment/{id}

Updates an existing comment using its JSON representation.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

id Required

string

Comment id

Query parameters

expand

string

Optional flags: renderedBody (provides body rendered in HTML)

Body parameters

author

UserJsonBean

body

string

created

string

id

string

properties

Array<EntityPropertyBean>

renderedBody

string

self

string

updateAuthor

UserJsonBean

updated

string

visibility

VisibilityJsonBean

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/api/2/issue/{issueIdOrKey}/comment/{id}"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json",
  "Content-Type": "application/json"
}

response = requests.request(
   "PUT",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

ELETE /rest/api/2/issue/{issueIdOrKey}/comment/{id}

Deletes an existing comment.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

id Required

string

Comment id

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth

url = "http://{baseurl}/rest/api/2/issue/{issueIdOrKey}/comment/{id}"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

response = requests.request(
   "DELETE",
   url,
   auth=auth
)

print(response.text)

GET /rest/api/2/issue/{issueIdOrKey}/subtask

Returns an issue's subtask list

Request

Path parameters

issueIdOrKey Required

string

The parent issue's key or id

Example

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/api/2/issue/{issueIdOrKey}/subtask"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))