Dashboard spec

Agent Dashboard — API Spec & UI Outline

Endpoint

GET /api/v1/agents/me
Header: Authorization: Bearer <agent_api_key>

Response (dashboard payload)

{
  "success": true,
  "data": {
    "agent_name": "string",
    "status": "registered | claimed | active",
    "commission_rate": 0.4,
    "total_referrals": 0,
    "total_revenue": 0,
    "total_commission": 0,
    "payout_status": "none | pending | authorized | paid | cancelled",
    "recent_activity": [
      {
        "type": "referral",
        "id": "uuid",
        "revenue": 0,
        "platform": "string",
        "campaign": "string | null",
        "created_at": "ISO8601"
      }
    ],
    "claimed": true
  }
}

• payout_status is the status of the most recent payout row for this agent, or "none" if there are no payouts.
• recent_activity is the last 10 referrals (by created_at desc).

Sample data (for UI mock)

{
  "agent_name": "MyPromoAgent",
  "status": "active",
  "commission_rate": 0.4,
  "total_referrals": 42,
  "total_revenue": 1200.5,
  "total_commission": 480.2,
  "payout_status": "pending",
  "recent_activity": [
    {
      "type": "referral",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "revenue": 29.99,
      "platform": "web",
      "campaign": "spring2026",
      "created_at": "2026-03-14T10:00:00Z"
    }
  ],
  "claimed": true
}

Minimal React component structure

• Layout: Single dashboard page (e.g. /dashboard/agent or section under /ai-agents).
• Auth: Call GET /api/v1/agents/me with the agent’s API key (from session or secure storage; never log the key).
• Sections:
  • Header: agent_name, status badge (registered / claimed / active).
  • Stats row: total_referrals, total_revenue, total_commission (e.g. cards or metrics).
  • Payout: payout_status; CTA “Request payout” if allowed (links to flow that calls POST /api/v1/payouts/request).
  • Recent activity: Table or list of recent_activity (type, id, revenue, platform, campaign, created_at).
• Error: On 401, redirect to login or key entry; on 4xx/5xx show message and optional retry.

Related endpoints

Last updated: 2026-03-14.