Skip to main content

​
Get Project Dashboard Data

​
projectId
string
required
The ID of the project whose dashboard data to retrieve

​
Request

GET /api/projects/{projectId}/dashboard

​
Authentication

Requires an active session. Users can only access dashboard data for projects they own.

​
Response

​
project
object
Complete project information including connections
​
id
string
Project identifier
​
title
string
Project title
​
description
string
Project description
​
isPublic
boolean
Public visibility status
​
idPublic
string | null
Public sharing ID (null if not public)
​
orderedWidgetIds
string[]
Array of widget IDs in display order
​
databases
array
Array of decrypted database connection objects
​
schemas
object
Map of connection IDs to their database schemas
​
{connectionId}
object
Database schema object for each valid connection
​
tables
array
Array of table definitions with columns and relationships
​
widgets
array
Array of all widgets in the project
​
id
string
Widget identifier
​
projectId
string
Parent project ID
​
type
string
Widget type
​
title
string
Widget title
​
configs
object
Widget configuration
​
query
string | null
SQL query (if applicable)
​
connectionId
string | null
Associated database connection
​
connections
array
Array of database connection objects (same as project.databases)
​
orderedWidgetIds
string[]
Array of widget IDs in their display order

​
Example

const response = await fetch('/api/projects/proj_abc123/dashboard', {
  method: 'GET',
  credentials: 'include'
});

const data = await response.json();

{
  "project": {
    "id": "proj_abc123",
    "title": "Sales Dashboard",
    "description": "Q4 2025 sales metrics",
    "isPublic": false,
    "idPublic": null,
    "orderedWidgetIds": ["widget_1", "widget_2", "widget_3"],
    "databases": [
      {
        "id": "conn_xyz789",
        "title": "PostgreSQL Production",
        "host": "db.example.com",
        "port": 5432,
        "database": "sales_db",
        "user": "app_user",
        "password": "",
        "isExisting": true,
        "status": "valid"
      }
    ]
  },
  "schemas": {
    "conn_xyz789": {
      "tables": [
        {
          "name": "sales",
          "columns": [
            { "name": "id", "type": "integer" },
            { "name": "product", "type": "varchar" },
            { "name": "amount", "type": "decimal" }
          ]
        }
      ]
    }
  },
  "widgets": [
    {
      "id": "widget_1",
      "projectId": "proj_abc123",
      "type": "DataTable",
      "title": "Recent Sales",
      "configs": { "pageSize": 10 },
      "query": "SELECT * FROM sales ORDER BY created_at DESC",
      "connectionId": "conn_xyz789"
    }
  ],
  "connections": [
    {
      "id": "conn_xyz789",
      "title": "PostgreSQL Production",
      "host": "db.example.com",
      "port": 5432,
      "database": "sales_db",
      "user": "app_user",
      "password": "",
      "isExisting": true,
      "status": "valid"
    }
  ],
  "orderedWidgetIds": ["widget_1", "widget_2", "widget_3"]
}
Database connection passwords are always returned as empty strings for security. The schemas object only includes connections that have been successfully validated and introspected.

​
Update Widget Order

​
projectId
string
required
The ID of the project whose widget order to update
​
orderedWidgetIds
string[]
required
Array of widget IDs in the desired display order

​
Request

PUT /api/projects/{projectId}/widgets/order

​
Authentication

Requires an active session. Only the project owner can update widget order.

​
Request Body

{
  "orderedWidgetIds": ["widget_3", "widget_1", "widget_2"]
}

​
Response

​
success
boolean
Indicates if the operation was successful

​
Example

const response = await fetch('/api/projects/proj_abc123/widgets/order', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    orderedWidgetIds: ['widget_3', 'widget_1', 'widget_2']
  })
});

const data = await response.json();

{
  "success": true
}
The widget order determines how widgets are displayed on the project dashboard. The order is preserved in the project’s orderedWidgetIds field.

​
Use Cases

​
Loading a Dashboard

To load a complete dashboard with all necessary data:
  1. Call GET /api/projects/{projectId}/dashboard to fetch:
    • Project metadata and settings
    • All widgets with their configurations
    • Database schemas for building queries
    • Widget display order
  2. Use the orderedWidgetIds array to display widgets in the correct order
  3. Reference the schemas object when building or editing SQL queries

​
Reordering Widgets

When users drag and drop widgets to reorder them:
  1. Update the local state with the new order
  2. Call PUT /api/projects/{projectId}/widgets/order with the new orderedWidgetIds array
  3. The dashboard will reflect the new order on next load

​
Security Considerations

All dashboard endpoints require authentication and verify project ownership. Users cannot access dashboard data for projects they don’t own.
  • Database credentials are encrypted in the database
  • Passwords are never returned in API responses (always empty strings)
  • Only validated database connections are included in schemas
  • SQL queries are executed server-side to prevent direct database access

Build docs developers (and LLMs) love

Get started for freeTalk to us