Widgets are individual components placed on dashboards. Each widget has a type, size, position, and optional configuration.
Supported widget types:
Bookmark - Quick linksClock - Time displayCountdown - Countdown timerCrypto - Cryptocurrency pricesEditor - Text editorFrame - Embedded iframeGithub Heatmap - GitHub contribution heatmapGithub - GitHub statisticsInbox - Email inboxKanban - Kanban boardMeetings - Calendar meetingsTodo - Todo listWeather - Weather information
curl -X POST http://localhost:3000/api/widgets \
-H "Content-Type: application/json" \
-H "Cookie: session=your-session-token" \
-d '{
"dashboardId": "550e8400-e29b-41d4-a716-446655440000",
"widgetType": "Todo",
"height": 400,
"width": 300,
"positionX": 0,
"positionY": 0,
"config": {
"title": "My Tasks"
}
}'
Request Body
ID of the dashboard to add the widget to
Type of widget (see Widget Types above)
Horizontal position on the dashboard
Vertical position on the dashboard
Widget-specific configuration (key-value pairs)
Response
ID of the user who owns this widget
ID of the parent dashboard
Success (200)
Error (400)
Error (403)
Error (404)
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"userId": "user123",
"dashboardId": "550e8400-e29b-41d4-a716-446655440000",
"widgetType": "Todo",
"height": 400,
"width": 300,
"positionX": 0,
"positionY": 0,
"config": {
"title": "My Tasks"
},
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
User does not own the specified dashboard. { "error": "Dashboard not found" }
Retrieve all widgets for the authenticated user, or widgets from a specific dashboard.
curl -X GET http://localhost:3000/api/widgets \
-H "Cookie: session=your-session-token"
Query Parameters
Dashboard ID to retrieve widgets from. If omitted, returns all user widgets.
Response
Returns an array of widget objects.
Success (200)
Error (403)
Error (404)
[
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"userId": "user123",
"dashboardId": "550e8400-e29b-41d4-a716-446655440000",
"widgetType": "Todo",
"height": 400,
"width": 300,
"positionX": 0,
"positionY": 0,
"config": {
"title": "My Tasks"
},
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
]
{ "error": "Dashboard not found" }
curl -X PUT http://localhost:3000/api/widgets \
-H "Content-Type: application/json" \
-H "Cookie: session=your-session-token" \
-d '{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"height": 500,
"width": 350,
"positionX": 100,
"positionY": 50,
"config": {
"title": "Updated Tasks"
}
}'
Request Body
New widget height in pixels
New widget width in pixels
Updated widget configuration
Response
Returns the updated widget object.
Success (200)
Error (400)
Error (403)
Error (404)
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"userId": "user123",
"dashboardId": "550e8400-e29b-41d4-a716-446655440000",
"widgetType": "Todo",
"height": 500,
"width": 350,
"positionX": 100,
"positionY": 50,
"config": {
"title": "Updated Tasks"
},
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T11:45:00.000Z"
}
{ "error": "Widget not found or could not be updated" }
curl -X DELETE "http://localhost:3000/api/widgets?id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "Cookie: session=your-session-token"
Query Parameters
Response
Returns the deleted widget object.
Success (200)
Error (400)
Error (403)
Error (404)
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"userId": "user123",
"dashboardId": "550e8400-e29b-41d4-a716-446655440000",
"widgetType": "Todo",
"height": 500,
"width": 350,
"positionX": 100,
"positionY": 50,
"config": {
"title": "Updated Tasks"
},
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T11:45:00.000Z"
}
{ "error": "Widget not found or could not be deleted" }