# API Reference

Complete reference for the Analytics API endpoints.

## Base URL

```
Production: https://analytics.example.com
Development: http://localhost:4001
```

## Authentication

API endpoints use API key authentication:

```
Authorization: Bearer <api-key>
```

Or via header:

```
X-API-Key: <api-key>
```

## Collector Endpoints

### POST /collect/engagement

Collect engagement events from clients.

**Request Body:**

```json
{
  "sessionId": "string (required)",
  "userId": "string (optional)",
  "type": "string (required)",
  "action": "string (required)",
  "timestamp": "ISO8601 string (optional)",
  "metadata": "object (optional)",
  "source": {
    "app": "string",
    "environment": "string"
  }
}
```

**Response:** `202 Accepted`

```json
{
  "success": true,
  "eventId": "evt_abc123"
}
```

**Example:**

```bash
curl -X POST https://analytics.example.com/collect/engagement \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_123",
    "type": "navigation",
    "action": "page_view",
    "metadata": {
      "path": "/products",
      "referrer": "https://google.com"
    }
  }'
```

### POST /collect/batch

Collect multiple events in a single request.

**Request Body:**

```json
{
  "events": [
    {
      "sessionId": "string",
      "type": "string",
      "action": "string",
      "timestamp": "ISO8601",
      "metadata": {}
    }
  ]
}
```

**Response:** `202 Accepted`

```json
{
  "success": true,
  "processed": 10,
  "failed": 0
}
```

### POST /collect/device

Collect device fingerprint information.

**Request Body:**

```json
{
  "sessionId": "string (required)",
  "fingerprint": {
    "screenWidth": 1920,
    "screenHeight": 1080,
    "viewportWidth": 1200,
    "viewportHeight": 800,
    "devicePixelRatio": 2,
    "colorDepth": 24,
    "timezone": "America/New_York",
    "language": "en-US",
    "platform": "MacIntel",
    "vendor": "Google Inc.",
    "cookiesEnabled": true,
    "doNotTrack": false
  }
}
```

## Query API Endpoints

### GET /api/trends

Get trend data over time.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `metric` | string | Yes | Metric to query (pageViews, sessions, users) |
| `startDate` | ISO8601 | Yes | Start of date range |
| `endDate` | ISO8601 | Yes | End of date range |
| `granularity` | string | No | hour, day, week, month (default: day) |
| `filters` | JSON | No | Filter criteria |

**Response:**

```json
{
  "metric": "pageViews",
  "granularity": "day",
  "data": [
    { "date": "2024-01-01", "value": 1523 },
    { "date": "2024-01-02", "value": 1687 },
    { "date": "2024-01-03", "value": 1456 }
  ],
  "total": 4666,
  "change": 12.5
}
```

### GET /api/funnels

Get funnel conversion data.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `funnelId` | string | Yes | Funnel identifier |
| `startDate` | ISO8601 | Yes | Start of date range |
| `endDate` | ISO8601 | Yes | End of date range |
| `steps` | JSON array | No | Custom funnel steps |

**Response:**

```json
{
  "funnelId": "checkout",
  "steps": [
    { "name": "Cart View", "count": 10000, "rate": 100 },
    { "name": "Begin Checkout", "count": 6500, "rate": 65 },
    { "name": "Add Payment", "count": 4200, "rate": 42 },
    { "name": "Purchase", "count": 3100, "rate": 31 }
  ],
  "overallConversion": 31,
  "dropoffs": [
    { "from": "Cart View", "to": "Begin Checkout", "lost": 3500, "rate": 35 },
    { "from": "Begin Checkout", "to": "Add Payment", "lost": 2300, "rate": 35.4 },
    { "from": "Add Payment", "to": "Purchase", "lost": 1100, "rate": 26.2 }
  ]
}
```

### GET /api/cohorts

Get cohort retention data.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cohortType` | string | Yes | signup_date, first_purchase, etc. |
| `startDate` | ISO8601 | Yes | Start of cohort range |
| `endDate` | ISO8601 | Yes | End of cohort range |
| `periods` | number | No | Number of retention periods (default: 12) |

**Response:**

```json
{
  "cohortType": "signup_date",
  "cohorts": [
    {
      "date": "2024-01",
      "size": 1000,
      "retention": [100, 45, 38, 32, 28, 25]
    },
    {
      "date": "2024-02",
      "size": 1200,
      "retention": [100, 48, 41, 35, 30]
    }
  ]
}
```

### GET /api/segments

Get data segmented by dimension.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dimension` | string | Yes | Segmentation dimension |
| `metric` | string | Yes | Metric to aggregate |
| `startDate` | ISO8601 | Yes | Start of date range |
| `endDate` | ISO8601 | Yes | End of date range |
| `limit` | number | No | Max segments (default: 10) |

