Authenticated API

This endpoint requires a valid JWT Bearer token with content_creator roles. Accessible via the API gateway.

Audience API

Manage audience relationships, track engagement, handle subscriptions, and build community for creators.

Overview

Attribute	Value
Base Path	`/api/v1/audience`
Authentication	Bearer Token
Required Roles	`content_creator`, `marketing`, `brand_manager`, `manager`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Audience Members

List Audience

GET /api/v1/audience/members

Query Parameters

Parameter	Type	Description
`creator_id`	uuid	Filter by creator
`tier`	string	Filter by subscription tier
`status`	string	`active`, `churned`, `paused`
`engagement_level`	string	`superfan`, `engaged`, `casual`, `inactive`
`joined_after`	date	Filter by join date

Response

{
  "members": [
    {
      "id": "member_001",
      "user_id": "user_abc",
      "creator_id": "creator_xyz",
      "name": "Sarah Johnson",
      "email": "sarah@example.com",
      "avatar_url": "https://...",
      "tier": {
        "id": "tier_premium",
        "name": "Premium Fan",
        "price_monthly": 9.99
      },
      "status": "active",
      "engagement": {
        "level": "superfan",
        "score": 95,
        "interactions_30d": 45,
        "last_interaction": "2026-01-24T18:00:00Z"
      },
      "subscription": {
        "started_at": "2025-06-15",
        "months_subscribed": 7,
        "lifetime_value": 69.93,
        "next_billing": "2026-02-15"
      },
      "joined_at": "2025-06-15T00:00:00Z"
    }
  ],
  "total": 4520,
  "segments": {
    "superfans": 450,
    "engaged": 1200,
    "casual": 2100,
    "inactive": 770
  }
}

Get Member

GET /api/v1/audience/members/{member_id}

Response

{
  "id": "member_001",
  "user_id": "user_abc",
  "creator_id": "creator_xyz",
  "name": "Sarah Johnson",
  "email": "sarah@example.com",
  "avatar_url": "https://...",
  "tier": {
    "id": "tier_premium",
    "name": "Premium Fan",
    "price_monthly": 9.99,
    "benefits": ["Early access", "Exclusive content", "Direct messaging"]
  },
  "status": "active",
  "engagement": {
    "level": "superfan",
    "score": 95,
    "rank": 23,
    "interactions_total": 520,
    "interactions_30d": 45,
    "content_views": 380,
    "comments": 85,
    "shares": 55,
    "persona_conversations": 120
  },
  "activity_timeline": [
    {
      "type": "persona_chat",
      "timestamp": "2026-01-24T18:00:00Z",
      "details": {"duration_minutes": 12}
    },
    {
      "type": "content_view",
      "timestamp": "2026-01-24T15:30:00Z",
      "details": {"content_id": "content_001", "completion": 1.0}
    }
  ],
  "subscription": {
    "id": "sub_001",
    "tier_id": "tier_premium",
    "started_at": "2025-06-15",
    "months_subscribed": 7,
    "lifetime_value": 69.93,
    "billing_cycle": "monthly",
    "next_billing": "2026-02-15",
    "payment_method": "card_ending_4242",
    "status": "active"
  },
  "gifts_received": [
    {
      "from_member_id": "member_050",
      "gift_type": "subscription_month",
      "date": "2025-12-25"
    }
  ],
  "preferences": {
    "notifications": ["new_content", "live_events"],
    "communication_channel": "email"
  },
  "joined_at": "2025-06-15T00:00:00Z",
  "last_active": "2026-01-24T18:00:00Z"
}

Update Member

PUT /api/v1/audience/members/{member_id}

Subscription Tiers

List Tiers

GET /api/v1/audience/tiers

Response

