# Recommendation Service API

> 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

1. [Personalized Feeds](#personalized-feeds)
2. [Discovery](#discovery)
3. [Similar Content](#similar-content)
4. [Trending](#trending)
5. [Search](#search)

---

## 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 |