**Available Dimensions:**
- `country` - Geographic country
- `device` - Device type (mobile, tablet, desktop)
- `browser` - Browser name
- `os` - Operating system
- `source` - Traffic source
- `medium` - Traffic medium
- `campaign` - Campaign name

**Response:**

```json
{
  "dimension": "device",
  "metric": "sessions",
  "segments": [
    { "name": "desktop", "value": 45000, "percentage": 56.2 },
    { "name": "mobile", "value": 30000, "percentage": 37.5 },
    { "name": "tablet", "value": 5000, "percentage": 6.3 }
  ],
  "total": 80000
}
```

### GET /api/acquisition

Get traffic acquisition data.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `startDate` | ISO8601 | Yes | Start of date range |
| `endDate` | ISO8601 | Yes | End of date range |
| `groupBy` | string | No | source, medium, campaign |

**Response:**

```json
{
  "channels": [
    {
      "channel": "Organic Search",
      "sessions": 25000,
      "users": 20000,
      "newUsers": 15000,
      "bounceRate": 45.2,
      "avgSessionDuration": 180,
      "conversions": 500,
      "conversionRate": 2.0
    },
    {
      "channel": "Direct",
      "sessions": 18000,
      "users": 12000,
      "newUsers": 3000,
      "bounceRate": 35.8,
      "avgSessionDuration": 240,
      "conversions": 800,
      "conversionRate": 4.4
    }
  ]
}
```

### GET /api/engagement

Get engagement metrics.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `startDate` | ISO8601 | Yes | Start of date range |
| `endDate` | ISO8601 | Yes | End of date range |

**Response:**

```json
{
  "metrics": {
    "avgSessionDuration": 185,
    "avgPageViewsPerSession": 3.2,
    "bounceRate": 42.5,
    "avgScrollDepth": 65,
    "engagementRate": 57.5
  },
  "topPages": [
    { "path": "/", "views": 50000, "avgTime": 45 },
    { "path": "/products", "views": 35000, "avgTime": 120 },
    { "path": "/pricing", "views": 28000, "avgTime": 90 }
  ],
  "topEvents": [
    { "action": "add_to_cart", "count": 8500 },
    { "action": "signup_click", "count": 6200 },
    { "action": "video_play", "count": 4800 }
  ]
}
```

## Realtime Endpoints

### WebSocket /realtime

Connect to receive real-time analytics updates.

**Connection:**

```javascript
const ws = new WebSocket('wss://analytics.example.com/realtime');

ws.onopen = () => {
  // Subscribe to channels
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels: ['active_users', 'page_views', 'events']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};
```

**Messages:**

```json
{
  "channel": "active_users",
  "data": {
    "count": 156,
    "byPage": {
      "/": 45,
      "/products": 32,
      "/checkout": 12
    }
  }
}
```

### GET /api/realtime/active

Get current active users.

**Response:**

```json
{
  "activeUsers": 156,
  "activeSessions": 142,
  "byCountry": [
    { "country": "US", "count": 65 },
    { "country": "UK", "count": 23 },
    { "country": "DE", "count": 18 }
  ],
  "byPage": [
    { "path": "/", "count": 45 },
    { "path": "/products", "count": 32 }
  ],
  "recentEvents": [
    { "action": "purchase", "timestamp": "2024-01-15T10:30:00Z" },
    { "action": "signup", "timestamp": "2024-01-15T10:29:45Z" }
  ]
}
```

## Error Responses

All endpoints return consistent error responses:

```json
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid date format for startDate",
    "details": {
      "parameter": "startDate",
      "provided": "2024-13-01",
      "expected": "ISO8601 date string"
    }
  }
}
```

**Error Codes:**

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `INVALID_PARAMETER` | 400 | Invalid request parameter |
| `MISSING_PARAMETER` | 400 | Required parameter missing |
| `UNAUTHORIZED` | 401 | Invalid or missing API key |
| `FORBIDDEN` | 403 | Insufficient permissions |
| `NOT_FOUND` | 404 | Resource not found |
| `RATE_LIMITED` | 429 | Too many requests |
| `INTERNAL_ERROR` | 500 | Server error |

## Rate Limits

| Endpoint Type | Limit |
|---------------|-------|
| Collector | 1000 req/min per session |
| Query API | 100 req/min per API key |
| Realtime | 10 connections per API key |

Rate limit headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800
```