{
  "tiers": [
    {
      "id": "tier_free",
      "name": "Free Fan",
      "description": "Basic access to public content",
      "price_monthly": 0,
      "price_yearly": 0,
      "benefits": [
        "Access to public content",
        "Community forum access"
      ],
      "member_count": 8500,
      "is_default": true
    },
    {
      "id": "tier_supporter",
      "name": "Supporter",
      "description": "Support the creator and get extra perks",
      "price_monthly": 4.99,
      "price_yearly": 49.99,
      "benefits": [
        "Everything in Free",
        "Early access to content",
        "Supporter badge",
        "Monthly Q&A access"
      ],
      "member_count": 2100,
      "revenue_monthly": 10479.00
    },
    {
      "id": "tier_premium",
      "name": "Premium Fan",
      "description": "The ultimate fan experience",
      "price_monthly": 9.99,
      "price_yearly": 99.99,
      "benefits": [
        "Everything in Supporter",
        "Exclusive content",
        "Direct messaging",
        "Unlimited persona chat",
        "Behind the scenes access"
      ],
      "member_count": 850,
      "revenue_monthly": 8491.50
    }
  ]
}

Create Tier

POST /api/v1/audience/tiers

Request Body

{
  "name": "VIP",
  "description": "Exclusive VIP access with personalized perks",
  "price_monthly": 24.99,
  "price_yearly": 249.99,
  "benefits": [
    "Everything in Premium",
    "1-on-1 monthly call",
    "Physical merchandise",
    "Credit in content"
  ],
  "limit": 100,
  "visible": true
}

Update Tier

PUT /api/v1/audience/tiers/{tier_id}

Engagement

Get Engagement Analytics

GET /api/v1/audience/engagement

Query Parameters

Parameter	Type	Description
`period`	string	`day`, `week`, `month`, `year`
`creator_id`	uuid	Filter by creator

Response

{
  "period": "month",
  "overview": {
    "total_members": 11450,
    "active_members": 8200,
    "new_members": 580,
    "churned_members": 120,
    "net_growth": 460,
    "growth_rate": 0.042
  },
  "engagement": {
    "avg_engagement_score": 65,
    "interactions_total": 125000,
    "content_views": 85000,
    "comments": 15000,
    "shares": 8500,
    "persona_conversations": 16500
  },
  "distribution": {
    "superfans": {
      "count": 1150,
      "percent": 0.10,
      "avg_interactions": 45
    },
    "engaged": {
      "count": 3200,
      "percent": 0.28,
      "avg_interactions": 18
    },
    "casual": {
      "count": 4600,
      "percent": 0.40,
      "avg_interactions": 5
    },
    "inactive": {
      "count": 2500,
      "percent": 0.22,
      "avg_interactions": 0
    }
  },
  "trends": {
    "engagement_trend": "+8%",
    "retention_rate": 0.92,
    "avg_session_duration_minutes": 12.5
  }
}

Send Engagement Campaign

POST /api/v1/audience/engagement/campaigns

Request Body

{
  "name": "Win Back Inactive Fans",
  "type": "reactivation",
  "target_segment": "inactive",
  "filters": {
    "inactive_days_min": 30,
    "was_paid_subscriber": true
  },
  "message": {
    "subject": "We miss you! Here's a special offer...",
    "body": "It's been a while since we've seen you...",
    "cta": "Come back and get 50% off your first month"
  },
  "offer": {
    "type": "discount",
    "value": 0.50,
    "duration_months": 1,
    "code": "COMEBACK50"
  },
  "channels": ["email", "push"],
  "scheduled_at": "2026-01-25T09:00:00Z"
}

Monetization

Get Revenue Analytics

GET /api/v1/audience/revenue

Query Parameters

Parameter	Type	Description
`period`	string	`month`, `quarter`, `year`
`creator_id`	uuid	Filter by creator

Response

{
  "period": "month",
  "revenue": {
    "total": 45250.00,
    "subscriptions": 38500.00,
    "tips": 4200.00,
    "merchandise": 1850.00,
    "pay_per_view": 700.00
  },
  "subscriptions": {
    "mrr": 38500.00,
    "arr": 462000.00,
    "new_mrr": 5200.00,
    "churned_mrr": 1800.00,
    "net_mrr_growth": 3400.00,
    "by_tier": [
      {"tier": "Supporter", "mrr": 10479.00, "subscribers": 2100},
      {"tier": "Premium Fan", "mrr": 8491.50, "subscribers": 850},
      {"tier": "VIP", "mrr": 19529.50, "subscribers": 782}
    ]
  },
  "metrics": {
    "arpu": 3.95,
    "arppu": 12.50,
    "ltv": 125.00,
    "cac": 15.00,
    "ltv_cac_ratio": 8.3,
    "churn_rate": 0.028
  },
  "payouts": {
    "pending": 12500.00,
    "next_payout_date": "2026-02-01",
    "platform_fee_rate": 0.10
  }
}

