Authenticated API

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

Social Listening API

Comprehensive social listening and influencer discovery platform for the Creator Revolution, with direct POS integration for correlating social mentions with sales impact.

Overview

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

Key Features

Multi-Platform Monitoring - Twitter, Instagram, TikTok, Facebook
Sentiment Analysis - AI-powered sentiment classification
Influencer Discovery - Local influencer identification and scoring
Review Aggregation - Google, Yelp, TripAdvisor in one place
Sales Correlation - Unique integration with POS data

Brand Mentions

Get Mentions

GET /api/v1/social-listening/mentions

Retrieve brand mentions across all connected platforms.

Query Parameters

Parameter	Type	Description
`platform`	string	`twitter`, `instagram`, `tiktok`, `facebook`, `all`
`sentiment`	string	`positive`, `negative`, `neutral`, `all`
`since`	datetime	Start date for mentions
`until`	datetime	End date for mentions
`influencer_only`	boolean	Only show influencer mentions
`min_followers`	integer	Minimum follower count

Response

{
  "mentions": [
    {
      "mention_id": "men_001",
      "platform": "instagram",
      "author": {
        "username": "@foodie_jane",
        "display_name": "Jane Doe",
        "followers": 15420,
        "is_influencer": true,
        "influencer_tier": "micro"
      },
      "content": "Best burger in town! @olympus_restaurant never disappoints 🍔",
      "media": [
        {
          "type": "image",
          "url": "https://instagram.com/..."
        }
      ],
      "engagement": {
        "likes": 234,
        "comments": 45,
        "shares": 12
      },
      "sentiment": {
        "score": 0.92,
        "label": "positive",
        "emotions": ["joy", "satisfaction"]
      },
      "location_match": {
        "matched": true,
        "location_id": "loc_001",
        "location_name": "Downtown Location"
      },
      "posted_at": "2026-01-24T19:30:00Z",
      "processed_at": "2026-01-24T19:31:00Z"
    }
  ],
  "summary": {
    "total": 156,
    "positive": 132,
    "negative": 8,
    "neutral": 16,
    "platforms": {
      "instagram": 89,
      "twitter": 45,
      "tiktok": 22
    }
  },
  "pagination": {
    "cursor": "next_page_token",
    "has_more": true
  }
}

Get Mention Details

GET /api/v1/social-listening/mentions/{mention_id}

Response

{
  "mention_id": "men_001",
  "platform": "instagram",
  "post_url": "https://instagram.com/p/...",
  "author": {
    "username": "@foodie_jane",
    "profile_url": "https://instagram.com/foodie_jane",
    "followers": 15420,
    "following": 892,
    "engagement_rate": 4.2,
    "is_influencer": true,
    "influencer_tier": "micro",
    "categories": ["food", "lifestyle"]
  },
  "content": "Best burger in town! @olympus_restaurant never disappoints 🍔",
  "sentiment": {
    "score": 0.92,
    "label": "positive",
    "analysis": "User expressing strong satisfaction with product quality"
  },
  "engagement": {
    "likes": 234,
    "comments": 45,
    "shares": 12,
    "reach_estimate": 12500
  },
  "sales_correlation": {
    "correlated": true,
    "order_id": "ord_123",
    "order_total": 45.99,
    "items_mentioned": ["Signature Burger"]
  },
  "suggested_response": {
    "template": "thank_customer",
    "message": "Thank you so much for the love, Jane! 🙏 We're thrilled you enjoyed our Signature Burger. See you again soon!",
    "confidence": 0.89
  },
  "posted_at": "2026-01-24T19:30:00Z"
}

Sentiment Analysis

Get Sentiment Overview

GET /api/v1/social-listening/sentiment

Query Parameters

Parameter	Type	Description
`period`	string	`day`, `week`, `month`, `quarter`
`platform`	string	Filter by platform
`location_id`	uuid	Filter by location

Response

