Create a Workspace

Use the createWorkspace mutation to create a new workspace. Workspaces are Workspace objects in the API, and live inside an organization (Organization). The user whose token makes the request is automatically added to the new workspace as its OWNER.

Creating a workspace from scratch returns the new Workspace synchronously. Creating one from a template is queued and runs in the background — the mutation returns null, and you poll copyProjectStatus to track progress.

Request

The smallest call provides an organization and a name.

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

Include your authentication headers (header names are case-insensitive):

• blue-token-id — your API token ID
• blue-token-secret — your API token secret
• blue-org-id — your organization ID or slug

companyId accepts either the organization’s ID or its slug.

Parameters

CreateWorkspaceInput

ProjectCategory

Response

The mutation returns the newly created Workspace. (The return type is nullable — see Create from a template for the case where it returns null.)

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

Returns

createWorkspace returns a Workspace. Common fields:

There is no companyId scalar on Workspace — the organization is exposed as the organization relation. Select organization { id slug name } when you need its identifiers.

Create from a template

Pass a templateId to seed the new workspace from an existing template. This copies the template’s lists, records, custom fields, automations, tags, files, and other content.

mutation CreateFromTemplate {
  createWorkspace(
    input: { companyId: "company_123", name: "Q1 Marketing Campaign", templateId: "project_123" }
  ) {
    id
  }
}

Track creation status

Use the copyProjectStatus query to check where your workspace sits in the copy queue.

query WorkspaceCopyStatus {
  copyProjectStatus {
    newProjectName
    isTemplate
    isActive
    queuePosition
    totalQueues
  }
}

{
  "data": {
    "copyProjectStatus": {
      "newProjectName": "Q1 Marketing Campaign",
      "isTemplate": true,
      "isActive": false,
      "queuePosition": 2,
      "totalQueues": 5
    }
  }
}

copyProjectStatus returns a CopyProjectStatus:

Cover image configuration

The coverConfig input controls how record cover images are chosen in the new workspace. It is only applied when creating from a template; for workspaces created from scratch, configure cover images afterward with Rename / edit a workspace.

mutation CreateWithCoverConfig {
  createWorkspace(
    input: {
      companyId: "company_123"
      name: "Q1 Marketing Campaign"
      templateId: "project_123"
      description: "Marketing initiatives for Q1"
      color: "#10B981"
      icon: "megaphone"
      category: MARKETING
      coverConfig: { enabled: true, fit: COVER, imageSelectionType: FIRST, source: DESCRIPTION }
    }
  ) {
    id
  }
}

TodoCoverConfigInput

• ImageFit — COVER, CONTAIN, FILL, SCALE_DOWN
• ImageSelectionType — FIRST, LAST
• ImageSource — DESCRIPTION, COMMENTS, CUSTOM_FIELD

Errors

{
  "errors": [
    {
      "message": "Company was not found.",
      "extensions": { "code": "COMPANY_NOT_FOUND" }
    }
  ]
}

A plan limit on the number of workspaces (or, for template copies, the number of records) is reported separately with an upgrade-oriented payload rather than one of the codes above.

Permissions

You must be an OWNER, ADMIN, or MEMBER of the organization to create a workspace. The creating user is added to the new workspace as its OWNER.

Related

• List workspaces
• Rename / edit a workspace
• Copy a workspace
• Templates
• Error codes