Dashboards API

Quick Reference

• Base URL: https://insights.omisell.com/api/v1/dashboards
• Auth: Authorization: Omi <token>
• Content-Type: application/json

Endpoints Overview

Method	Endpoint	Mô tả	Auth
GET	/api/v1/dashboards/	Danh sách dashboards	Yes
POST	/api/v1/dashboards/	Tạo dashboard	Yes
GET	/api/v1/dashboards/{id}	Chi tiết dashboard	Yes
PATCH	/api/v1/dashboards/{id}	Cập nhật dashboard	Yes
DELETE	/api/v1/dashboards/{id}	Xoá dashboard	Yes
GET	/api/v1/dashboards/{id}/widgets	Danh sách widgets	Yes
POST	/api/v1/dashboards/{id}/widgets	Tạo widget	Yes
PATCH	/api/v1/dashboards/{id}/widgets/{wid}	Cập nhật widget	Yes
DELETE	/api/v1/dashboards/{id}/widgets/{wid}	Xoá widget	Yes
POST	/api/v1/dashboards/{id}/widgets/{wid}/refresh	Refresh widget data	Yes
GET	/api/v1/dashboards/subscriptions	Tất cả subscriptions	Yes
GET	/api/v1/dashboards/{id}/subscriptions	Subscriptions của dashboard	Yes
POST	/api/v1/dashboards/{id}/subscriptions	Tạo subscription	Yes
PATCH	/api/v1/dashboards/subscriptions/{subId}	Toggle subscription	Yes
DELETE	/api/v1/dashboards/subscriptions/{subId}	Xoá subscription	Yes

---

Dashboard CRUD

GET /api/v1/dashboards/

Danh sách tất cả dashboards user có quyền xem.

Response (200 OK): Dashboard[]

Field	Type	Mô tả
id	string	ID dashboard
tenant_id	string	ID tenant
name	string	Tên dashboard
description	string?	Mô tả
created_by	string	User ID người tạo
created_by_name	string	Tên người tạo
is_shared	boolean	Đã chia sẻ?
shared_with_emails	string[]?	Email được chia sẻ
widget_ids	string[]	Danh sách widget IDs
global_filter_presets	GlobalFilterPreset[]	Bộ filter presets
active_preset_id	string?	Preset đang active
created_at	string	Thời gian tạo (ISO)
updated_at	string	Thời gian cập nhật (ISO)

Source: (api.service.ts:160-162)

POST /api/v1/dashboards/

Tạo dashboard mới. Yêu cầu role Owner/Admin.

Request Body: DashboardCreateRequest

Field	Type	Required	Mô tả
name	string	Yes	Tên dashboard
description	string?	No	Mô tả
is_shared	boolean?	No	Chia sẻ công khai (default: false)

Response (201 Created): Dashboard

Source: (api.service.ts:168-169)

PATCH /api/v1/dashboards/:id

Cập nhật dashboard (tên, mô tả, sharing, filter presets).

Request Body: Partial<Dashboard>

Response (200 OK): Dashboard (updated)

Source: (api.service.ts:172-173)

DELETE /api/v1/dashboards/:id

Xoá dashboard và tất cả widgets. Yêu cầu role Owner/Admin hoặc là người tạo.

Response: 204 No Content

Source: (api.service.ts:176-178)

---

Widget CRUD

GET /api/v1/dashboards/:id/widgets

Danh sách widgets của dashboard.

Response (200 OK): DashboardWidget[]

Field	Type	Mô tả
id	string	ID widget
dashboard_id	string	ID dashboard
title	string	Tiêu đề widget
widget_type	'chart' | 'table' | 'kpi'	Loại widget
display_size	'small' | 'medium' | 'large' | 'full'	Kích thước
data_source	'live_insight' | 'snapshot'	Nguồn dữ liệu
insight_code	string?	Mã insight (nếu live)
granularity	string?	Mức thời gian
widget_filters	Record<string, unknown>?	Bộ lọc riêng
snapshot_data	DataRow[]?	Dữ liệu snapshot
snapshot_chart_hint	ChartHint?	Chart hint cho snapshot
snapshot_question	string?	Câu hỏi AI gốc
chart_hint	ChartHint?	Chart hint hiện tại
chart_hint_override	{ chart_type?: ChartType }?	Override chart type
created_at	string	Thời gian tạo
last_refreshed_at	string?	Lần refresh cuối

