Workspaces

A workspace is the top-level container for work in Blue: it holds lists, records, custom fields, tags, automations, and saved views. Every workspace belongs to one organization. In the API, a workspace is a Workspace object and an organization is an Organization — the GraphQL surface uses those type names throughout.

This section covers creating workspaces, listing and filtering them, renaming, archiving, copying, deleting, and managing the lists inside them.

Operations

Key concepts

Structure

A workspace (Workspace) belongs to exactly one organization (Organization). Inside it:

• Lists (RecordList) group records into columns or stages.
• Records (Record) are the individual items of work, each owned by a list.
• Custom fields, tags, automations, and saved views are all scoped to the workspace.

Most workspace-scoped operations require the blue-workspace-id header in addition to the organization headers. Organization (companyId) and workspace (projectId) arguments accept either an ID or a slug.

Categories

Each workspace has a category (ProjectCategory), used for grouping and filtering. It defaults to GENERAL. The complete set of values is:

CRM
CROSS_FUNCTIONAL
CUSTOMER_SUCCESS
DESIGN
ENGINEERING
GENERAL
HR
IT
MARKETING
OPERATIONS
PRODUCT
SALES

Permissions

A user’s access to a workspace is one of the UserAccessLevel values:

The user whose token makes a createWorkspace request is automatically added to the new workspace as its OWNER.

Create a workspace

Use the createWorkspace mutation to create a workspace. Only companyId and name are required; pass templateId to seed the workspace from a template, or category to classify it.

mutation CreateWorkspace {
  createWorkspace(
    input: { companyId: "company_123", name: "Q1 Marketing Campaign", category: MARKETING }
  ) {
    id
    name
    slug
    category
  }
}

{
  "data": {
    "createWorkspace": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "name": "Q1 Marketing Campaign",
      "slug": "q1-marketing-campaign",
      "category": "MARKETING"
    }
  }
}

createWorkspace returns a nullable Workspace. The workspace name is capped at 50 characters. See Create a workspace for the full input reference, including folderId, description, color, icon, and coverConfig.

List workspaces

Use the workspaceList query to filter, sort, and paginate workspaces. The filter’s companyIds is required; everything else is optional.

query ListWorkspaces {
  workspaceList(
    filter: { companyIds: ["company_123"], archived: false }
    sort: [updatedAt_DESC]
    take: 20
  ) {
    items {
      id
      name
      slug
      category
      archived
      updatedAt
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

{
  "data": {
    "workspaceList": {
      "items": [
        {
          "id": "clm4n8qwx000008l0g4oxdqn7",
          "name": "Q1 Marketing Campaign",
          "slug": "q1-marketing-campaign",
          "category": "MARKETING",
          "archived": false,
          "updatedAt": "2026-05-29T10:14:00.000Z"
        }
      ],
      "pageInfo": {
        "totalItems": 1,
        "hasNextPage": false
      }
    }
  }
}

sort takes ProjectSort enum values (name_ASC, updatedAt_DESC, createdAt_DESC, position_ASC, …), and pageInfo.totalItems holds the total count. To filter by category, query with archived / isTemplate / search and filter the results client-side — ProjectListFilter does not accept a category filter. See List workspaces for the full filter and pagination reference.

Manage lists in a workspace

There are two ways to read the lists in a workspace.

For a simple, unpaginated read of every list in one workspace, use the recordLists(projectId:) query:

query WorkspaceLists {
  recordLists(projectId: "project_123") {
    id
    title
    position
    todosCount
  }
}

For filtering across workspaces, or for pagination, use recordListQueries.recordLists with a TodoListsFilterInput (its companyIds is required):

query PaginatedLists {
  recordListQueries {
    recordLists(filter: { companyIds: ["company_123"], projectIds: ["project_123"] }, take: 20) {
      items {
        id
        title
        position
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

To create a list, use the createRecordList mutation. All three inputs — projectId, title, and position — are required:

mutation CreateList {
  createRecordList(input: { projectId: "project_123", title: "To Do", position: 1.0 }) {
    id
    title
    position
  }
}

A workspace can hold at most 50 lists; creating a 51st fails with FORBIDDEN. See Lists for the full reference.

Errors

Related

• Records — the records (Record) that live inside a workspace’s lists.
• Custom fields — add structured fields to a workspace’s records.
• Automations — automate work within a workspace.
• User management — manage who can access a workspace and at what level.