Versions Compared

Old Version 51

changes.mady.by.user Howard Nedd [AgileVisor]

Saved on

compared with

New Version Current

changes.mady.by.user Howard Nedd [AgileVisor]

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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
titleCreate an issue or sub-task from json

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

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"

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
titleCreate an issue or sub-task from json - bulk operation

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

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


Expand
titleDelete an issue

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

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}"

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

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

print(response.text)


Expand
titleArchive 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
titleAssign 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
titleAdd 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 typeValueRestrictions
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
titleGet 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
titleAdd 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
titleUpdate 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
languagepython
# 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
titleDelete 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
languagepython
# 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
titleGet 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
languagepython
# 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
titleGet 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
languagepython
# 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
titlePerform 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
languagepython
# 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
titleAdd 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
languagepython
# 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
titleRemove 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
languagepython
# 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
titleGet 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
languagepython
# 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
titleGet 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
languagepython
# 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
titleDelete 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
languagepython
# 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
titleGet 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
languagepython
# 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=(",", ": ")))


...