Create a Checklist

A checklist groups related sub-tasks under a record (records are Record objects in the API). Use the createChecklist mutation to add a new checklist to a record, then use Checklist items to populate it. This page also documents the organization-wide checklistItems query for finding items across every record.

All requests go to https://api.blue.app/graphql and must include your authentication headers:

• blue-token-id: your token ID
• blue-token-secret: your token secret
• blue-org-id: your organization ID or slug

Header names are case-insensitive.

Request

Create a checklist by attaching it to a record. All three fields are required.

mutation CreateChecklist {
  createChecklist(input: { todoId: "todo_123", title: "Launch Checklist", position: 1 }) {
    id
    title
    position
  }
}

Parameters

CreateChecklistInput

Response

createChecklist returns the newly created Checklist. It starts with no items — add them with createChecklistItem.

{
  "data": {
    "createChecklist": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Launch Checklist",
      "position": 1
    }
  }
}

Returns — Checklist

Full example

Create a checklist and select a richer set of fields, including the parent record and creator.

mutation CreateChecklistFull {
  createChecklist(input: { todoId: "todo_123", title: "QA Verification Steps", position: 2 }) {
    id
    title
    position
    createdAt
    updatedAt
    createdBy {
      id
      fullName
    }
    todo {
      id
      title
    }
    checklistItems {
      id
      title
      done
    }
  }
}

Side effects

Creating a checklist:

• Records a CREATE_CHECKLIST activity entry on the record.
• Fires the TODO_CHECKLIST_CREATED webhook event.
• Pushes a real-time update to everyone viewing the record.

Errors

Permissions

Creating a checklist requires write access to the parent record’s workspace.

Query checklist items across your organization

The checklistItems query searches and paginates checklist items across every record in your organization, regardless of which record or checklist they belong to. Use it to build “my open items” dashboards or to find items by keyword. To read the items of a single checklist, select checklistItems on the Checklist object instead.

query MyChecklistItems {
  checklistItems(filter: { assigneeIds: ["user_123"], done: false }, skip: 0, take: 20) {
    items {
      id
      title
      done
      duedAt
      checklist {
        id
        title
      }
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

Arguments

ChecklistItemFilterInput

Sorting

The sort argument is a list of TodosSort! values applied in order; append _ASC or _DESC to each. The TodosSort enum is large (it is shared with the records query), but the checklistItems resolver only honors the nine values below. Any other value is silently ignored.

Full example

Find open items containing “deploy”, assigned to either of two users, on active records and non-archived workspaces, sorted by due date.

query SearchChecklistItems {
  checklistItems(
    filter: {
      q: "deploy"
      done: false
      todoDone: false
      excludeArchivedProjects: true
      assigneeIds: ["user_123", "user_456"]
    }
    sort: [duedAt_ASC]
    skip: 0
    take: 50
  ) {
    items {
      id
      title
      done
      startedAt
      duedAt
      createdAt
      users {
        id
        fullName
      }
      checklist {
        id
        title
        todo {
          id
          title
        }
      }
    }
    pageInfo {
      totalItems
      totalPages
      page
      perPage
      hasNextPage
      hasPreviousPage
    }
  }
}

Response

checklistItems returns a ChecklistItemPagination object: an items array plus a pageInfo block describing the page.

{
  "data": {
    "checklistItems": {
      "items": [
        {
          "id": "clm4n8qwx000008l0g4oxdqn7",
          "title": "Deploy to staging",
          "done": false,
          "duedAt": "2026-06-01T17:00:00.000Z",
          "checklist": {
            "id": "clm4n8qwx000009l0checklist1",
            "title": "Release Checklist"
          }
        }
      ],
      "pageInfo": {
        "totalItems": 1,
        "hasNextPage": false
      }
    }
  }
}

Returns — ChecklistItemPagination

PageInfo

Related

• Checklist items — create, edit, assign, and schedule items.
• Manage checklists — rename, reposition, and delete checklists.
• Update a record
• Webhooks