---

Overview

Projects are the core organizational unit in Blue. They contain lists, todos, custom fields, automations, and all other work-related data. Projects belong to companies and have their own permission systems, templates, and configurations.

Available Operations

Core Project Operations

Operation	Description	Link
Create Project	Create a new project or from template	View Details →
List Projects	Query and filter projects	View Details →
Delete Project	Permanently delete a project	View Details →
Archive Project	Archive/unarchive projects	View Details →
Rename Project	Update project name and slug	View Details →
Copy Project	Duplicate an existing project	View Details →

Project Components

Component	Description	Link
Lists	Manage todo lists within projects	View Details →
Templates	Work with project templates	View Details →
Activity	Track project activity and changes	View Details →

Key Concepts

Project Structure

• Projects belong to companies
• Each project can have multiple lists
• Lists contain todos
• Projects support custom fields, tags, and automations

Permissions Model

Projects have a multi-level permission system:

Level	Permissions
OWNER	Full control, can delete project
ADMIN	Manage project settings, users, and content
MEMBER	Create and edit content
CLIENT	Limited edit access
VIEW_ONLY	Read-only access
COMMENT_ONLY	Can only comment

Project Categories

Projects can be categorized for better organization:

• CRM
• CROSS_FUNCTIONAL
• CUSTOMER_SUCCESS
• DESIGN
• ENGINEERING
• GENERAL (default)
• HR
• IT
• MARKETING
• OPERATIONS
• PERSONAL
• PROCUREMENT
• PRODUCT
• SALES

Common Patterns

Creating a Basic Project

mutation CreateProject {
  createProject(input: {
    name: "Q1 Marketing Campaign"
    companyId: "company-123"
    category: MARKETING
  }) {
    id
    name
    slug
  }
}

Querying Projects with Filters

query GetProjects {
  projectList(
    filter: {
      companyIds: ["company-123"]
      isArchived: false
      categories: [MARKETING, SALES]
    }
    sort: [{ field: updatedAt, direction: DESC }]
    take: 20
  ) {
    items {
      id
      name
      category
      todosCount
      todosDoneCount
    }
    pageInfo {
      hasNextPage
      total
    }
  }
}

Note: The projectList query is the recommended approach for querying projects. A legacy projects query exists but should not be used for new implementations.

Managing Project Lists

# Get all lists in a project
query GetProjectLists {
  todoLists(projectId: "project-123") {
    id
    title
    position
    todosCount
  }
}

# Create a new list
mutation CreateList {
  createTodoList(input: {
    projectId: "project-123"
    title: "To Do"
    position: 1.0
  }) {
    id
    title
  }
}

Best Practices

1. Project Naming

   • Use clear, descriptive names
   • Avoid special characters that might affect slugs
   • Keep names under 50 characters

2. Permission Management

   • Start with minimal permissions
   • Use CLIENT role for external stakeholders
   • Regularly audit project access

3. Organization

   • Use categories to group similar projects
   • Archive completed projects instead of deleting
   • Use templates for repetitive project types

4. Performance

   • Use pagination for large project lists
   • Filter by active/archived status
   • Limit the number of lists per project (max 50)

Error Handling

Common errors you might encounter:

Error Code	Description	Solution
PROJECT_NOT_FOUND	Project doesn't exist or no access	Verify project ID and permissions
COMPANY_NOT_FOUND	Company doesn't exist	Check company ID
FORBIDDEN	Insufficient permissions	Ensure proper role level
BAD_USER_INPUT	Validation error (e.g., name too long)	Check input validation requirements

Related Resources

• Records API - Managing todos/records within projects
• Custom Fields API - Adding custom fields to projects
• Automations API - Setting up project automations
• Users API - Managing project users and permissions