{
  "period": "week",
  "sentiment_breakdown": {
    "positive": 0.78,
    "neutral": 0.14,
    "negative": 0.08
  },
  "sentiment_trend": [
    {"date": "2026-01-18", "positive": 0.75, "negative": 0.10},
    {"date": "2026-01-19", "positive": 0.80, "negative": 0.07},
    {"date": "2026-01-20", "positive": 0.82, "negative": 0.05}
  ],
  "top_positive_topics": [
    {"topic": "food quality", "mentions": 45, "sentiment": 0.94},
    {"topic": "service", "mentions": 32, "sentiment": 0.88},
    {"topic": "ambiance", "mentions": 18, "sentiment": 0.85}
  ],
  "top_negative_topics": [
    {"topic": "wait time", "mentions": 8, "sentiment": -0.72},
    {"topic": "parking", "mentions": 5, "sentiment": -0.65}
  ],
  "emotion_analysis": {
    "joy": 0.45,
    "satisfaction": 0.30,
    "excitement": 0.12,
    "frustration": 0.08,
    "disappointment": 0.05
  }
}

Get Sentiment Alerts

GET /api/v1/social-listening/sentiment/alerts

Response

{
  "alerts": [
    {
      "alert_id": "alert_001",
      "type": "negative_spike",
      "severity": "high",
      "description": "Negative sentiment increased 25% in the last hour",
      "trigger_mentions": ["men_101", "men_102", "men_103"],
      "common_topic": "slow service",
      "suggested_action": "Review current staffing levels and kitchen ticket times",
      "created_at": "2026-01-24T20:00:00Z"
    }
  ]
}

Influencer Discovery

Discover Influencers

GET /api/v1/social-listening/influencers/discover

Find local influencers relevant to your business.

Query Parameters

Parameter	Type	Description
`location`	string	City, region, or coordinates
`category`	string	`food`, `lifestyle`, `travel`, `local_news`
`tier`	string	`nano`, `micro`, `mid`, `macro`, `mega`
`min_engagement`	float	Minimum engagement rate

Influencer Tiers

Tier	Follower Range	Typical Engagement
`nano`	1K - 10K	5-10%
`micro`	10K - 50K	3-5%
`mid`	50K - 500K	2-3%
`macro`	500K - 1M	1-2%
`mega`	1M+	0.5-1%

Response

{
  "influencers": [
    {
      "influencer_id": "inf_001",
      "username": "@local_foodie",
      "display_name": "Sarah's Food Adventures",
      "platform": "instagram",
      "profile_url": "https://instagram.com/local_foodie",
      "avatar_url": "https://...",
      "bio": "Food blogger exploring the best local eats 🍽️",
      "metrics": {
        "followers": 28500,
        "following": 1200,
        "posts": 850,
        "engagement_rate": 4.2,
        "avg_likes": 1200,
        "avg_comments": 85
      },
      "categories": ["food", "local", "lifestyle"],
      "tier": "micro",
      "location": {
        "city": "Austin",
        "state": "TX"
      },
      "relevance_score": 0.94,
      "previous_mentions": 3,
      "estimated_reach": 25000,
      "estimated_cpm": 15.00
    }
  ],
  "total": 45
}

Get Influencer Profile

GET /api/v1/social-listening/influencers/{influencer_id}

Response

