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
}
]
}
statusis the id of a status of the field context (todo,in_progress,done,skippedby default).assigneeis an Atlassian account id, ornull.dueis a date asyyyymmdd, ornull.headermarks 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
textis required. Defaults:status: "todo",mandatory: false,assignee: null,due: null. A missingidis generated. An item with blank text is dropped. "items": []clears the field.issueIdandfieldIdmay also be sent in the body; the query string wins when both are present.- The answer is
200with the same bodyGETwould 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.

