Workspaces API

Overview

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

Available Operations

Core Workspace Operations

Workspace Components

Key Concepts

Workspace Structure

• Workspaces belong to organizations
• Each workspace can have multiple lists
• Lists contain todos
• Workspaces support custom fields, tags, and automations

Permissions Model

Workspaces have a multi-level permission system:

Workspace Categories

Workspaces 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 Workspace

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

Querying Workspaces 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 workspaces. A legacy projects query exists but should not be used for new implementations.

Managing Workspace 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. Workspace 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 workspace access

3. Organization

   • Use categories to group similar workspaces
   • Archive completed workspaces instead of deleting
   • Use templates for repetitive workspace types

4. Performance

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

Error Handling

Common errors you might encounter:

Related Resources

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