Source: (api.service.ts:181-184)

POST /api/v1/dashboards/:id/widgets

Tạo widget mới.

Request Body: DashboardWidgetCreateRequest

Field	Type	Required	Default	Mô tả
title	string	Yes	—	Tiêu đề
widget_type	string	Yes	—	chart, table, kpi
display_size	string?	No	medium	small, medium, large, full
data_source	string	Yes	—	live_insight hoặc snapshot
insight_code	string?	No	—	Mã insight (khi live)
granularity	string?	No	—	Mức thời gian
widget_filters	object?	No	—	Bộ lọc
snapshot_data	DataRow[]?	No	—	Dữ liệu snapshot
snapshot_chart_hint	ChartHint?	No	—	Chart hint cho snapshot
snapshot_question	string?	No	—	Câu hỏi AI gốc
chart_hint	ChartHint?	No	—	Chart hint

Response (201 Created): DashboardWidget

Source: (api.service.ts:187-194)

POST /api/v1/dashboards/:id/widgets/:wid/refresh

Refresh dữ liệu widget (chỉ áp dụng cho live_insight).

Request Body (optional):

Field	Type	Mô tả
granularity	string?	Override granularity
filters	Record<string, unknown>?	Override filters

Response (200 OK): ExecuteResponse

Source: (api.service.ts:214-223)

---

Dashboard Subscriptions (Scheduled Reports)

GET /api/v1/dashboards/subscriptions

Lấy tất cả dashboard subscriptions (cho trang Settings).

Response (200 OK): DashboardSubscription[]

Source: (api.service.ts:232-235)

GET /api/v1/dashboards/:id/subscriptions

Lấy subscriptions của một dashboard cụ thể.

Response (200 OK): DashboardSubscription[]

Field	Type	Mô tả
id	string	ID subscription
dashboard_id	string	ID dashboard
dashboard_name	string	Tên dashboard
channel_ids	string[]	Danh sách channel IDs
schedule	'daily' | 'weekly' | 'monthly'	Tần suất
schedule_time	string	Giờ gửi (HH:mm, UTC)
schedule_day_of_week	number?	0=CN, 1=T2...6=T7 (weekly)
schedule_day_of_month	number?	1-31 (monthly)
is_active	boolean	Đang hoạt động?
created_at	string	Thời gian tạo

Source: (api.service.ts:226-229)

POST /api/v1/dashboards/:id/subscriptions

Tạo scheduled report cho dashboard.

Request Body: DashboardSubscriptionCreateRequest

Field	Type	Required	Mô tả
dashboard_id	string	Yes	ID dashboard
dashboard_name	string	Yes	Tên dashboard
channel_ids	string[]	Yes	Kênh nhận
schedule	string	Yes	daily, weekly, monthly
schedule_time	string	Yes	Giờ gửi (HH:mm UTC)
schedule_day_of_week	number?	weekly only	0-6
schedule_day_of_month	number?	monthly only	1-31

Response (201 Created): DashboardSubscription

Source: (api.service.ts:238-245)

PATCH /api/v1/dashboards/subscriptions/:subId

Toggle subscription on/off.

Request Body: { "is_active": boolean }

Source: (api.service.ts:247-251)

DELETE /api/v1/dashboards/subscriptions/:subId

Xoá subscription.

Response: 204 No Content

Source: (api.service.ts:254-257)

Liên kết

• API Index — Tổng quan API
• Notifications API — Channels & insight subscriptions
• SOP: Dashboards — Hướng dẫn sử dụng