Hugging Face's logo

Spaces:
minhvtt
/
Aus_F
Sleeping

App Files Community
Aus_F / API_DOCUMENTATION.md
minhvtt's picture
minhvtt
Upload 7 files
d97be90 verified
preview code
|
raw
history blame contribute delete
11.1 kB

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

[
  {
    "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:

{
  "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:

{
  "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):

{
  "approved_by": "owner_user_id",
  "modified_content": {
    "email_subject": "Modified subject",
    "email_body": "Modified body"
  }
}

Response:

{
  "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:

{
  "send_immediately": true,
  "schedule_at": "2025-11-25T10:00:00"
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "segment_id": "507f...",
  "user_id": "user_1",
  "event_code": "event_123",
  "opened": true,
  "clicked": true,
  "converted": false,
  "unsubscribed": false
}

Response:

{
  "status": "recorded",
  "feedback_id": "feedback_xyz"
}

GET /api/feedback/email-performance/{segment_id}

Get email campaign performance.

Path Parameters:

  • segment_id (string, required)

Response:

{
  "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:

{
  "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:

{
  "model_type": "segmentation",
  "event_code": "event_123"
}

Response:

{
  "status": "started",
  "job_id": "retrain_abc123"
}

Error Responses

All endpoints may return error responses in the following format:

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