Dashboards

The Dashboards API lets you save chat conversations as dashboards, publish them publicly, and manage refresh settings.

Save Dashboard

POST /api/v1/analytics/dashboards

Save a chat conversation as a dashboard.

Request:

{
  "conversationId": "conv_abc123",
  "title": "Q3 Revenue Dashboard"
}

Response:

{
  "success": true,
  "dashboard": {
    "id": "dash_xyz789",
    "title": "Q3 Revenue Dashboard",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

List Dashboards

GET /api/v1/analytics/dashboards

List all dashboards for your organization.

Response:

{
  "success": true,
  "dashboards": [
    {
      "id": "dash_xyz789",
      "title": "Q3 Revenue Dashboard",
      "isDashboard": true,
      "isPublic": false,
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Publish Dashboard

POST /api/v1/analytics/dashboards/:id/publish

Make a dashboard publicly accessible via a shareable URL.

Request:

{
  "password": "optional-password"
}

Response:

{
  "success": true,
  "slug": "q3-revenue-abc123",
  "publicUrl": "https://app.ballast.sh/public/dashboards/q3-revenue-abc123"
}

Password Protection

Published dashboards can require a password. If set, viewers must enter the password to access the dashboard.

Unpublish Dashboard

DELETE /api/v1/analytics/dashboards/:id/publish

Remove public access to a dashboard.

Clone Dashboard

POST /api/v1/analytics/dashboards/:id/clone

Create a copy of a dashboard.

Response:

{
  "success": true,
  "dashboard": {
    "id": "dash_newid",
    "title": "Q3 Revenue Dashboard (Copy)"
  }
}

Refresh Settings

GET /api/v1/analytics/dashboards/:id/refresh

Get the auto-refresh settings for a dashboard.

Response:

{
  "success": true,
  "refreshEnabled": true,
  "refreshInterval": 900,
  "lastRefreshedAt": "2024-01-15T10:00:00Z"
}

PUT /api/v1/analytics/dashboards/:id/refresh

Update auto-refresh settings.

Request:

{
  "refreshEnabled": true,
  "refreshInterval": 3600
}

Interval	Description
300	Every 5 minutes
900	Every 15 minutes
3600	Every hour
86400	Daily

POST /api/v1/analytics/dashboards/:id/refresh

Trigger an immediate refresh of all charts in the dashboard.

Public Dashboard Access

POST /api/v1/public/dashboards/:slug

Access a published dashboard (no authentication required).

Request:

{
  "password": "if-required"
}

Response:

Returns the dashboard content including all charts and data.

Error Responses

Status	Error	Description
401	unauthorized	Invalid authentication
403	forbidden	No access to dashboard
403	password_required	Published dashboard requires password
404	not_found	Dashboard doesn’t exist