Checklist API

Introduction

You can use the Jira REST API to interact with the Issue Checklist. This page documents the REST resources available to use, including example requests and responses. Use this API to build script interactions with your checklist, or develop any other type of integration.

This guide applies to Jira REST API version 2 calls only. While the latest Jira REST API version is 3, it is still in beta and doesn't work with the Issue Checklist. 

This guide applies to Jira Company-managed (Classic) projects only. Team-managed (Next-Gen) projects do not support global custom fields, which are required for checklist REST API access.

Note that you can access checklist data stored in custom fields even if the Issue Checklist app has been uninstalled. 

Requirements

  • To use Issue Checklists with the API, the Save checklist data to Jira custom fields global setting must be enabled.

  • To update or remove an existing checklist via the API, the Checklist Text custom field must be present on the Edit issue screen. Follow these instructions for adding a custom field to a screen.

  • No configuration are required for reading a checklist, or checklist metadata via the API.


Authentication

Following guide is based on basic-authentication which means that all calls will impersonate the user. The user must have view issue and edit issue permissions. A valid API Token for the user’s Atlassian account is also required.

 

In the examples below, you will need to replace the following items:

Item

Replace with

Example

Item

Replace with

Example

email@example.com 

The email address provided in your Atlassian ID account

stefan@herocoders.com

<api_token>

A valid API token for your Atlassian ID

J3D4smrVz29cxzsd

https://your-domain.atlassian.net

The URL of your Jira Cloud instance

https://herocoders.atlassian.net

{issueIdOrKey}

The relevant issue key

DEMO-1

"customfield_10034"

The ID of the Checklist Text custom field in your instance. Follow these instructions for getting the custom field ID.

"customfield_10058"

 


Get, Update or Remove Checklist

You will need to replace the custom field ID with the ID of the Checklist Text field in your instance.

Get a Checklist

GET /rest/api/2/issue/{issueIdOrKey} (reference)

Returns the details of an issue, including the checklist in text format.

cURL example:
1 2 3 4 curl --request GET \ --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'
Example response (application/json):
1 2 3 4 5 6 7 8 9 10 11 { "expand": "", "id": "10002", "self": "https://your-domain.atlassian.net/rest/api/2/issue/10002", "key": "DEMO-1", "fields": { (...) // omitted for brevity "customfield_10034": "--- Tested on\n* Chrome\n* Safari\n* Firefox\n* Edge\n* [x] IE11", } (...) // omitted for brevity }

Create or Update a Checklist

PUT /rest/api/2/issue/{issueIdOrKey} (reference)

Updates the issue by adding or updating a formatted checklist.

The Checklist Text custom field must be present on the Edit issue screen. Follow instructions here for adding a field to a screen.

 

cURL example:
1 2 3 4 5 6 7 8 9 10 curl --request PUT \ --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "fields": { "customfield_10034": "--- Tested on\n* [x] Chrome\n* Safari\n* Firefox\n* Edge\n* [x] IE11\n--- Mobile\n* Android\n* iPhone" } }'
Response errors:
1 {"errorMessages":[],"errors":{"customfield_10034":"Field 'customfield_10034' cannot be set. It is not on the appropriate screen, or unknown."}}

Remove a Checklist

Deletes a checklist by passing a null or empty value for to the Checklist Text custom field.

cURL example:
1 2 3 4 5 6 7 8 9 10 curl --request PUT \ --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "fields": { "customfield_10034": null } }'

Read, Modify & Update Checklists

You may want to retrieve a checklist from a Jira issue, modify the checklist’s items (for example, mark them as complete), and pass the updated checklist back to Jira issue. The steps are:

  1. Retrieve a representation of the issue via GET /rest/api/2/issue/{issueIdOrKey}

  2. Using Checklist Text field id, extract and parse checklist value: representation → fields → customfield_xxxxx (parse items by new line characters)

  3. Modify the parsed checklist as needed. For example, to check an item as complete, put an "x" in the square brackets (so that "* [] summary" becomes "* [x] summary"). 

  4. Upload the modified value back to the issue via PUT /rest/api/2/issue/{issueIdOrKey}

