Dashboards - Budget Bee

Overview

Dashboards in Budget Bee provide customizable views of financial data, aggregations, and analytics. They enable users to create personalized financial reporting views.

The dashboards resource is planned for future implementation. This documentation describes the intended API structure based on common dashboard patterns.

Base URL

{NEXT_PUBLIC_PG_REST_URL}/dashboards

Authorization

All dashboard endpoints require authentication via JWT token:

Authorization: Bearer {JWT_TOKEN}

Dashboard Schema

uuid

Unique dashboard identifier

name

string

Dashboard name/title

description

string

Dashboard description

layout

jsonb

Dashboard layout configuration (widgets, positions, sizes)

filters

jsonb

Default filters applied to dashboard data

date_range

object

Default date range for dashboard queries

is_default

boolean

Whether this is the default dashboard for the user/org

visibility

string

Dashboard visibility: private, shared, public

user_id

string

Owner user ID

organization_id

string

Organization ID (null for personal dashboards)

created_at

timestamp

Dashboard creation timestamp

updated_at

timestamp

Last update timestamp

List Dashboards

Retrieve all dashboards for the authenticated user or organization.

GET /dashboards

Query Parameters

select

string

Columns to return. Default: *

order

string

Sort order. Example: name.asc or created_at.desc

visibility

string

Filter by visibility level

Request Example

curl -X GET "{NEXT_PUBLIC_PG_REST_URL}/dashboards?order=name.asc" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json"

Response Example

[
  {
    "id": "dash_abc123",
    "name": "Monthly Overview",
    "description": "High-level view of monthly finances",
    "layout": {
      "widgets": [
        {
          "id": "widget_1",
          "type": "summary_cards",
          "position": {"x": 0, "y": 0},
          "size": {"w": 12, "h": 2}
        },
        {
          "id": "widget_2",
          "type": "expense_chart",
          "position": {"x": 0, "y": 2},
          "size": {"w": 8, "h": 4}
        }
      ]
    },
    "filters": {
      "date_range": "last_30_days",
      "categories": []
    },
    "is_default": true,
    "visibility": "private",
    "user_id": "usr_abc123",
    "organization_id": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:22:00Z"
  }
]

Get Dashboard

Retrieve a single dashboard by ID.

GET /dashboards?id=eq.{dashboard_id}

Request Example

curl -X GET "{NEXT_PUBLIC_PG_REST_URL}/dashboards?id=eq.dash_abc123" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Accept: application/vnd.pgrst.object+json"

Create Dashboard

Create a new dashboard.

POST /dashboards

Request Body

name

string

required

Dashboard name

description

string

Dashboard description

layout

object

required

Dashboard layout with widgets

filters

object

Default filters

is_default

boolean

Set as default dashboard

visibility

string

Visibility: private, shared, public

Request Example

curl -X POST "{NEXT_PUBLIC_PG_REST_URL}/dashboards" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{
    "name": "Expense Analysis",
    "description": "Detailed expense breakdown and trends",
    "layout": {
      "widgets": [
        {
          "id": "widget_1",
          "type": "category_breakdown",
          "position": {"x": 0, "y": 0},
          "size": {"w": 6, "h": 4},
          "config": {
            "chart_type": "pie",
            "show_legend": true
          }
        },
        {
          "id": "widget_2",
          "type": "trend_chart",
          "position": {"x": 6, "y": 0},
          "size": {"w": 6, "h": 4},
          "config": {
            "chart_type": "line",
            "grouping": "monthly"
          }
        }
      ]
    },
    "filters": {
      "date_range": "last_90_days",
      "transaction_type": "expense"
    },
    "is_default": false,
    "visibility": "private"
  }'

Response Example

{
  "id": "dash_def456",
  "name": "Expense Analysis",
  "description": "Detailed expense breakdown and trends",
  "layout": {
    "widgets": [
      {
        "id": "widget_1",
        "type": "category_breakdown",
        "position": {"x": 0, "y": 0},
        "size": {"w": 6, "h": 4}
      }
    ]
  },
  "is_default": false,
  "visibility": "private",
  "created_at": "2024-01-21T09:15:00Z"
}

Update Dashboard

Update an existing dashboard.

PATCH /dashboards?id=eq.{dashboard_id}

Request Example

curl -X PATCH "{NEXT_PUBLIC_PG_REST_URL}/dashboards?id=eq.dash_abc123" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{
    "name": "Monthly Financial Overview",
    "layout": {
      "widgets": [
        {
          "id": "widget_1",
          "type": "summary_cards",
          "position": {"x": 0, "y": 0},
          "size": {"w": 12, "h": 2}
        }
      ]
    }
  }'

Delete Dashboard

Delete a dashboard permanently.

DELETE /dashboards?id=eq.{dashboard_id}

Request Example

