Create a Checklist

Create a Checklist

The createChecklist mutation allows you to add a new checklist to an existing record. Checklists help break down work into smaller, trackable items that can be assigned, scheduled, and marked as complete.

Basic Example

Create a simple checklist on a record:

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

Advanced Example

Create a checklist and query back its full details including the parent record:

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

Input Parameters

CreateChecklistInput

Response Fields

The mutation returns a Checklist object:

Query Checklist Items

The checklistItems query lets you search and paginate through checklist items across your entire organization. This is useful for building dashboards or finding assigned checklist items.

Basic Example

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

Advanced Example

Search for checklist items with sorting and additional filters:

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 {
      hasNextPage
      total
    }
  }
}

ChecklistItemFilterInput

Sort Options

Checklist items support the following sort values (append _ASC or _DESC):

Required Permissions

Error Responses

Permission Denied

{
  "errors": [{
    "message": "You do not have permission to perform this action.",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

When: The user has VIEW_ONLY or COMMENT_ONLY access, or the workspace is archived.

Record Not Found

{
  "errors": [{
    "message": "Todo was not found.",
    "extensions": {
      "code": "TODO_NOT_FOUND"
    }
  }]
}

When: The specified todoId does not exist or the user lacks access to it.

Important Notes

Side Effects

Creating a checklist triggers:

• Activity log entry (CREATE_CHECKLIST action)
• Webhook notification (todoChecklistCreated)
• Real-time update pushed to all users viewing the record

Business Logic

• Position: The position field determines the ordering of checklists within a record. Use incremental values (e.g., 1, 2, 3) to control display order.
• Empty Checklists: Checklists are created without items. Use the createChecklistItem mutation to add items after creation.
• Inline Creation: Checklists can also be created inline when creating a record via createTodo using the checklists input field.

Related Endpoints

• Create Checklist Item: Use createChecklistItem to add items to a checklist
• Edit Checklist: Use editChecklist to rename or reorder a checklist
• Delete Checklist: Use deleteChecklist to remove a checklist and all its items
• Query Checklist Items: Use the checklistItems query to search items across all records