Dashboard Widget Groups (v1)

Overview

The Dashboard Widget Groups API allows workspace owners to organize widgets into groups for better dashboard organization. Groups can contain multiple widgets, have custom names, background colors, and separators. Widgets can be moved between groups or exist as standalone widgets.

Method & Path

GET /api/v1/workspace/:workspaceId/dashboard/groups
POST /api/v1/workspace/:workspaceId/dashboard/groups
GET /api/v1/workspace/:workspaceId/dashboard/groups/:groupId
PATCH /api/v1/workspace/:workspaceId/dashboard/groups/:groupId
DELETE /api/v1/workspace/:workspaceId/dashboard/groups/:groupId
PUT /api/v1/workspace/:workspaceId/dashboard/groups/reorder
POST /api/v1/workspace/:workspaceId/dashboard/widgets/:widgetInstanceId/move-to-group

Description

Widget groups provide a way to organize related widgets together on the dashboard. Each group:

• Has a name and optional background color
• Can display separators above and/or below
• Can be dragged as a single unit (by dragging the group header)
• Contains widgets that can be arranged independently within the group
• Has its own auto-arrange button to organize widgets within the group

Authentication

Required: Workspace authentication via session cookie.

Headers

• Content-Type: application/json
• Cookie with workspace session

List Dashboard Groups

Method & Path

GET /api/v1/workspace/:workspaceId/dashboard/groups

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	The workspace ID

Response 200 OK

{
  "groups": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f191e810c19729de860ea",
      "name": "الجلسات",
      "position": {
        "x": 0,
        "y": 0
      },
      "size": {
        "w": 12,
        "h": 6
      },
      "order": 0,
      "backgroundColor": "#f3f4f6",
      "showSeparatorAbove": true,
      "showSeparatorBelow": false,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}

Common Errors

404 Not Found: Workspace not found or access denied 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired or insufficient permissions

Get Dashboard Group

Method & Path

GET /api/v1/workspace/:workspaceId/dashboard/groups/:groupId

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	The workspace ID
groupId	string	Yes	The group ID

Response 200 OK

