Dashboards API

Dashboards let you group multiple files together for combined Excel exports — merge all your monthly statements into a single spreadsheet. All endpoints require Clerk JWT authentication.

Dashboard Status

Dashboards track whether their combined outputs are current:

new → (add/remove files) → outdated → (reprocess) → up_to_date

• new — Dashboard created, no files added yet
• outdated — Files were added or removed; combined outputs are stale
• up_to_date — Reprocess completed; combined Excel is current

---

Create Dashboard

POST /dashboards/

Request body:

{
  "name": "Q1 2026 Statements",
  "description": "All bank statements from January to March 2026"
}

Field	Type	Required
name	string	Yes
description	string	No

Response (200):

{
  "id": 15,
  "name": "Q1 2026 Statements",
  "description": "All bank statements from January to March 2026",
  "user_id": 42,
  "status": "new",
  "created_at": "2026-05-09T11:00:00Z",
  "updated_at": "2026-05-09T11:00:00Z"
}

---

List Dashboards

GET /dashboards/

Query parameters:

Param	Type	Default
skip	integer	0
limit	integer	20 (max 100)

curl -H "Authorization: Bearer TOKEN" \
  "https://api.excellent-banking.com/dashboards/?limit=10"

Response (200): Array of DashboardResponse objects.

---

Get Dashboard Details

GET /dashboards/{dashboard_id}

curl -H "Authorization: Bearer TOKEN" \
  https://api.excellent-banking.com/dashboards/15

---

Update Dashboard

PATCH /dashboards/{dashboard_id}

Request body (both optional):

{
  "name": "Q1 Financials",
  "description": "Updated description"
}

---

Delete Dashboard

DELETE /dashboards/{dashboard_id}

Deletes the dashboard but does not delete the associated files — they remain in your Files list. Combined output files in MinIO are also removed.

curl -X DELETE -H "Authorization: Bearer TOKEN" \
  https://api.excellent-banking.com/dashboards/15

Response (200):

{
  "message": "Dashboard deleted successfully"
}

---

Add Files to Dashboard

POST /dashboards/{dashboard_id}/files

Add one or more files to a dashboard. Marks the dashboard as outdated — you’ll need to reprocess to rebuild the combined Excel.

Request body:

{
  "file_ids": [128, 129, 130]
}

All files must belong to the authenticated user. Duplicate additions are silently ignored.

Response (200):

{
  "message": "Added 3 files to dashboard"
}

---

Remove Files from Dashboard

DELETE /dashboards/{dashboard_id}/files

Request body:

{
  "file_ids": [129]
}

Marks the dashboard outdated.

---

List Dashboard Files

GET /dashboards/{dashboard_id}/files

Returns the full FileResponse objects for all files currently assigned to the dashboard.

curl -H "Authorization: Bearer TOKEN" \
  https://api.excellent-banking.com/dashboards/15/files

---

Reprocess Dashboard

POST /dashboards/{dashboard_id}/reprocess

Triggers a background task that merges all dashboard files into combined outputs (JSON, SQLite, Excel). Old combined files in MinIO are deleted before the rebuild starts. Sets dashboard status to up_to_date.

curl -X POST -H "Authorization: Bearer TOKEN" \
  https://api.excellent-banking.com/dashboards/15/reprocess

Response (200):

{
  "message": "Dashboard build started",
  "task_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

If the dashboard has no files, the response is:

{
  "message": "Dashboard is empty, no files to combine"
}

---

Download Dashboard Excel

GET /dashboards/{dashboard_id}/download-excel

Returns a pre-signed GET URL for the combined Excel file. You must have reprocessed first.

Query parameters:

Param	Type	Default	Description
mode	string	merged	merged (single sheet) or separate (one sheet per file)

curl -H "Authorization: Bearer TOKEN" \
  "https://api.excellent-banking.com/dashboards/15/download-excel?mode=merged"

Response (200):

{
  "download_url": "https://minio.example.com/excel/dashboard_id=15/combined_merged.xlsx?X-Amz-..."
}

Errors:

Status	When
404	Dashboard not found or Excel not built yet — reprocess first