Page History

...

Info
This documentation refers to Jira Data Center only. This page contains the basic examples. To get all options please navigate to: https://developer.atlassian.com/server/jira/platform/rest/v10004/intro/#gettingstarted

Jira REST APIs

Jira has REST APIs and Java APis that you can use to interact with Jira. For example, you may want to integrate your existing application with Jira or write a script to get information from Jira. For more information, check out our reference documentation:

...

Expand

title	Archive an issue

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

Code Block

# 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)

Expand

title	Assign an issue to a user

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

Code Block

# 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)

Expand

title	Add one or more attachments to an issue

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

Content type	Value	Restrictions
multipart/form-data	string	Format: `binary`

Example

Code Block

# 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=(",", ": ")))

Expand

title	Get comments for an issue

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

Code Block

# 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=(",", ": ")))

Expand

title	Add a comment

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

Code Block

# 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=(",", ": ")))

Expand

title	Update a comment

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

Code Block

language	python

# 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=(",", ": ")))

Expand

title	Delete a comment

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

Code Block

language	python

# 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)

Expand

title	Get an issue's subtask list

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

Code Block

language	python

# 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=(",", ": ")))

Expand

title	Get list of transitions possible for an issue

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

Get a list of the transitions possible for this issue by the current user, along with fields that are required and their types. Fields will only be returned if expand=transitions.fields. The fields in the metadata correspond to the fields in the transition screen for that transition. Fields not in the screen will not be in the metadata.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

Query parameters

transitionId

string

Transition id

Example

Code Block

language	python

# 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}/transitions"

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=(",", ": ")))

Expand

title	Perform a transition on an issue

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

Perform a transition on an issue. When performing the transition you can update or set other issue fields. The fields that can be set on transition, in either the fields parameter or the update parameter can be determined using the /rest/api/2/issue/{issueIdOrKey}/transitions?expand=transitions.fields resource. If a field is not configured to appear on the transition screen, then it will not be in the transition metadata, and a field validation error will occur if it is submitted. The updateHistory param adds the issues retrieved by this method to the current user's issue history, if set to true (by default, the issue history does not include issues retrieved via the REST API). You can view the issue history in the Jira application, via the Issues dropdown or by using the lastViewed JQL field in an issue search.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

Body parameters

fields

object

historyMetadata

HistoryMetadata

properties

Array<EntityPropertyBean>

transition

TransitionBean

update

object

Example

Code Block

language	python

# 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}/transitions"

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

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

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

print(response.text)

Expand

title	Add vote to issue

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

Adds voter (currently logged user) to particular ticket. You need to be logged in to use this method.

Request

Path parameters

issueIdOrKey Required

string

Issue id.

Example

Code Block

language	python

# 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}/votes"

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

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

print(response.text)

Expand

title	Remove vote from issue

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

Remove your vote from an issue.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

Example

Code Block

language	python

# 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}/votes"

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

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

print(response.text)

Expand

title	Get worklogs for an issue

ET /rest/api/2/issue/{issueIdOrKey}/worklog

Returns all work logs for an issue. Work logs won't be returned if the Log work field is hidden for the project.

Request

Path parameters

issueIdOrKey Required

string

Issue id or key

Example

Code Block

language	python

# 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}/worklog"

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=(",", ": ")))

...

Custom Fields

Expand

title	Get custom fields with pagination

GET /rest/api/2/customFields

Returns a list of Custom Fields in the given range.

Request

Query parameters

sortColumn

string

The column by which to sort the returned custom fields.

types

string

A list of custom field types to filter the custom fields.

search

string

A query string used to search custom fields.

maxResults

string

The maximum number of custom fields to return.

sortOrder

string

The order in which to sort the returned custom fields.

screenIds

string

A list of screen IDs to filter the custom fields.

lastValueUpdate

string

The last value update to filter the custom fields.

projectIds

string

A list of project IDs to filter the custom fields.

startAt

string

The starting index of the returned custom fields.

Example

Code Block

language	python

# 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/customFields"

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=(",", ": ")))

Expand

title	Delete custom fields in bulk

DELETE /rest/api/2/customFields

Deletes custom fields in bulk.

Request

Query parameters

ids Required

string

A list of custom field IDs to delete.

Example

Code Block

language	python

# 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/customFields"

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

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

query = {
  'ids': '{ids}'
}

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

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

Expand

title	Get custom field options

Experimental

GET /rest/api/2/customFields/{customFieldId}/options

Returns custom field's options defined in a given context composed of projects and issue types.

Request

Path parameters

customFieldId Required

string

The ID of the custom field.

Query parameters

maxResults

string

The maximum number of results to return.

issueTypeIds

string

A list of issue type IDs in a context.

query

string

A string used to filter options.

sortByOptionName

string

Flag to sort options by their names.

useAllContexts

string

Flag to fetch all options regardless of context, project IDs, or issue type IDs.

page

string

The page of options to return.

projectIds

string

A list of project IDs in a context.

Example

Code Block

language	python

# 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/customFields/{customFieldId}/options"

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=(",", ": ")))

...

Jira architecture

Atlassian's architecture documentation will help you understand Jira fundamentals and get a high-level perspective of Jira's dependencies.

...

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 54

New Version Current

Key

Jira REST APIs

Request

Path parameters

Query parameters

Example

Request

Path parameters

Body parameters

Example

Request

Path parameters

Body parameters

Example

Request

Path parameters

Query parameters

Example

Request

Path parameters

Query parameters

Body parameters

Example

Request

Path parameters

Query parameters

Body parameters

Example

Request

Path parameters

Example

Request

Path parameters

Example

Request

Path parameters

Query parameters

Example

Request

Path parameters

Body parameters

Example

Request

Path parameters

Example

Request

Path parameters

Example

Request

Path parameters

Example

Custom Fields

Request

Query parameters

Example

Request

Query parameters

Example

Request

Path parameters

Query parameters

Example

Jira architecture