JIRA Developer Documentation : Updating an Issue via the JIRA REST APIs

Available:

JIRA 5.0 and later.

This page describes the JIRA REST API for updating an issue. For the related tutorial, see JIRA REST API Example - Edit issues.

Simple update (implicit set via "fields")

The simple way to update an issue is to do a GET, update the values inside "fields", and then PUT back.

If you PUT back exactly what you GOT, then you are also sending "names", "self", "key", etc. These are ignored.
You do not need to send all the fields inside "fields". You can just send the fields you want to update. Absent fields are left unchanged. For example, to update the summary:
```
1
2
{ "fields": {"summary": "new summary"} }
```
Some fields cannot be updated this way (for example, comments). Instead you must use explicit-verb updates (see below). You can tell if a field cannot be implicitly set by the fact it doesn't have a SET verb.
If you do send along such un-SET-able fields in this manner, they are ignored. This means that you can PUT what you GET, but not all of the document is taken into consideration.

Operation (verb) based update (explicit verb via "update")

Each field supports a set of operations (verbs) for mutating the field. You can retrieve the editable fields and the operations they support using the "editmeta" resource. For example:

1
2
http://MYJIRA.INSTALL.COM:8080/rest/api/2/issue/ISSUE-KEY/editmeta

The basic operations are defined below (but custom fields can define their own).

The general shape of an update is field, array of verb-value pairs. For example:

1
2
{ "update": {
    "field1": [ {"verb": value}, {"verb": value}, ...],
    "field2": [ {"verb": value}, {"verb": value}, ...],
}}

SET: Sets the value of the field. The incoming value must be the same shape as the value of the field from a GET. For example, a string for "summary", and array of strings for "labels".
CLEAR:

We don't need CLEAR, it's the same as SET: [].

ADD: Adds an element to a field that is an array. The incoming value must be the same shape as the items of the array in a GET. For example, to add a label:

1
2
{ "update": { "labels": [ {"add": "newlabel"} ] } }

REMOVE: Removes an element from a field that is an array. The incoming value must be the same shape as the items of the array in a GET (although you can remove parts of the object that are not needed to uniquely identify the object).

remove a label:

1
2
{ "update": { "labels": [{"remove": "test" }] } }

remove a comment (by comment id):

1
2
{ "update": { "comments": [{"remove": {"id": 10001} }] } }

EDIT: Edits an element in a field that is an array. The element is indexed/identified by the value itself (usually by id/name/key).

edit the text of a particular comment:

1
2
{ "update": { "comments": [{"edit": {"id": 10002, "body": "newbody"} } ] } }

Fields available with verb operations (work in progress)

Field	Verb	Field Value
Assignee	Set	User Id
Comment	Add	Json object - (look at an issue to get the shape)
Components	Set, Add	Component Id or Name
Description	Set	String
Fix Versions	Set, Add, Remove	Version Id or Name
Labels	Set, Add, Remove	Label name
Priority	Set	Priority Id or Name
Summary	Set	String
Affected Versions	Set, Add, Remove	Version Id or Name
Worklog	Add	Json object - (look at an issue to get the shape)

Combining implicit and explicit updates

You can have both "fields" and "update" in the one PUT, but a given field must appear only in one or the other.

Validation and errors

If any of the implicit or explicit updates cause a validation error, an error document is returned, detailing the validation errors associated with each field.

JIRA REST API Example - Edit issues