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:

    { "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:

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:

{ "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: (warning) 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:

    { "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:

      { "update": { "labels": [{"remove": "test" }] } }
      
    • remove a comment (by comment id):

      { "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:

      { "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.

RELATED TOPICS

JIRA REST API Example - Edit issues

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport