Dashboards are the primary organizational unit in Forge. Each dashboard can contain multiple widgets and belongs to a single user.
Create Dashboard
curl -X POST http://localhost:3000/api/dashboards \
-H "Content-Type: application/json" \
-H "Cookie: session=your-session-token" \
-d '{
"name": "My Dashboard"
}'
Request Body
Dashboard name (minimum 1 character)
Response
Unique dashboard identifier
ID of the user who owns this dashboard
Whether the dashboard is publicly accessible (default: false)
Success (200)
Error (400)
Error (401)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userId": "user123",
"name": "My Dashboard",
"isPublic": false,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
Get Dashboards
Retrieve all dashboards for the authenticated user, or a specific dashboard by ID.
curl -X GET http://localhost:3000/api/dashboards \
-H "Cookie: session=your-session-token"
Query Parameters
Dashboard ID to retrieve. If omitted, returns all user dashboards.
Response
Returns an array of dashboard objects.
Success (200)
Error (403)
Error (404)
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userId": "user123",
"name": "My Dashboard",
"isPublic": false,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
]
User does not own the requested dashboard. { "error": "Dashboard not found" }
Update Dashboard
curl -X PUT http://localhost:3000/api/dashboards \
-H "Content-Type: application/json" \
-H "Cookie: session=your-session-token" \
-d '{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Updated Dashboard Name"
}'
Request Body
New dashboard name (minimum 1 character)
Response
Returns the updated dashboard object.
Success (200)
Error (400)
Error (403)
Error (404)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userId": "user123",
"name": "Updated Dashboard Name",
"isPublic": false,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T11:45:00.000Z"
}
{ "error": "Dashboard not found or could not be updated" }
Delete Dashboard
Deletes a dashboard and all associated widgets.
curl -X DELETE "http://localhost:3000/api/dashboards?id=550e8400-e29b-41d4-a716-446655440000" \
-H "Cookie: session=your-session-token"
Query Parameters
Response
Returns the deleted dashboard object.
This action is permanent and will also delete all widgets on the dashboard.
Success (200)
Error (400)
Error (403)
Error (404)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userId": "user123",
"name": "My Dashboard",
"isPublic": false,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
{ "error": "Dashboard not found or could not be deleted" }