Skip to content
UltimateTeam.ai Docs

HQ nerve center

GET
/api/v1/dashboard/hq
curl --request GET \
  --url https://api.ultimateteam.ai/api/v1/dashboard/hq \
  --header 'X-API-Key: <X-API-Key>'

Aggregated dashboard with runway, metrics, briefing, approvals, activity, and celebrations.

Authorizations

Section titled “Authorizations”

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful Response

Media typeapplication/json
HQDashboardResponse

Response for GET /api/v1/dashboard/hq.

object
data
required
HQDashboardData

Full HQ nerve center payload.

Attributes: runway: Condensed runway health snapshot. metrics: Key business metrics at a glance. brief: Today’s CEO briefing items. None while the welcome-mode tenant has not yet had its first morning-brief cadence run – distinct from [] (cadence ran but produced zero items). v49.0 LBF-02 fix: schema previously rejected None and /api/v1/dashboard/hq 5xx’d on day-0 fresh tenants. approvals: Actions awaiting human approval. activity: Recent agent activity feed. celebrations: Celebration-worthy events. welcome_mode: Welcome-state payload for fresh tenants. None once the tenant ages past the welcome window OR emits a CONNECTOR_AUTHORIZED event (per Plan 209-01 D-01/D-04).

object
activity
Activity
Array<object>
ActivityItem

A single recent activity entry.

Attributes: agent_role: Which agent performed the activity. action: Short description of what was done. timestamp: When this activity occurred.

object
action
required
Action
string
agent_role
required
Agent Role
string
timestamp
Any of:
string format: date-time
approvals
Approvals
Array<object>
ApprovalItem

An action awaiting human approval.

Attributes: id: Queue item identifier. agent_role: Which agent is requesting approval. action_type: Category of the action. description: Plain-language summary of the request. urgency: How time-sensitive this approval is. created_at: When the request was created.

object
action_type
required
Action Type
string
agent_role
required
Agent Role
string
created_at
Any of:
string format: date-time
description
required
Description
string
id
required
Id
string
urgency
Urgency
string
default: normal
brief
Any of:
Array<object>
BriefItem

A single item in the daily CEO briefing.

Attributes: title: Short headline. body: Summary text. category: Topic category (revenue, operations, etc.). urgency: Importance level (info/action/critical).

object
body
required
Body
string
category
Category
string
default: general
title
required
Title
string
urgency
Urgency
string
default: info
celebrations
Celebrations
Array<object>
CelebrationItem

A celebration-worthy event to surface on the dashboard.

Attributes: type: Category (milestone/streak/improvement/team). title: Short headline. message: Full celebration message. importance: Significance level (high/medium/low).

object
importance
Importance
string
default: medium
message
required
Message
string
title
required
Title
string
type
required
Type
string
metrics
Metrics
Array<object>
MetricSnapshot

A single top-level business metric.

Attributes: label: Human-readable metric name. value: Current metric value, or null when no measurement is available. change_pct: Percentage change from prior period. period: Comparison period (e.g. ‘7d’, ‘30d’).

object
change_pct
Any of:
number
label
required
Label
string
period
Period
string
default: 7d
value
required
Any of:
number
runway
RunwaySummary

Condensed runway info for the HQ dashboard.

Attributes: runway_days: Estimated days of cash remaining. status: Color-coded health level (green/yellow/orange/red). trend: Direction of runway change (improving/stable/declining).

object
data_status
Data Status
string
default: unavailable
reason
Any of:
string
runway_days
Any of:
integer
status
Status
string
default: unknown
trend
Trend
string
default: unknown
welcome_mode
Any of:
WelcomeModePayload

Welcome-state payload for fresh tenants (D-01, D-04).

Returned inside :class:HQDashboardData when the tenant is in the 7-day welcome window AND has emitted no CONNECTOR_AUTHORIZED event. None (i.e. omitted) once either gate flips, after which the operational HQ composition renders.

Attributes: is_first_day: True iff tenant.created_at >= now() - 24h. Used by the UI to decide between the “Day-1” celebration voice and the “still inside the 7-day window” voice. tenant_age_hours: Whole-hour age of the tenant since tenant.created_at. Floors at 0 to keep the field non-negative even under clock skew. featured_checklist_item_id: The single checklist item id that the welcome HQ visually emphasises (UI-SPEC §1.4 — the “next-undone” item with gold tint + chevron). Constant "setup_first_integration" per Phase 209 funnel target. next_steps: Exactly three :class:NextStepCard instances with verbatim UI-SPEC §5.3 copy.

object
featured_checklist_item_id
required
Featured Checklist Item Id
string
Allowed value: setup_first_integration
is_first_day
required
Is First Day
boolean
next_steps
required
Next Steps
Array<object>
NextStepCard

One of the three “What happens next” cards on the welcome HQ.

Surfaced in :class:WelcomeModePayload only when the tenant qualifies for welcome mode (see UI-SPEC §5.3 for the verbatim copy strings).

Attributes: id: Stable card identifier (used by the frontend for keys/analytics). title: Card heading (text-sm font-semibold per UI-SPEC §5.3). body: Card body copy (text-xs text-muted-foreground). icon: Lucide icon hint – the frontend maps this to a concrete icon component (UI-SPEC §1.4 reserves three: plug/eye/check).

object
body
required
Body
string
icon
required
Icon
string
Allowed values: plug eye check
id
required
Id
string
title
required
Title
string
tenant_age_hours
required
Tenant Age Hours
integer
meta
ApiMeta

Standard metadata included in every API response.

Attributes: request_id: Unique identifier for request tracing. timestamp: UTC timestamp of the response.

object
request_id
Request Id

Unique identifier for request tracing

string
timestamp
Timestamp

UTC timestamp of the response

string format: date-time
Example
{
  "data": {
    "approvals": [
      {
        "urgency": "normal"
      }
    ],
    "brief": [
      {
        "category": "general",
        "urgency": "info"
      }
    ],
    "celebrations": [
      {
        "importance": "medium"
      }
    ],
    "metrics": [
      {
        "period": "7d"
      }
    ],
    "runway": {
      "data_status": "unavailable",
      "reason": "Accounting observations are unavailable",
      "status": "unknown",
      "trend": "unknown"
    },
    "welcome_mode": {
      "featured_checklist_item_id": "setup_first_integration",
      "next_steps": [
        {
          "icon": "plug"
        }
      ]
    }
  }
}