# Business Metrics API Reference

## Base URL
```
https://api.lilith.platform/observability/v1/metrics
```

## Authentication
All metrics endpoints require valid service or user authentication.

```bash
export LILITH_TOKEN="your-api-token"
curl -H "Authorization: Bearer $LILITH_TOKEN" \
     ${API_BASE}/metrics/dashboards/business
```

## Endpoints

### Business Dashboard

```http
GET /v1/metrics/dashboards/business
Authorization: Bearer <token>
```

Returns comprehensive business KPI dashboard with real-time metrics.

**Response Example:**
```json
{
  "dashboard_type": "business",
  "generated_at": "2024-01-01T12:00:00Z",
  "kpis": {
    "user_engagement": { "dau": 2847, "wau": 15632, "mau": 45891 },
    "conversion": { "signup_conversion_24h": 3.2 },
    "revenue": { "revenue_30d_usd": 127849.50 }
  }
}
```

### Business Reports

```http
GET /v1/metrics/reports/business?period={period}&format={format}
Authorization: Bearer <token>
```

**Parameters:**
- `period`: `7d` | `30d` | `90d` | `1y`
- `format`: `json` | `csv` | `pdf`

**Response Example:**
```json
{
  "report_type": "business_kpi",
  "period": "30d",
  "generated_at": "2024-01-01T12:00:00Z",
  "kpis": {
    "summary": {
      "dau_avg": 2654,
      "mau_growth": 23.1,
      "revenue_total": 127849.50
    },
    "trends": [
      {"date": "2024-01-01", "dau": 2847, "revenue": 4251.50},
      {"date": "2024-01-02", "dau": 2793, "revenue": 4184.20}
    ]
  },
  "insights": [
    {
      "category": "user_growth",
      "insight": "DAU growth accelerating (+12.5% vs +8.1% previous period)",
      "recommendation": "Continue current user acquisition strategy"
    }
  ]
}
```

### KPI Historical Data

```http
GET /v1/metrics/kpis/{kpi_name}/history?period={period}&granularity={granularity}
Authorization: Bearer <token>
```

**Parameters:**
- `kpi_name`: Any valid KPI (e.g., `dau`, `conversion_rate`, `revenue_30d`)
- `period`: Time range (`7d`, `30d`, `90d`)
- `granularity`: Data points (`hour`, `day`, `week`)

### Real-time Metrics

```http
GET /v1/metrics/realtime?kpis={kpi_list}
Authorization: Bearer <token>
```

**Example:**
```bash
curl "$API_BASE/metrics/realtime?kpis=dau,conversion_rate,revenue_30d"
```

## Data Sources

### Analytics Events
All KPIs are calculated from analytics events ingested via:

```http
POST /v1/analytics/events
Content-Type: application/json
Authorization: Bearer <token>

{
  "event_type": "session.started",
  "user_hash": "sha256_hash_of_user_id",
  "session_id": "ses_1234567890",
  "timestamp": "2024-01-01T12:00:00Z",
  "context": {
    "platform": "web",
    "user_agent": "Mozilla/5.0...",
    "referrer": "https://google.com"
  },
  "consent": true
}
```

### Event Schema Validation

All analytics events must conform to the schema:

```javascript
const eventSchema = {
  event_type: {
    type: 'string',
    required: true,
    enum: [
      'session.started', 'session.ended',
      'signup.started', 'signup.completed',
      'chat.message_sent', 'chat.session_ended',
      'voice.session_started', 'voice.session_ended',
      'meditation.started', 'meditation.completed',
      'payment.started', 'payment.completed'
    ]
  },
  user_hash: { type: 'string', pattern: /^[a-f0-9]{64}$/ },
  session_id: { type: 'string', required: true },
  timestamp: { type: 'string', format: 'iso8601' },
  consent: { type: 'boolean', required: true }
};
```

## Error Handling

### Common Errors

| Status | Error | Description |
|--------|-------|-------------|
| 400 | `invalid_period` | Invalid time period specified |
| 401 | `unauthorized` | Missing or invalid authentication |
| 403 | `insufficient_permissions` | Insufficient access permissions |
| 404 | `kpi_not_found` | Requested KPI does not exist |
| 429 | `rate_limited` | Too many requests |
| 500 | `calculation_error` | Error calculating KPI |

### Error Response Format

```json
{
  "error": {
    "code": "invalid_period",
    "message": "Period must be one of: 7d, 30d, 90d, 1y",
    "details": {
      "provided": "invalid_period",
      "valid_options": ["7d", "30d", "90d", "1y"]
    }
  }
}
```

---
*Generated automatically by business-metrics-docs-generator.js*
*Last updated: 2025-09-26T09:29:19.730Z*