{
  "influencer_id": "inf_001",
  "username": "@local_foodie",
  "platforms": [
    {
      "platform": "instagram",
      "username": "@local_foodie",
      "followers": 28500,
      "engagement_rate": 4.2
    },
    {
      "platform": "tiktok",
      "username": "@sarahsfoodadventures",
      "followers": 45000,
      "engagement_rate": 6.8
    }
  ],
  "audience_demographics": {
    "age_groups": {
      "18-24": 0.25,
      "25-34": 0.45,
      "35-44": 0.20,
      "45+": 0.10
    },
    "gender": {
      "female": 0.68,
      "male": 0.30,
      "other": 0.02
    },
    "top_locations": [
      {"city": "Austin", "percentage": 0.35},
      {"city": "Houston", "percentage": 0.15}
    ]
  },
  "content_analysis": {
    "posting_frequency": "3-4 posts/week",
    "best_performing_content": ["restaurant reviews", "food photography"],
    "typical_post_time": "6-8 PM"
  },
  "brand_mentions": [
    {
      "mention_id": "men_001",
      "date": "2026-01-15",
      "content": "Amazing dinner at @olympus_restaurant",
      "engagement": 1500,
      "sentiment": "positive"
    }
  ],
  "collaboration_history": {
    "total_collaborations": 12,
    "avg_roi": 3.5,
    "brands_worked_with": ["LocalBrand1", "LocalBrand2"]
  },
  "contact": {
    "email_available": true,
    "preferred_contact": "dm"
  }
}

Track Influencer ROI

GET /api/v1/social-listening/influencers/{influencer_id}/roi

Response

{
  "influencer_id": "inf_001",
  "campaigns": [
    {
      "campaign_id": "camp_001",
      "name": "Summer Menu Launch",
      "date": "2026-01-10",
      "investment": 500.00,
      "metrics": {
        "reach": 28000,
        "impressions": 45000,
        "engagement": 2500,
        "clicks": 350,
        "conversions": 45
      },
      "attributed_revenue": 1850.00,
      "roi": 2.7
    }
  ],
  "lifetime_metrics": {
    "total_investment": 1500.00,
    "total_attributed_revenue": 5200.00,
    "overall_roi": 2.47,
    "total_reach": 85000
  }
}

Review Aggregation

Get Reviews

GET /api/v1/social-listening/reviews

Aggregate reviews from all platforms.

Query Parameters

Parameter	Type	Description
`platform`	string	`google`, `yelp`, `tripadvisor`, `all`
`rating`	integer	Filter by rating (1-5)
`responded`	boolean	Filter by response status
`location_id`	uuid	Filter by location

Response

{
  "reviews": [
    {
      "review_id": "rev_001",
      "platform": "google",
      "author": {
        "name": "Michael Chen",
        "profile_url": "https://...",
        "review_count": 45,
        "photo_count": 120
      },
      "rating": 4,
      "content": "Great food and atmosphere. Service was a bit slow during peak hours but overall a good experience.",
      "photos": [
        "https://..."
      ],
      "sentiment": {
        "score": 0.65,
        "label": "positive",
        "topics": {
          "food": "positive",
          "atmosphere": "positive",
          "service": "negative"
        }
      },
      "responded": false,
      "suggested_response": {
        "message": "Thank you for your feedback, Michael! We're glad you enjoyed the food and atmosphere. We apologize for the wait during peak hours and are working to improve our service speed. We hope to see you again soon!",
        "confidence": 0.87
      },
      "posted_at": "2026-01-23T18:00:00Z",
      "location_id": "loc_001"
    }
  ],
  "summary": {
    "total": 234,
    "average_rating": 4.3,
    "by_platform": {
      "google": {"count": 120, "avg": 4.4},
      "yelp": {"count": 78, "avg": 4.2},
      "tripadvisor": {"count": 36, "avg": 4.1}
    },
    "needs_response": 15
  }
}

Respond to Review

POST /api/v1/social-listening/reviews/{review_id}/respond

Request Body

{
  "response": "Thank you for your feedback, Michael! We're glad you enjoyed...",
  "use_ai_suggestion": false
}

Response

{
  "review_id": "rev_001",
  "response_status": "pending",
  "response_message": "Thank you for your feedback...",
  "platform": "google",
  "submitted_at": "2026-01-24T20:00:00Z"
}

Competitor Monitoring

Add Competitor

POST /api/v1/social-listening/competitors

Request Body

