REST API documentation for the Aphrodite Recommendation Service.
Base URL: https://api.aphrodite.example.com/api/v1/recommendations
Port: 7004 Authentication: JWT Bearer Token
Table of Contents#
Personalized Feeds#
Get Personalized Home Feed#
http
GET /personalized-home?cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
Response (200 OK):
json
{
"success": true,
"data": {
"sections": [
{
"id": "live_followed",
"type": "carousel",
"title": "Live Now from Creators You Follow",
"items": [
{
"type": "stream",
"id": "str_abc123",
"creator": {
"id": "usr_xyz789",
"username": "janedoe",
"displayName": "Jane Doe",
"avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_xyz789.jpg",
"verified": true
},
"title": "Saturday Night Stream",
"thumbnailUrl": "https://cdn.aphrodite.example.com/thumbnails/str_abc123.jpg",
"viewerCount": 1250,
"startedAt": "2026-01-18T20:00:00.000Z",
"tags": ["chat", "music"],
"isLive": true
}
],
"seeMoreUrl": "/api/v1/recommendations/live-following"
},
{
"id": "for_you",
"type": "grid",
"title": "For You",
"items": [
{
"type": "creator",
"id": "usr_rec1",
"username": "recommended1",
"displayName": "Recommended Creator",
"avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_rec1.jpg",
"bio": "Entertainment and fun!",
"isLive": false,
"followerCount": 25000,
"reason": "Similar to creators you follow"
}
],
"seeMoreUrl": "/api/v1/recommendations/for-you"
},
{
"id": "trending",
"type": "carousel",
"title": "Trending Now",
"items": [...]
},
{
"id": "new_content",
"type": "grid",
"title": "New from Your Subscriptions",
"items": [...]
}
],
"refreshedAt": "2026-01-18T20:00:00.000Z"
}
}
Get For You Feed#
http
GET /for-you?cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
Response (200 OK):
json
{
"success": true,
"data": [
{
"type": "creator",
"id": "usr_rec1",
"username": "recommended1",
"displayName": "Recommended Creator",
"avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_rec1.jpg",
"bannerUrl": "https://cdn.aphrodite.example.com/banners/usr_rec1.jpg",
"bio": "Entertainment and fun streams!",
"isLive": true,
"currentStream": {
"id": "str_rec1",
"title": "Gaming Night",
"viewerCount": 450
},
"stats": {
"followers": 25000,
"avgViewers": 500
},
"tags": ["gaming", "entertainment"],
"recommendation": {
"reason": "Similar to janedoe who you follow",
"score": 0.92,
"factors": [
{ "type": "similar_content", "weight": 0.4 },
{ "type": "viewer_overlap", "weight": 0.35 },
{ "type": "category_match", "weight": 0.25 }
]
}
}
],
"pagination": {
"cursor": "next_cursor",
"hasMore": true
},
"meta": {
"algorithm": "hybrid_v2",
"personalizationLevel": "high"
}
}
Get Because You Watched#
http
GET /because-you-watched/:creatorId?limit=10
Authorization: Bearer <access_token>
Response (200 OK):
json
{
"success": true,
"data": {
"basedOn": {
"id": "usr_xyz789",
"username": "janedoe",
"displayName": "Jane Doe"
},
"recommendations": [
{
"type": "creator",
"id": "usr_sim1",
"username": "similar1",
"displayName": "Similar Creator 1",
"avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_sim1.jpg",
"isLive": false,
"stats": {
"followers": 18000
},
"similarity": 0.87
}
]
}
}
Discovery#
Get Discover Feed#
http
GET /discover?category=all&cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
category |
string | Category filter: all, gaming, music, etc. |
sort |
string | Sort: recommended, popular, new |
tags |
string | Comma-separated tags |
live |
boolean | Filter to live streams only |
Response (200 OK):
json
{
"success": true,
"data": {
"featured": [
{
"type": "stream",
"id": "str_featured1",
"creator": {
"id": "usr_featured1",
"username": "featuredcreator",
"displayName": "Featured Creator",
"verified": true
},
"title": "Special Event Stream",
"thumbnailUrl": "https://cdn.aphrodite.example.com/thumbnails/str_featured1.jpg",
"viewerCount": 5000,
"isLive": true,
"featuredReason": "Staff Pick"
}
],
"categories": [
{
"id": "gaming",
"name": "Gaming",
"thumbnailUrl": "https://cdn.aphrodite.example.com/categories/gaming.jpg",
"liveCount": 245,
"viewerCount": 45000
}
],
"streams": [
{
"type": "stream",
"id": "str_disc1",
"creator": {
"id": "usr_disc1",
"username": "discoveredcreator",
"displayName": "Discovered Creator"
},
"title": "Evening Stream",
"thumbnailUrl": "https://cdn.aphrodite.example.com/thumbnails/str_disc1.jpg",
"viewerCount": 320,
"isLive": true,
"tags": ["chat", "music"]
}
]
},
"pagination": {
"cursor": "next_cursor",
"hasMore": true
}
}
Get Category#
http
GET /categories/:categoryId?sort=popular&cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
Response (200 OK):
json
{
"success": true,
"data": {
"category": {
"id": "gaming",
"name": "Gaming",
"description": "Live gaming streams",
"thumbnailUrl": "https://cdn.aphrodite.example.com/categories/gaming.jpg",
"stats": {
"liveStreams": 245,
"totalViewers": 45000,
"totalCreators": 1250
}
},
"subcategories": [
{ "id": "fps", "name": "FPS Games", "liveCount": 85 },
{ "id": "rpg", "name": "RPG Games", "liveCount": 62 }
],
"streams": [
{
"id": "str_game1",
"creator": {
"id": "usr_gamer1",
"username": "progamer",
"displayName": "Pro Gamer"
},
"title": "Ranked Matches",
"viewerCount": 1500,
"isLive": true
}
]
},
"pagination": {
"cursor": "next_cursor",
"hasMore": true
}
}
Get All Categories#
http
GET /categories
Authorization: Bearer <access_token>
Response (200 OK):
json
{
"success": true,
"data": [
{
"id": "gaming",
"name": "Gaming",
"thumbnailUrl": "https://cdn.aphrodite.example.com/categories/gaming.jpg",
"liveCount": 245,
"viewerCount": 45000
},
{
"id": "music",
"name": "Music",
"thumbnailUrl": "https://cdn.aphrodite.example.com/categories/music.jpg",
"liveCount": 128,
"viewerCount": 22000
},
{
"id": "chat",
"name": "Just Chatting",
"thumbnailUrl": "https://cdn.aphrodite.example.com/categories/chat.jpg",
"liveCount": 520,
"viewerCount": 85000
}
]
}
Similar Content#
Get Similar Creators#
http
GET /similar-creators/:creatorId?limit=10
Authorization: Bearer <access_token>
Response (200 OK):
json
{
"success": true,
"data": {
"basedOn": {
"id": "usr_xyz789",
"username": "janedoe"
},
"similar": [
{
"id": "usr_sim1",
"username": "similar1",
"displayName": "Similar Creator 1",
"avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_sim1.jpg",
"bio": "Entertainment streams",
"isLive": true,
"currentStream": {
"viewerCount": 450
},
"stats": {
"followers": 18000
},
"similarity": {
"score": 0.87,
"reasons": [
"Similar content style",
"Shared audience",
"Same category"
]
}
}
]
}
}
Get Related Content#
http
GET /related/:contentId?type=vod&limit=10
Authorization: Bearer <access_token>
Response (200 OK):
json
{
"success": true,
"data": {
"basedOn": {
"id": "vod_abc123",
"title": "Best Moments January"
},
"related": [
{
"id": "vod_rel1",
"type": "vod",
"title": "Best Moments December",
"creator": {
"id": "usr_xyz789",
"username": "janedoe"
},
"thumbnailUrl": "https://cdn.aphrodite.example.com/thumbnails/vod_rel1.jpg",
"duration": 1800,
"views": 5200,
"relevance": 0.92
}
]
}
}
Trending#
Get Trending Streams#
http
GET /trending?period=now&limit=20
Authorization: Bearer <access_token>
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
period |
string | now, today, week |
category |
string | Optional category filter |
Response (200 OK):
json
{
"success": true,
"data": [
{
"rank": 1,
"change": "+2",
"stream": {
"id": "str_trend1",
"creator": {
"id": "usr_trend1",
"username": "trendingcreator",
"displayName": "Trending Creator",
"avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_trend1.jpg",
"verified": true
},
"title": "Viral Stream",
"thumbnailUrl": "https://cdn.aphrodite.example.com/thumbnails/str_trend1.jpg",
"viewerCount": 8500,
"peakViewers": 12000,
"startedAt": "2026-01-18T18:00:00.000Z"
},
"trendingScore": 95.2,
"trendingFactors": {
"viewerGrowth": 0.45,
"chatActivity": 0.3,
"socialMentions": 0.25
}
}
],
"meta": {
"period": "now",
"updatedAt": "2026-01-18T20:00:00.000Z"
}
}
Get Trending Creators#
http
GET /trending/creators?period=week&limit=20
Authorization: Bearer <access_token>
Response (200 OK):
json
{
"success": true,
"data": [
{
"rank": 1,
"previousRank": 3,
"creator": {
"id": "usr_rising1",
"username": "risingstar",
"displayName": "Rising Star",
"avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_rising1.jpg",
"bio": "New creator making waves",
"isLive": false,
"stats": {
"followers": 45000,
"followerGrowth": 12500,
"avgViewers": 1200
}
},
"growth": {
"followers": "+38.5%",
"avgViewers": "+55.2%",
"engagement": "+42.0%"
}
}
],
"meta": {
"period": "week",
"updatedAt": "2026-01-18T00:00:00.000Z"
}
}
Get Trending Tags#
http
GET /trending/tags?limit=20
Authorization: Bearer <access_token>
Response (200 OK):
json
{
"success": true,
"data": [
{
"rank": 1,
"tag": "newgame2026",
"displayName": "New Game 2026",
"streamCount": 450,
"viewerCount": 125000,
"growth": "+250%"
},
{
"rank": 2,
"tag": "justchatting",
"displayName": "Just Chatting",
"streamCount": 1250,
"viewerCount": 85000,
"growth": "+5%"
}
]
}
Search#
Search All#
http
GET /search?q=gaming&type=all&cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
q |
string | Search query (min 2 characters) |
type |
string | Filter: all, creators, streams, content, categories |
live |
boolean | Filter to live streams only |
sort |
string | Sort: relevance, popular, recent |
Response (200 OK):
json
{
"success": true,
"data": {
"query": "gaming",
"results": {
"creators": {
"count": 45,
"items": [
{
"id": "usr_gamer1",
"username": "gamingpro",
"displayName": "Gaming Pro",
"avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_gamer1.jpg",
"isLive": true,
"followers": 125000,
"relevance": 0.95
}
]
},
"streams": {
"count": 128,
"items": [
{
"id": "str_search1",
"title": "Gaming Marathon",
"creator": {
"id": "usr_gamer2",
"username": "marathongamer"
},
"viewerCount": 850,
"isLive": true,
"relevance": 0.92
}
]
},
"categories": {
"count": 3,
"items": [
{
"id": "gaming",
"name": "Gaming",
"thumbnailUrl": "https://cdn.aphrodite.example.com/categories/gaming.jpg",
"liveCount": 245
}
]
},
"content": {
"count": 520,
"items": [
{
"id": "vod_search1",
"title": "Best Gaming Moments",
"type": "vod",
"creator": {
"id": "usr_gamer1",
"username": "gamingpro"
},
"thumbnailUrl": "https://cdn.aphrodite.example.com/thumbnails/vod_search1.jpg",
"views": 12500
}
]
}
},
"suggestions": ["gaming streams", "gaming highlights", "gaming tutorials"]
},
"pagination": {
"cursor": "next_cursor",
"hasMore": true
}
}
Search Suggestions#
http
GET /search/suggestions?q=gam
Authorization: Bearer <access_token>
Response (200 OK):
json
{
"success": true,
"data": {
"query": "gam",
"suggestions": [
{ "type": "query", "text": "gaming", "count": 245 },
{ "type": "query", "text": "game night", "count": 45 },
{ "type": "creator", "text": "gamingpro", "id": "usr_gamer1" },
{ "type": "category", "text": "Gaming", "id": "gaming" }
]
}
}
Data Types#
Recommendation Item#
typescript
interface RecommendationItem {
type: 'creator' | 'stream' | 'content' | 'category';
id: string;
recommendation?: {
reason: string;
score: number;
factors?: RecommendationFactor[];
};
}
interface RecommendationFactor {
type: string;
weight: number;
}
Trending Item#
typescript
interface TrendingItem {
rank: number;
previousRank?: number;
change?: string;
trendingScore: number;
trendingFactors?: Record<string, number>;
}
Document History#
| Date | Version | Changes |
|---|---|---|
| 2026-01-18 | 1.0.0 | Initial Recommendation Service API docs |