Lists

Overview

Lists in Blue are containers for organizing todos within a workspace. Each list can hold multiple todos and helps structure work into logical groups. Lists support positioning, locking, and role-based access control.

Key Concepts

• Each workspace can have up to 50 lists
• Lists are ordered by position (ascending)
• Lists can be locked to prevent modifications
• Lists respect workspace-level and role-based permissions
• Deleted lists are moved to trash (soft delete)

Queries

Get a Single List

Retrieve a specific todo list by ID.

query GetTodoList($id: String!) {
  todoList(id: $id) {
    id
    uid
    title
    position
    isDisabled
    isLocked
    createdAt
    updatedAt
    project {
      id
      name
    }
    createdBy {
      id
      username
    }
  }
}

Get All Lists in a Workspace

Retrieve all todo lists for a specific workspace.

query GetProjectLists($projectId: String!) {
  todoLists(projectId: $projectId) {
    id
    uid
    title
    position
    isDisabled
    isLocked
    createdAt
    updatedAt
  }
}

Advanced List Query

Query lists with filtering, sorting, and pagination.

query SearchTodoLists($filter: TodoListsFilterInput!, $sort: [TodoListsSort!], $skip: Int, $take: Int) {
  todoListQueries {
    todoLists(filter: $filter, sort: $sort, skip: $skip, take: $take) {
      items {
        id
        uid
        title
        position
        isDisabled
        isLocked
        createdAt
        updatedAt
        project {
          id
          name
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        total
      }
    }
  }
}

Mutations

Create a List

Create a new todo list in a workspace.

mutation CreateTodoList($input: CreateTodoListInput!) {
  createTodoList(input: $input) {
    id
    uid
    title
    position
    isDisabled
    isLocked
    createdAt
    project {
      id
      name
    }
  }
}

Example:

mutation {
  createTodoList(input: {
    projectId: "project-123"
    title: "Sprint 1 Tasks"
    position: 1.0
  }) {
    id
    title
  }
}

Edit a List

Update an existing todo list’s properties.

mutation EditTodoList($input: EditTodoListInput!) {
  editTodoList(input: $input) {
    id
    title
    position
    isLocked
    updatedAt
  }
}

Example:

mutation {
  editTodoList(input: {
    todoListId: "list-123"
    title: "Sprint 1 - In Progress"
    position: 2.0
    isLocked: true
  }) {
    id
    title
    isLocked
  }
}

Delete a List

Delete a todo list (moves to trash).

mutation DeleteTodoList($input: DeleteTodoListInput!) {
  deleteTodoList(input: $input) {
    success
  }
}

Example:

mutation {
  deleteTodoList(input: {
    projectId: "project-123"
    todoListId: "list-123"
  }) {
    success
  }
}

Mark List as Done/Undone

Mark all todos in a list as done or undone.

# Mark as done
mutation MarkListDone($todoListId: String!, $filter: TodosFilter) {
  markTodoListAsDone(todoListId: $todoListId, filter: $filter)
}

# Mark as undone
mutation MarkListUndone($todoListId: String!, $filter: TodosFilter) {
  markTodoListAsUndone(todoListId: $todoListId, filter: $filter)
}

Input Types

CreateTodoListInput

EditTodoListInput

DeleteTodoListInput

TodoListsFilterInput

TodoListsSort Values

Response Types

TodoList Type

TodoListsPagination Type

Required Permissions

Query Permissions

Mutation Permissions

Note: Users with CLIENT role can edit lists but cannot create or delete them. Users with VIEW_ONLY or COMMENT_ONLY roles cannot create, edit, or delete lists.

Error Responses

TodoListNotFoundError

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

WorkspaceNotFoundError

{
  "errors": [{
    "message": "Project was not found.",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Maximum Lists Error

{
  "errors": [{
    "message": "You have reached the maximum number of todo lists for this project.",
    "extensions": {
      "code": "INTERNAL_SERVER_ERROR"
    }
  }]
}

UnauthorizedError

{
  "errors": [{
    "message": "Unauthorized",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

Important Notes

• List Limit: Each workspace can have a maximum of 50 lists
• Soft Delete: Deleted lists are moved to trash and can potentially be recovered
• Position Management: When creating lists, ensure positions don’t conflict. Use incremental values (1.0, 2.0, 3.0) to allow insertion between lists
• Role-Based Access: Lists can be hidden from certain roles using ProjectUserRoleTodoList permissions
• Webhooks: List creation, updates, and deletion trigger webhooks if configured
• Activity Tracking: All list operations are logged in the activity feed
• Real-time Updates: List changes are published via subscriptions for real-time updates

Related Operations

• Use todos query to fetch todos within a list
• Use createTodo mutation to add todos to a list
• Use moveTodo mutation to move todos between lists
• Subscribe to list changes using subscribeToTodoList subscription