API_DOCUMENTATION.md

# Audience Segmentation AI - REST API Documentation

## Base Information

**Base URL**: `http://localhost:7860`  
**API Documentation**: `/api/docs` (Swagger UI)  
**Content-Type**: `application/json`

---

##  Health & System

### GET `/health`
Check API and database connection status.

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2025-11-24T00:00:00",
  "database": "connected"
}
```

---

##  Event Analysis

### POST `/api/events/{event_code}/analyze`
Trigger full AI analysis pipeline for an event (Segmentation + Sentiment + GenAI).

**Path Parameters:**
- `event_code` (string, required): Event identifier

**Response:**
```json
{
  "status": "started",
  "message": "Analysis pipeline started for event {event_code}",
  "job_id": "analysis_abc123"
}
```

### GET `/api/events/{event_code}/dashboard`
Get comprehensive analytics dashboard for Event Owner.

**Path Parameters:**
- `event_code` (string, required): Event identifier

**Response:**
```json
{
  "event_code": "event_123",
  "segments": [
    {
      "id": "507f1f77bcf86cd799439011",
      "segment_name": "VIP Khách Hàng Trung Thành",
      "user_count": 150,
      "criteria": {
        "avg_spend": 1500000,
        "avg_tickets": 5.2,
        "avg_recency": 15
      },
      "marketing_content": {
        "email_subject": "Ưu đãi đặc biệt cho bạn!",
        "email_body": "...",
        "status": "Draft",
        "generated_at": "2025-11-24T00:00:00"
      }
    }
  ],
  "sentiment_summary": {
    "total_comments": 200,
    "sentiment_distribution": {
      "Positive": 150,
      "Negative": 30,
      "Neutral": 20
    },
    "avg_confidence": 0.87,
    "top_keywords": ["tuyệt vời", "âm thanh", "tổ chức"],
    "ai_insights": {
      "summary": "Sự kiện được đánh giá tích cực...",
      "top_issues": ["Check-in chậm", "Âm thanh yếu"],
      "improvement_suggestions": ["Tăng quầy check-in", "Nâng cấp loa"],
      "predicted_nps": 65.5
    }
  }
}
```

---

##  Audience Segmentation

### POST `/api/events/{event_code}/segmentation/run`
Run segmentation analysis for an event.

**Path Parameters:**
- `event_code` (string, required): Event identifier

**Query Parameters:**
- `n_clusters` (integer, optional): Number of segments (default: 5)

**Response:**
```json
{
  "status": "started",
  "message": "Segmentation started",
  "event_code": "event_123"
}
```

### GET `/api/events/{event_code}/segments`
Get all audience segments for an event.

**Path Parameters:**
- `event_code` (string, required): Event identifier

**Query Parameters:**
- `status` (string, optional): Filter by status (`Draft`, `Approved`, `Sent`)

**Response:**
```json
[
  {
    "id": "507f1f77bcf86cd799439011",
    "event_code": "event_123",
    "segment_name": "VIP Khách Hàng Trung Thành",
    "segment_type": "High Value",
    "user_count": 150,
    "user_ids": ["user_1", "user_2", "..."],
    "criteria": {
      "avg_spend": 1500000,
      "avg_tickets": 5.2,
      "avg_recency": 15,
      "avg_follow_count": 3
    },
    "marketing_content": {
      "email_subject": "Ưu đãi VIP đặc biệt",
      "email_body": "Kính gửi Quý khách...",
      "status": "Draft",
      "generated_at": "2025-11-24T00:00:00"
    },
    "created_at": "2025-11-24T00:00:00",
    "last_updated": "2025-11-24T00:00:00"
  }
]
```

### GET `/api/events/{event_code}/segments/{segment_id}`
Get specific segment details.

**Path Parameters:**
- `event_code` (string, required)
- `segment_id` (string, required): Segment ObjectId

**Response:**
```json
{
  "id": "507f1f77bcf86cd799439011",
  "event_code": "event_123",
  "segment_name": "VIP Khách Hàng Trung Thành",
  "user_count": 150,
  "user_ids": ["user_1", "user_2"],
  "criteria": {...},
  "marketing_content": {...}
}
```

### GET `/api/events/{event_code}/segments/{segment_id}/users`
Get user list in a segment.

**Path Parameters:**
- `event_code` (string, required)
- `segment_id` (string, required)

**Query Parameters:**
- `skip` (integer): Offset (default: 0)
- `limit` (integer): Max results (default: 100)

**Response:**
```json
{
  "segment_id": "507f1f77bcf86cd799439011",
  "total_users": 150,
  "users": [
    {
      "user_id": "user_1",
      "email": "user@example.com",
      "full_name": "Nguyễn Văn A",
      "stats": {
        "total_spend": 2000000,
        "tickets_bought": 6,
        "last_purchase": "2025-11-20"
      }
    }
  ]
}
```

---

##  Approval Workflow

### POST `/api/events/{event_code}/segments/{segment_id}/approve`
Event Owner approves marketing content.

**Path Parameters:**
- `event_code` (string, required)
- `segment_id` (string, required)

**Request Body (optional):**
```json
{
  "approved_by": "owner_user_id",
  "modified_content": {
    "email_subject": "Modified subject",
    "email_body": "Modified body"
  }
}
```

**Response:**
```json
{
  "status": "success",
  "message": "Segment approved",
  "segment_id": "507f1f77bcf86cd799439011",
  "marketing_content": {
    "status": "Approved",
    "approved_at": "2025-11-24T00:00:00",
    "approved_by": "owner_user_id"
  }
}
```

### POST `/api/events/{event_code}/segments/{segment_id}/send-email`
Send approved marketing email to segment users.

**Path Parameters:**
- `event_code` (string, required)
- `segment_id` (string, required)

**Request Body:**
```json
{
  "send_immediately": true,
  "schedule_at": "2025-11-25T10:00:00"
}
```

**Response:**
```json
{
  "status": "success",
  "message": "Email sent to 150 users",
  "segment_id": "507f1f77bcf86cd799439011",
  "emails_sent": 150,
  "emails_failed": 0,
  "marketing_content": {
    "status": "Sent"
  }
}
```

---

##  Sentiment Analysis

### POST `/api/events/{event_code}/sentiment/analyze`
Analyze sentiment for event comments.

**Path Parameters:**
- `event_code` (string, required)

**Response:**
```json
{
  "status": "started",
  "message": "Sentiment analysis started for event {event_code}"
}
```

### GET `/api/events/{event_code}/sentiment/summary`
Get sentiment summary for an event.

**Path Parameters:**
- `event_code` (string, required)

**Response:**
```json
{
  "event_code": "event_123",
  "total_comments": 200,
  "sentiment_distribution": {
    "Positive": 150,
    "Negative": 30,
    "Neutral": 20
  },
  "avg_confidence": 0.87,
  "top_keywords": ["tuyệt vời", "âm thanh", "tổ chức"],
  "ai_insights": {
    "summary": "Sự kiện được đánh giá tích cực với 75% feedback tích cực...",
    "top_issues": [
      "Check-in quá chậm (15 mentions)",
      "Âm thanh yếu ở khu vực sau (10 mentions)"
    ],
    "improvement_suggestions": [
      "Tăng số quầy check-in lên 5 quầy",
      "Bổ sung loa phụ khu vực sau"
    ],
    "predicted_nps": 65.5
  },
  "last_updated": "2025-11-24T00:00:00"
}
```

### GET `/api/events/{event_code}/sentiment/results`
Get detailed sentiment results.

**Path Parameters:**
- `event_code` (string, required)

**Query Parameters:**
- `sentiment_label` (string, optional): Filter by `Positive`, `Negative`, `Neutral`
- `skip` (integer): Offset
- `limit` (integer): Max results

**Response:**
```json
{
  "total": 200,
  "results": [
    {
      "id": "507f...",
      "event_code": "event_123",
      "source_id": "comment_abc",
      "sentiment_label": "Positive",
      "confidence_score": 0.92,
      "key_phrases": ["tuyệt vời", "hài lòng"],
      "analyzed_at": "2025-11-24T00:00:00"
    }
  ]
}
```

---

##  Generative AI

### POST `/api/events/{event_code}/genai/generate-emails`
Generate marketing emails for all segments.

**Path Parameters:**
- `event_code` (string, required)

**Response:**
```json
{
  "status": "started",
  "message": "Email generation started for {n} segments"
}
```

### POST `/api/events/{event_code}/genai/generate-insights`
Generate AI insights from negative feedback.

**Path Parameters:**
- `event_code` (string, required)

**Response:**
```json
{
  "status": "success",
  "insights": {
    "summary": "...",
    "top_issues": ["..."],
    "improvement_suggestions": ["..."],
    "predicted_nps": 62.5
  }
}
```

---

##  Monitoring & Analytics

### GET `/api/monitoring/pipelines/{pipeline}/metrics`
Get performance metrics for a pipeline.

**Path Parameters:**
- `pipeline` (string): `segmentation`, `sentiment`, `genai`

**Query Parameters:**
- `event_code` (string, optional): Filter by event
- `days` (integer): Date range (default: 7)

**Response:**
```json
{
  "pipeline": "segmentation",
  "event_code": "event_123",
  "total_runs": 5,
  "avg_execution_time": 4.2,
  "last_run": "2025-11-24T00:00:00",
  "metrics": {
    "avg_users_processed": 850,
    "avg_segments_created": 5,
    "avg_inertia": 1250.5
  }
}
```

### GET `/api/monitoring/pipelines/{pipeline}/drift`
Check for model drift.

**Path Parameters:**
- `pipeline` (string): `segmentation`, `sentiment`

**Query Parameters:**
- `event_code` (string, optional)

**Response:**
```json
{
  "pipeline": "segmentation",
  "drift_detected": true,
  "avg_drift": 0.65,
  "max_drift": 1.2,
  "threshold": 0.5,
  "recommendation": "Consider retraining model"
}
```

---

##  Feedback & Performance

### POST `/api/feedback/email-engagement`
Record email engagement metrics.

**Request Body:**
```json
{
  "segment_id": "507f...",
  "user_id": "user_1",
  "event_code": "event_123",
  "opened": true,
  "clicked": true,
  "converted": false,
  "unsubscribed": false
}
```

**Response:**
```json
{
  "status": "recorded",
  "feedback_id": "feedback_xyz"
}
```

### GET `/api/feedback/email-performance/{segment_id}`
Get email campaign performance.

**Path Parameters:**
- `segment_id` (string, required)

**Response:**
```json
{
  "segment_id": "507f...",
  "total_sent": 150,
  "open_rate": 0.65,
  "click_rate": 0.32,
  "conversion_rate": 0.12,
  "unsubscribe_rate": 0.02
}
```

---

##  Administration

### POST `/api/admin/indexes/create`
Create all MongoDB indexes (run once during setup).

**Response:**
```json
{
  "status": "success",
  "indexes_created": [
    "idx_payment_event_status_user",
    "idx_follow_event_user",
    "idx_comment_event_date",
    "..."
  ]
}
```

### POST `/api/admin/models/retrain`
Trigger model retraining based on feedback.

**Request Body:**
```json
{
  "model_type": "segmentation",
  "event_code": "event_123"
}
```

**Response:**
```json
{
  "status": "started",
  "job_id": "retrain_abc123"
}
```

---

## Error Responses

All endpoints may return error responses in the following format:

```json
{
  "detail": "Error message description",
  "status_code": 400
}
```