ToDo List REST API

Two REST endpoints let scripts and integrations read and replace the items of a ToDo List field. They are Forge app REST endpoints: they run inside Atlassian, like the rest of the app.

Method Path Scope Needs on the issue
GET /todo/items?issueId=<id>&fieldId=<customfield_id> read:todo-list:jbcf:custom — Read ToDo lists Browse projects
PUT /todo/items?issueId=<id>&fieldId=<customfield_id> write:todo-list:jbcf:custom — Update ToDo lists Edit issues

Requests run on behalf of the calling user, and the app checks that user’s permission on the issue. Read and write are separate scopes, so an integration that only reports on checklists does not get the right to change them.


Read: GET /todo/items

{
  "issueId": "10001",
  "fieldId": "customfield_10100",
  "fieldName": "ToDo List",
  "items": [
    {
      "id": "6b1e…",
      "text": "Write the docs",
      "status": "done",
      "mandatory": false,
      "assignee": "5b10a2…",
      "due": 20260813,
      "header": false,
      "isDefault": false
    }
  ]
}
  • status is the id of a status of the field context (todo, in_progress, done, skipped by default).
  • assignee is an Atlassian account id, or null.
  • due is a date as yyyymmdd, or null.
  • header marks a section header.
  • Properties that an integration stored on an item itself are returned as they were saved.

Replace: PUT /todo/items

{
  "items": [
    { "text": "Write the docs", "status": "done" },
    { "text": "Ship it", "mandatory": true, "due": 20260901 }
  ]
}
  • The list replaces the whole checklist.
  • Only text is required. Defaults: status: "todo", mandatory: false, assignee: null, due: null. A missing id is generated. An item with blank text is dropped.
  • "items": [] clears the field.
  • issueId and fieldId may also be sent in the body; the query string wins when both are present.
  • The answer is 200 with the same body GET would return for the checklist as stored.
  • The limits of the field apply (100 items, 255 characters per text, 500 per note, no two items with the same text).
  • A write adds an entry to the issue history.

Status codes

Code When
200 Read or write succeeded.
400 issueId or fieldId missing, the body cannot be read, items is not a list of objects, or the items break a limit (details names the items).
403 The user cannot browse (GET) or edit (PUT) the issue, or the app license is not active (PUT).
404 fieldId is not a ToDo List field, the field does not apply to this issue, or the issue cannot be read.
500 Unexpected failure in the app.
502 Jira refused or did not answer the write.

Error bodies look like {"error": "…"}, with "details": ["…"] for validation errors.