API Reference
Dashboard Overview (v2)
Overview
Fetch the v2 dashboard overview for your tenant workspace. This is the newer overview contract under the /api/v2 path and is intended for updated admin dashboards.
Like v1, it requires a client Access Token with tenant admin privileges and must be called with tenant headers.
When to use this endpoint?
Use Dashboard Overview (v2) when:
- You are building or migrating to the newer dashboard overview API.
- Your integration targets
/api/v2/dashboard/overviewinstead of the versioned v1-style path. - You need the same high-level tenant snapshot with the v2 response contract.
If you are still on the original overview, continue using Dashboard → Overview (/api/{apiVersion}/dashboard/overview). Prefer v2 for new dashboard work.
What's Different from v1?
| Aspect | Overview (v1) | Overview (v2) |
|---|---|---|
| URL | /api/{apiVersion}/dashboard/overview | /api/v2/dashboard/overview |
| Auth | Client Bearer token + tenant headers | Client Bearer token + tenant headers |
| Purpose | Combined users / conversations / messages snapshot | Newer overview contract for updated dashboards |
{baseUrl}/api/v2/dashboard/overviewAuthentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer <access_token> | Client Access Token with tenant admin privileges. |
| is-tenant | true | Targets the tenant DB ("true", needs x-client-id). |
| x-client-id | {{clientId}} | Tenant (client) id. Uses the {{clientId}} variable. |
Common Errors
Same authentication rules as the v1 overview — missing tokens or non-admin client access are rejected.
HTTP 403 Forbidden — Tenant admin required
{
"success": false,
"message": "Access denied: tenant admin privileges required",
"data": null,
"error": null
}| Code | Reason |
|---|---|
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 403 Forbidden | Access denied: tenant admin privileges required. |
| 500 Internal Server Error | An unexpected error occurred while building the v2 overview. |
Best Practices
- Use v2 for new dashboard work; keep v1 only while migrating existing screens.
- Do not mix v1 and v2 response parsers in the same UI component.
- Always send tenant headers with a client Bearer token over HTTPS.
- If you only need one metric type, prefer the dedicated Users / Conversations / Messages metrics endpoints.
Ready for v2
Point your dashboard client at /api/v2/dashboard/overview and map the returned summary into your KPI cards. For deep-dives, continue with the individual metrics endpoints under Dashboard.