Checklist Items

Checklist items are the individual to-dos inside a checklist. Each one can be assigned to users, scheduled with start and due dates, and marked complete. In the API they are ChecklistItem objects, attached to a Checklist, which in turn belongs to a record (Record).

This page covers the five mutations that operate on checklist items:

• createChecklistItem — add an item to a checklist.
• editChecklistItem — update title, position, completion, or move it to another checklist.
• deleteChecklistItem — remove an item.
• setChecklistItemAssignees — replace the item’s assignees.
• updateChecklistItemDueDate — set or clear start and due dates.

To create the parent checklist first, see Create a Checklist. To find items across your whole organization, use the checklistItems query.

Authentication

All requests go to https://api.blue.app/graphql and authenticate with your personal access token headers. Headers are case-insensitive; the canonical casing is shown below.

curl https://api.blue.app/graphql \
  -H "blue-token-id: YOUR_TOKEN_ID" \
  -H "blue-token-secret: YOUR_TOKEN_SECRET" \
  -H "blue-org-id: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "..."}'

blue-org-id accepts either the organization ID or its slug. See Authentication for how to create tokens.

Create a checklist item

Use the createChecklistItem mutation to add a new item to an existing checklist. The item starts incomplete and unassigned; assign users and set dates with the dedicated mutations below.

Request

mutation CreateChecklistItem {
  createChecklistItem(input: { checklistId: "list_123", title: "Write unit tests", position: 1 }) {
    id
    title
    position
    done
  }
}

Parameters

CreateChecklistItemInput

Response

{
  "data": {
    "createChecklistItem": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Write unit tests",
      "position": 1,
      "done": false
    }
  }
}

Returns the created ChecklistItem. See ChecklistItem fields for the full selection set.

Edit a checklist item

Use the editChecklistItem mutation to update an item’s title, position, or completion status, or to move it to a different checklist. Every field except checklistItemId is optional; omitted fields are left unchanged.

Request

Mark an item complete:

mutation MarkItemDone {
  editChecklistItem(input: { checklistItemId: "todo_123", done: true }) {
    id
    title
    done
  }
}

Parameters

EditChecklistItemInput

Response

{
  "data": {
    "editChecklistItem": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Write unit tests",
      "done": true
    }
  }
}

Returns the updated ChecklistItem.

Full example

Move an item to another checklist and update its title and position in one call:

mutation EditChecklistItem {
  editChecklistItem(
    input: {
      checklistItemId: "todo_123"
      checklistId: "list_456"
      title: "Updated task description"
      position: 2
      done: false
    }
  ) {
    id
    title
    position
    done
    checklist {
      id
      title
    }
    users {
      id
      fullName
    }
  }
}

Toggling done and changing the title or moving the item fire distinct activity actions: a completion change records MARK_CHECKLIST_ITEM_AS_DONE / MARK_CHECKLIST_ITEM_AS_UNDONE, while a title change records UPDATE_CHECKLIST_ITEM. A completion change also triggers any matching automation (CHECKLIST_ITEM_MARKED_AS_DONE / CHECKLIST_ITEM_MARKED_AS_UNDONE).

Delete a checklist item

Use the deleteChecklistItem mutation to permanently remove an item. This is irreversible.

Request

mutation DeleteChecklistItem {
  deleteChecklistItem(id: "todo_123")
}

Parameters

Response

Returns Boolean! — true when the item is deleted.

{
  "data": {
    "deleteChecklistItem": true
  }
}

Set assignees

Use the setChecklistItemAssignees mutation to set the complete list of users assigned to an item. This is a replace operation: pass every assignee you want each time. Users present in the existing assignment but absent from assigneeIds are unassigned; new IDs are added.

Request

mutation AssignChecklistItem {
  setChecklistItemAssignees(
    input: { checklistItemId: "todo_123", assigneeIds: ["user_123", "user_456"] }
  )
}

To remove all assignees, pass an empty array:

mutation UnassignAllFromItem {
  setChecklistItemAssignees(input: { checklistItemId: "todo_123", assigneeIds: [] })
}

Parameters

SetChecklistItemAssigneesInput

Response

Returns Boolean! — true when assignees are updated.

{
  "data": {
    "setChecklistItemAssignees": true
  }
}

Only users who are members of the record’s workspace (and your organization) can be assigned; IDs that don’t meet both conditions are silently skipped. Newly assigned users receive an email and push notification.

Set the due date

Use the updateChecklistItemDueDate mutation to set or clear an item’s start and due dates. Setting a due date schedules an overdue notification for the item’s assignees.

Request

mutation SetItemDueDate {
  updateChecklistItemDueDate(
    input: { checklistItemId: "todo_123", duedAt: "2026-03-15T17:00:00Z" }
  ) {
    id
    title
    startedAt
    duedAt
  }
}

Parameters

UpdateChecklistItemDueDateInput

Response

{
  "data": {
    "updateChecklistItemDueDate": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Write unit tests",
      "startedAt": null,
      "duedAt": "2026-03-15T17:00:00Z"
    }
  }
}

Returns the updated ChecklistItem.

Full example

Set a start/due window, then later clear both dates by passing null:

mutation SetItemDateRange {
  updateChecklistItemDueDate(
    input: {
      checklistItemId: "todo_123"
      startedAt: "2026-03-10T09:00:00Z"
      duedAt: "2026-03-15T17:00:00Z"
    }
  ) {
    id
    startedAt
    duedAt
    users {
      id
      fullName
    }
  }
}

mutation RemoveItemDueDate {
  updateChecklistItemDueDate(
    input: { checklistItemId: "todo_123", startedAt: null, duedAt: null }
  ) {
    id
    startedAt
    duedAt
  }
}

Clearing or changing the dates fires the matching webhook event: TODO_CHECKLIST_ITEM_DUE_DATE_ADDED when an item previously had no dates, TODO_CHECKLIST_ITEM_DUE_DATE_REMOVED when both fields become null, otherwise TODO_CHECKLIST_ITEM_DUE_DATE_UPDATED.

ChecklistItem fields

createChecklistItem, editChecklistItem, and updateChecklistItemDueDate return a ChecklistItem. (deleteChecklistItem and setChecklistItemAssignees return Boolean! — see their Response sections.) Select any of these fields:

Errors

{
  "errors": [
    {
      "message": "Checklist item was not found.",
      "extensions": { "code": "CHECKLIST_ITEM_NOT_FOUND" }
    }
  ]
}

Permissions

All five mutations require the same access level on the record’s workspace. Read-only roles are denied.

Title handling

Titles passed to createChecklistItem and editChecklistItem are sanitized server-side: HTML tags are stripped and only the plain-text content is stored. Send plain text to avoid surprises.

Related

• Create a Checklist — create the parent checklist and query items across the organization.
• Manage Checklists — rename, reorder, and delete checklists.
• Assignees — assign users to records (not just checklist items).
• Webhooks — subscribe to checklist item events.