curl -X DELETE "{NEXT_PUBLIC_PG_REST_URL}/dashboards?id=eq.dash_abc123" \
  -H "Authorization: Bearer {JWT_TOKEN}"

Summary Cards

Show Summary Cards

Display key financial metrics

{
  "type": "summary_cards",
  "config": {
    "metrics": ["total_income", "total_expenses", "net_balance"],
    "comparison_period": "previous_month"
  }
}

Category Breakdown

Show Category Breakdown

Pie or donut chart of spending by category

{
  "type": "category_breakdown",
  "config": {
    "chart_type": "donut",
    "show_legend": true,
    "top_n": 10
  }
}

Trend Chart

Show Trend Chart

Line or bar chart showing trends over time

{
  "type": "trend_chart",
  "config": {
    "chart_type": "line",
    "grouping": "daily",
    "metrics": ["expenses", "income"]
  }
}

Transaction List

Show Transaction List

Recent or filtered transaction list

{
  "type": "transaction_list",
  "config": {
    "limit": 10,
    "filters": {
      "status": "paid"
    },
    "columns": ["date", "name", "amount", "category"]
  }
}

Subscription Overview

Show Subscription Overview

Active subscriptions and costs

{
  "type": "subscription_overview",
  "config": {
    "show_annual_cost": true,
    "group_by": "category"
  }
}

Dashboard Analytics

Dashboards can query aggregated data using PostgREST functions:

Transaction Distribution

POST /rpc/get_transaction_distribution_by_category

{
  "params": {
    "user_id": "usr_abc123",
    "organization_id": null,
    "filters": {
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    }
  }
}

Budget vs Actual

GET /rpc/get_budget_comparison?start_date=2024-01-01&end_date=2024-01-31

Income vs Expenses

GET /rpc/get_cash_flow?grouping=monthly&periods=12

Date Range Presets

Common date range presets for dashboard filters:

today - Current day
yesterday - Previous day
last_7_days - Last 7 days
last_30_days - Last 30 days
this_week - Current week (Mon-Sun)
last_week - Previous week
this_month - Current month
last_month - Previous month
this_quarter - Current quarter
last_quarter - Previous quarter
this_year - Current year
last_year - Previous year
all_time - All available data
custom - Custom date range

Visibility Levels

Private

Only accessible by the creator

Shared

Accessible by organization members

Public

Accessible via public link (read-only)

PATCH /dashboards?id=eq.{dashboard_id}

{
  "visibility": "shared",
  "metadata": {
    "shared_with": ["usr_def456", "usr_ghi789"]
  }
}

Access Control

Dashboard access follows organization role permissions:

Owner, Admin, Editor

Full access: list, get, create, update, delete

Viewer

Can view shared dashboards, cannot create or modify

Best Practices

Dashboard Design

Focus on KPIs - Display the most important metrics prominently
Logical grouping - Group related widgets together
Consistent styling - Use consistent colors and chart types
Performance - Limit widgets per dashboard (8-12 max)

Clear titles - Use descriptive widget titles
Appropriate charts - Choose chart types that match the data
Date ranges - Set sensible default date ranges
Drill-down - Enable clicking to view details

Organization

Multiple dashboards - Create dashboards for different purposes
Default dashboard - Set a default for quick access
Regular updates - Review and update dashboard layouts
Share insights - Use shared dashboards for team collaboration

Authentication

Resources

​Overview

​Base URL

​Authorization

​Dashboard Schema

​List Dashboards

​Query Parameters

​Request Example

​Response Example

​Get Dashboard

​Request Example

​Create Dashboard

​Request Body

​Request Example

​Response Example

​Update Dashboard

​Request Example

​Delete Dashboard

​Request Example

​Widget Types

​Summary Cards

​Category Breakdown

​Trend Chart

​Transaction List

​Subscription Overview

​Dashboard Analytics

​Transaction Distribution

​Budget vs Actual

​Income vs Expenses

​Date Range Presets

​Dashboard Sharing

​Visibility Levels

Private

Shared

Public

​Share Dashboard

​Access Control

Owner, Admin, Editor

Viewer

​Best Practices

​Dashboard Design

​Widget Configuration

​Organization

Build docs developers (and LLMs) love

Overview

Base URL

Authorization

Dashboard Schema

List Dashboards

Query Parameters

Request Example

Response Example

Get Dashboard

Request Example

Create Dashboard

Request Body

Request Example

Response Example

Update Dashboard

Request Example

Delete Dashboard

Request Example

Widget Types

Summary Cards

Category Breakdown

Trend Chart

Transaction List

Subscription Overview

Dashboard Analytics

Transaction Distribution

Budget vs Actual

Income vs Expenses

Date Range Presets

Dashboard Sharing

Visibility Levels

Share Dashboard

Access Control

Best Practices

Dashboard Design

Widget Configuration

Organization