---

Create a Dashboard

The createDashboard mutation allows you to create a new dashboard within your company or project. Dashboards are powerful visualization tools that help teams track metrics, monitor progress, and make data-driven decisions.

Basic Example

mutation CreateDashboard {
  createDashboard(
    input: {
      companyId: "comp_abc123"
      title: "Sales Performance Dashboard"
    }
  ) {
    id
    title
    createdBy {
      id
      email
      firstName
      lastName
    }
    createdAt
  }
}

Project-Specific Dashboard

Create a dashboard associated with a specific project:

mutation CreateProjectDashboard {
  createDashboard(
    input: {
      companyId: "comp_abc123"
      projectId: "proj_xyz789"
      title: "Q4 Project Metrics"
    }
  ) {
    id
    title
    project {
      id
      name
    }
    createdBy {
      id
      email
    }
    dashboardUsers {
      id
      user {
        id
        email
      }
      role
    }
    createdAt
  }
}

Input Parameters

CreateDashboardInput

Parameter	Type	Required	Description
companyId	String!	✅ Yes	The ID of the company where the dashboard will be created
title	String!	✅ Yes	The name of the dashboard. Must be a non-empty string
projectId	String	No	Optional ID of a project to associate with this dashboard

Response Fields

The mutation returns a complete Dashboard object:

Field	Type	Description
id	String!	Unique identifier for the created dashboard
title	String!	The dashboard title as provided
companyId	String!	The company this dashboard belongs to
projectId	String	The associated project ID (if provided)
project	Project	The associated project object (if projectId was provided)
createdBy	User!	The user who created the dashboard (you)
dashboardUsers	[DashboardUser!]!	List of users with access (initially just the creator)
createdAt	DateTime!	Timestamp of when the dashboard was created
updatedAt	DateTime!	Timestamp of last modification (same as createdAt for new dashboards)

DashboardUser Fields

When a dashboard is created, the creator is automatically added as a dashboard user:

Field	Type	Description
id	String!	Unique identifier for the dashboard user relationship
user	User!	The user object with access to the dashboard
role	DashboardRole!	The user's role (creator gets full access)
dashboard	Dashboard!	Reference back to the dashboard

Required Permissions

Any authenticated user who belongs to the specified company can create dashboards. There are no special role requirements.

User Status	Can Create Dashboard
Company Member	✅ Yes
Non-Company Member	❌ No
Unauthenticated	❌ No

Error Responses

Invalid Company

{
  "errors": [{
    "message": "Company not found",
    "extensions": {
      "code": "NOT_FOUND"
    }
  }]
}

User Not in Company

{
  "errors": [{
    "message": "You don't have access to this company",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

Invalid Project

{
  "errors": [{
    "message": "Project not found or doesn't belong to the specified company",
    "extensions": {
      "code": "NOT_FOUND"
    }
  }]
}

Empty Title

{
  "errors": [{
    "message": "Dashboard title cannot be empty",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Important Notes

• Automatic ownership: The user creating the dashboard automatically becomes its owner with full permissions
• Project association: If you provide a projectId, it must belong to the same company
• Initial permissions: Only the creator has access initially. Use editDashboard to add more users
• Title requirements: Dashboard titles must be non-empty strings. There's no uniqueness requirement
• Company membership: You must be a member of the company to create dashboards in it

Dashboard Creation Workflow

1. Create the dashboard using this mutation
2. Configure charts and widgets using the dashboard builder UI
3. Add team members using the editDashboard mutation with dashboardUsers
4. Set up filters and date ranges through the dashboard interface
5. Share or embed the dashboard using its unique ID

Use Cases

1. Executive dashboards: Create high-level overviews of company metrics
2. Project tracking: Build project-specific dashboards to monitor progress
3. Team performance: Track team productivity and achievement metrics
4. Client reporting: Create dashboards for client-facing reports
5. Real-time monitoring: Set up dashboards for live operational data

Best Practices

1. Naming conventions: Use clear, descriptive titles that indicate the dashboard's purpose
2. Project association: Link dashboards to projects when they're project-specific
3. Access management: Add team members immediately after creation for collaboration
4. Organization: Create a dashboard hierarchy using consistent naming patterns

Related Operations

• List Dashboards - Retrieve all dashboards for a company or project
• Edit Dashboard - Rename dashboard or manage users
• Copy Dashboard - Duplicate an existing dashboard
• Delete Dashboard - Remove a dashboard