Add a Checklist to the Issue (cURL)

  1. Open terminal.

  2. Save the content of the snippet below to a local file, e.g. example.json:

    Text

    1 {"fields": {"customfield_12345": "[x] example item"}}

    Replace customfield_12345 string with the ID of Checklist Text custom field in your Jira instance. See instructions here for finding custom field ID.

  3. Type following command in the terminal.

    1 curl -D- -u "jack@herocoders.com:api_token" --request PUT --header "Content-Type: application/json" --url 'https://jiraUrl.atlassian.net/rest/api/2/issue/DEMO-1' --data-binary @example.json

    Replace jack@herocoders.com with the email address provided in your Atlassian ID account. 
    Replace api_token with a valid token generated in your Atlassian ID account (see instructions for generating tokens).
    Replace jiraUrl with URL of your Jira instance.
    Replace DEMO-1 with the appropriate issue key. 

  4. Go to Jira issue page to confirm that:

    1. Checklist has been updated and contains a single checked item "example item".

    2. The Checklist Text field has been updated with the checklist provided in example.json file. This will be visible if the Checklist Text field is on the View Issue Screen:




      You can also see that the other checklist custom fields (Checklist Progress and Checklist Completed) has been updated accordingly.

Check All Checklist Items on an Issue (Node.js)

  1. Install Node.js

  2. Install required Node.js modules with following command:

    1 npm install axios lodash



  3. Save the content of script.js file provided below to your local filesystem:

    script.js

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 const axios = require('axios'); const _ = require('lodash'); const issueKey = 'DEMO-2'; const jiraURL = 'https://your-jira-url.atlassian.net'; const credentials = { username: 'username', password: 'apiToken' }; const checklistFieldName = 'Checklist Text'; async function updateChecklist() { console.log(`Looking for ${checklistFieldName} field ID`); const metaResponse = await axios.get(`${jiraURL}/rest/api/2/issue/${issueKey}/editmeta`, { auth: credentials }); const checklistField = _.find(metaResponse.data.fields, (field) => { return _.isMatch(field, { name: checklistFieldName }) && _.find(field.operations, (operation) => { return operation === 'set'; }); }); if (!checklistField) { throw new Error('Checklist field not found'); } const checklistFieldId = `customfield_${checklistField.schema.customId}`; console.log(`Found checklist field ID: ${checklistFieldId}`); const issueResponse = await axios.get(`${jiraURL}/rest/api/2/issue/${issueKey}`, { auth: credentials }); const checklistText = issueResponse.data.fields[checklistFieldId]; console.log('Found checklist:'); console.log(checklistText); // replace "x" with "done" if you use checklist item statuses const updatedChecklistText = checklistText.replace(/^\*\s+\[.*]/gm, '* [x]'); console.log('Saving updated checklist:'); console.log(updatedChecklistText); const fieldsToUpdate = { [checklistFieldId]: updatedChecklistText, }; await axios.put(`${jiraURL}/rest/api/2/issue/${issueKey}`, { fields: fieldsToUpdate }, { auth: credentials }); } updateChecklist().then(() => { console.log('Checklist updated successfully'); }).catch((error) => { console.error('Failed: ', error instanceof Error ? error.stack : JSON.stringify(error)); });

    The scripts reads Checklist Text value from your issue, checks every item and performs PUT request to JIRA to change value of Checklist Text field.
     

  4. Edit script.js file and change issueKeyjiraUrl and credentials as appropriate. 

  5. Type following command in the terminal:

    1 node script.js

     

  6. Go to your JIRA and selected issue page and see the Checklist modified by the script. 

 

Note that the API can also be used to retrieve checklist metadata stored in issue entity properties.