{
  "name": "Competitor Restaurant",
  "social_handles": {
    "instagram": "@competitor_restaurant",
    "twitter": "@competitor",
    "tiktok": "@competitor_restaurant"
  },
  "locations": ["Downtown Austin"],
  "monitor": true
}

Get Competitor Analysis

GET /api/v1/social-listening/competitors/{competitor_id}/analysis

Response

{
  "competitor_id": "comp_001",
  "name": "Competitor Restaurant",
  "comparison": {
    "mention_volume": {
      "you": 156,
      "competitor": 89,
      "difference": "+75%"
    },
    "sentiment": {
      "you": 0.78,
      "competitor": 0.72,
      "difference": "+0.06"
    },
    "engagement": {
      "you": 2500,
      "competitor": 1800,
      "difference": "+39%"
    }
  },
  "competitor_insights": {
    "trending_content": [
      {
        "type": "new_menu_item",
        "content": "Competitor launched a new signature dish",
        "engagement": 450,
        "date": "2026-01-20"
      }
    ],
    "promotions_detected": [
      {
        "type": "discount",
        "description": "20% off weekday lunches",
        "detected_at": "2026-01-18"
      }
    ],
    "sentiment_trends": {
      "improving": ["service"],
      "declining": ["wait_time"]
    }
  }
}

Sales Correlation

GET /api/v1/social-listening/correlation/sales

Unique Olympus feature: correlate social mentions with actual sales data.

Response

{
  "period": "last_30_days",
  "correlations": [
    {
      "influencer_id": "inf_001",
      "username": "@local_foodie",
      "mention_date": "2026-01-10",
      "attributed_sales": {
        "orders": 45,
        "revenue": 1850.00,
        "new_customers": 28
      },
      "correlation_confidence": 0.87,
      "attribution_method": "promo_code"
    }
  ],
  "summary": {
    "total_attributed_revenue": 12500.00,
    "total_attributed_orders": 320,
    "top_performing_influencer": "inf_001",
    "best_performing_platform": "instagram"
  },
  "insights": [
    {
      "type": "recommendation",
      "message": "Instagram food influencers drive 3x more conversions than other platforms",
      "action": "Increase Instagram influencer partnerships"
    }
  ]
}

Webhooks

Event	Description
`mention.new`	New brand mention detected
`mention.negative`	Negative sentiment mention detected
`review.new`	New review posted
`review.negative`	Negative review (1-2 stars) posted
`influencer.mention`	Influencer mentioned your brand
`sentiment.spike`	Significant sentiment change detected
`competitor.update`	Competitor activity detected

Error Responses

Status	Code	Description
400	`invalid_platform`	Unsupported platform
400	`invalid_date_range`	Invalid date range
404	`mention_not_found`	Mention ID not found
429	`rate_limit_exceeded`	API rate limit exceeded
503	`platform_unavailable`	Social platform API unavailable

Social Publishing API - Post to social platforms
Content API - Content management
Audience API - Audience analytics
CRM API - Customer relationship management

Overview​

Key Features​

Brand Mentions​

Get Mentions​

Get Mention Details​

Sentiment Analysis​

Get Sentiment Overview​

Get Sentiment Alerts​

Influencer Discovery​

Discover Influencers​

Get Influencer Profile​

Track Influencer ROI​

Review Aggregation​

Get Reviews​

Respond to Review​

Competitor Monitoring​

Add Competitor​

Get Competitor Analysis​

Sales Correlation​

Get Social-Sales Correlation​

Webhooks​

Error Responses​

Related Documentation​

Overview

Key Features

Brand Mentions

Get Mentions

Get Mention Details

Sentiment Analysis

Get Sentiment Overview

Get Sentiment Alerts

Influencer Discovery

Discover Influencers

Get Influencer Profile

Track Influencer ROI

Review Aggregation

Get Reviews

Respond to Review

Competitor Monitoring

Add Competitor

Get Competitor Analysis

Sales Correlation

Get Social-Sales Correlation

Webhooks

Error Responses

Related Documentation