Create Tip Jar

POST /api/v1/audience/tips/jars

Request Body

{
  "name": "Support My Next Project",
  "goal": 5000.00,
  "description": "Help fund my upcoming documentary",
  "suggested_amounts": [5, 10, 25, 50, 100],
  "rewards": [
    {"threshold": 25, "reward": "Name in credits"},
    {"threshold": 100, "reward": "Exclusive behind-the-scenes access"}
  ],
  "end_date": "2026-03-31"
}

Process Tip

POST /api/v1/audience/tips

Request Body

{
  "member_id": "member_001",
  "creator_id": "creator_xyz",
  "jar_id": "jar_001",
  "amount": 25.00,
  "message": "Love your content! Keep it up!",
  "anonymous": false,
  "payment_method_id": "pm_card_001"
}

Response

{
  "tip_id": "tip_001",
  "amount": 25.00,
  "status": "completed",
  "creator_receives": 22.50,
  "platform_fee": 2.50,
  "reward_unlocked": {
    "description": "Name in credits",
    "instructions": "Reply with the name you'd like in the credits"
  },
  "thank_you_message": "Thank you so much for your support!",
  "receipt_url": "https://..."
}

Community

Get Community Stats

GET /api/v1/audience/community

Response

{
  "stats": {
    "total_members": 11450,
    "active_today": 2450,
    "posts_today": 85,
    "comments_today": 520
  },
  "top_contributors": [
    {
      "member_id": "member_001",
      "name": "Sarah Johnson",
      "contributions": 450,
      "badge": "Superfan"
    }
  ],
  "trending_topics": [
    {"topic": "latest_video", "mentions": 125},
    {"topic": "recipe_request", "mentions": 45}
  ],
  "moderation": {
    "pending_reports": 3,
    "auto_moderated_today": 12
  }
}

Create Announcement

POST /api/v1/audience/announcements

Request Body

{
  "title": "Big Announcement!",
  "content": "I'm excited to share that...",
  "visibility": "all_members",
  "pin": true,
  "notify": true,
  "notification_channels": ["push", "email"]
}

Webhooks

Event	Description
`audience.member_joined`	New member joined
`audience.member_upgraded`	Member upgraded tier
`audience.member_churned`	Member cancelled subscription
`audience.tip_received`	Tip received
`audience.milestone_reached`	Member or revenue milestone
`audience.engagement_alert`	Engagement anomaly detected

Error Responses

Status	Code	Description
400	`invalid_tier`	Tier not found
400	`payment_failed`	Payment processing failed
404	`member_not_found`	Member ID not found
409	`already_subscribed`	Already subscribed to tier
422	`tier_limit_reached`	Tier membership limit reached

Personas API - AI personas
Content API - Content management
Payments API - Payment processing

Overview​

Audience Members​

List Audience​

Get Member​

Update Member​

Subscription Tiers​

List Tiers​

Create Tier​

Update Tier​

Engagement​

Get Engagement Analytics​

Send Engagement Campaign​

Monetization​

Get Revenue Analytics​

Create Tip Jar​

Process Tip​

Community​

Get Community Stats​

Create Announcement​

Webhooks​

Error Responses​

Related Documentation​

Overview

Audience Members

List Audience

Get Member

Update Member

Subscription Tiers

List Tiers

Create Tier

Update Tier

Engagement

Get Engagement Analytics

Send Engagement Campaign

Monetization

Get Revenue Analytics

Create Tip Jar

Process Tip

Community

Get Community Stats

Create Announcement

Webhooks

Error Responses

Related Documentation