{
  "group": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f191e810c19729de860ea",
    "name": "الجلسات",
    "position": {
      "x": 0,
      "y": 0
    },
    "size": {
      "w": 12,
      "h": 6
    },
    "order": 0,
    "backgroundColor": "#f3f4f6",
    "showSeparatorAbove": true,
    "showSeparatorBelow": false,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Common Errors

404 Not Found: Group not found 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired

Create Dashboard Group

Method & Path

POST /api/v1/workspace/:workspaceId/dashboard/groups

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	The workspace ID

Request Body

{
  "name": "الجلسات",
  "position": {
    "x": 0,
    "y": 0
  },
  "size": {
    "w": 6,
    "h": 1
  },
  "backgroundColor": "#f3f4f6",
  "showSeparatorAbove": true,
  "showSeparatorBelow": false
}

Fields:

• name (string, required): Group name (max 100 characters)
• position (object, optional): Initial position {x: number, y: number}. Defaults to {x: 0, y: 0}
• size (object, optional): Initial size {w: number (1-12), h: number}. Defaults to {w: 6, h: 1} (header only)
• backgroundColor (string, optional): Background color in CSS color format (e.g., "#f3f4f6"). Can be null for no background color
• showSeparatorAbove (boolean, optional): Show separator above the group. Defaults to false
• showSeparatorBelow (boolean, optional): Show separator below the group. Defaults to false

Response 201 Created

{
  "group": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f191e810c19729de860ea",
    "name": "الجلسات",
    "position": {
      "x": 0,
      "y": 0
    },
    "size": {
      "w": 6,
      "h": 1
    },
    "order": 0,
    "backgroundColor": "#f3f4f6",
    "showSeparatorAbove": true,
    "showSeparatorBelow": false,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Common Errors

400 Bad Request: Invalid name or invalid position/size values 404 Not Found: Workspace not found 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired

Update Dashboard Group

Method & Path

PATCH /api/v1/workspace/:workspaceId/dashboard/groups/:groupId

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	The workspace ID
groupId	string	Yes	The group ID

Request Body

{
  "name": "الجلسات المحدثة",
  "position": {
    "x": 0,
    "y": 0
  },
  "size": {
    "w": 12,
    "h": 8
  },
  "backgroundColor": "#dbeafe",
  "showSeparatorAbove": false,
  "showSeparatorBelow": true,
  "order": 1
}

Fields (all optional):

• name (string): Group name (max 100 characters)
• position (object): New position {x: number, y: number}
• size (object): New size {w: number (1-12), h: number}
• backgroundColor (string | null): Background color in CSS color format, or null to remove background color
• showSeparatorAbove (boolean): Show separator above the group
• showSeparatorBelow (boolean): Show separator below the group
• order (number): New order for sorting

Response 200 OK

{
  "group": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f191e810c19729de860ea",
    "name": "الجلسات المحدثة",
    "position": {
      "x": 0,
      "y": 0
    },
    "size": {
      "w": 12,
      "h": 8
    },
    "order": 1,
    "backgroundColor": "#dbeafe",
    "showSeparatorAbove": false,
    "showSeparatorBelow": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

Common Errors

400 Bad Request: Invalid name or invalid position/size values 404 Not Found: Group not found 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired

Delete Dashboard Group

Method & Path

DELETE /api/v1/workspace/:workspaceId/dashboard/groups/:groupId

Description

Deletes a widget group. When a group is deleted, all widgets within that group become standalone widgets (their groupId is set to null).

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	The workspace ID
groupId	string	Yes	The group ID

Response 204 No Content

No response body.

Common Errors

404 Not Found: Group not found 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired

Reorder Dashboard Groups

Method & Path

PUT /api/v1/workspace/:workspaceId/dashboard/groups/reorder

Description

Updates the position, size, and order of multiple groups at once. Useful for batch updates after drag-and-drop operations.

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	The workspace ID

Request Body

{
  "groups": [
    {
      "id": "507f1f77bcf86cd799439011",
      "position": {
        "x": 0,
        "y": 0
      },
      "size": {
        "w": 12,
        "h": 6
      },
      "order": 0
    },
    {
      "id": "507f1f77bcf86cd799439012",
      "position": {
        "x": 0,
        "y": 6
      },
      "size": {
        "w": 12,
        "h": 4
      },
      "order": 1
    }
  ]
}

Fields:

• groups (array, required): Array of group updates, each containing:
  • id (string, required): Group ID
  • position (object, required): Position {x: number, y: number}
  • size (object, required): Size {w: number (1-12), h: number}
  • order (number, required): Order for sorting

Response 200 OK

{
  "groups": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f191e810c19729de860ea",
      "name": "الجلسات",
      "position": {
        "x": 0,
        "y": 0
      },
      "size": {
        "w": 12,
        "h": 6
      },
      "order": 0,
      "backgroundColor": "#f3f4f6",
      "showSeparatorAbove": true,
      "showSeparatorBelow": false,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T12:00:00.000Z"
    }
  ]
}

Common Errors

400 Bad Request: Invalid group IDs or position/size values 404 Not Found: Some group IDs do not belong to this workspace 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired

Move Widget to Group

Method & Path

POST /api/v1/workspace/:workspaceId/dashboard/widgets/:widgetInstanceId/move-to-group

Description

Moves a widget to a different group or makes it standalone. If targetGroupId is null, the widget becomes standalone (removed from any group).

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	The workspace ID
widgetInstanceId	string	Yes	The widget instance ID

Request Body

{
  "targetGroupId": "507f1f77bcf86cd799439011"
}

Fields:

• targetGroupId (string | null, required): The target group ID, or null to make the widget standalone

Response 204 No Content

No response body.

Common Errors

400 Bad Request: Invalid widget instance ID or group ID 404 Not Found: Widget instance or group not found 401 Unauthorized: Authentication required 403 Forbidden: Subscription expired

Grid Layout System

Groups use the same 12-column grid system as widgets:

• Width (w): 1-12 (1 = 1/12 of width, 12 = full width)
• Height (h): Measured in grid units (each unit = 50px by default)
• Position (x, y): Grid coordinates (0-based)

Group Behavior

• Groups are treated as single items in the main dashboard grid
• Groups can be dragged by their header (using the group-drag-handle class)
• Widgets inside groups have their own internal grid layout
• The main auto-arrange feature works on groups and standalone widgets, not on widgets inside groups
• Each group has its own auto-arrange button to organize widgets within the group

Group Features

Background Colors

Groups can have custom background colors to visually distinguish them:

• Use CSS color format (hex, rgb, or named colors)
• Set to null for default background
• Common preset colors: white, light gray, light yellow, light blue, light purple, light pink, light green

Separators

Groups can display visual separators:

• showSeparatorAbove: Shows a horizontal line above the group
• showSeparatorBelow: Shows a horizontal line below the group
• Useful for visually separating different sections of the dashboard

Group Header

Each group has a header that:

• Displays the group name
• Supports RTL/LTR text direction based on locale
• Contains action buttons:
  • Settings button (always visible)
  • Auto-arrange button (visible in edit mode)
• Can be dragged to move the entire group

Related Documentation

• Dashboard Widgets API - Widget management endpoints
• Dashboard Product Documentation - User guide for dashboard features