aethex.live/docs/API_STRUCTURE.md

# AeThex LIVE - API Structure

## API Routes

### Authentication
- `POST /api/auth/register` - Create account
- `POST /api/auth/login` - Login
- `POST /api/auth/logout` - Logout
- `GET /api/auth/me` - Get current user
- `POST /api/auth/refresh` - Refresh token

### Users
- `GET /api/users/:id` - Get user profile
- `PATCH /api/users/:id` - Update profile
- `GET /api/users/:id/followers` - Get user followers
- `POST /api/users/:username/follow` - Follow user
- `DELETE /api/users/:username/follow` - Unfollow user
- `GET /api/users/:id/stats` - User statistics

### Channels
- `POST /api/channels` - Create channel
- `GET /api/channels/:slug` - Get channel
- `PATCH /api/channels/:id` - Update channel
- `DELETE /api/channels/:id` - Delete channel
- `GET /api/channels/:id/streams` - Get channel streams
- `GET /api/channels/:id/followers` - Get followers
- `POST /api/channels/:id/follow` - Follow channel
- `DELETE /api/channels/:id/follow` - Unfollow channel
- `GET /api/channels/:id/analytics` - Channel analytics
- `GET /api/channels/:id/settings` - Channel settings
- `PATCH /api/channels/:id/settings` - Update settings

### Streams & Live
- `POST /api/streams` - Create/start stream
- `GET /api/streams/:id` - Get stream details
- `PATCH /api/streams/:id` - Update stream
- `DELETE /api/streams/:id` - End stream
- `GET /api/streams/:id/viewers` - Get viewer count
- `POST /api/streams/:id/webhooks` - Stream webhooks (from provider)
- `GET /api/browse` - Browse live streams
- `GET /api/search` - Search streams
- `GET /api/recommended` - Recommended streams

### Chat (Real-time via Socket.io)
- `socket.emit('join-stream', {streamId})` - Join chat
- `socket.emit('send-message', {message})` - Send message
- `socket.emit('delete-message', {messageId})` - Delete message
- `socket.on('new-message', handler)` - Receive messages
- `socket.on('user-joined', handler)` - User joined
- `socket.on('user-left', handler)` - User left

### VOD & Archives
- `GET /api/vods/:id` - Get VOD
- `GET /api/channels/:id/vods` - Get channel VODs
- `GET /api/vods/:id/progress` - Get watch progress
- `POST /api/vods/:id/progress` - Save watch progress
- `POST /api/vods/:id/report` - Report VOD

### Clips
- `POST /api/clips` - Create clip
- `GET /api/clips/:id` - Get clip
- `PATCH /api/clips/:id` - Update clip
- `DELETE /api/clips/:id` - Delete clip
- `GET /api/channels/:id/clips` - Get channel clips
- `POST /api/clips/:id/like` - Like clip
- `DELETE /api/clips/:id/like` - Unlike clip
- `GET /api/clips/trending` - Trending clips

### Monetization
- `POST /api/subscriptions` - Create subscription
- `GET /api/subscriptions/me` - Get my subscriptions
- `DELETE /api/subscriptions/:id` - Cancel subscription
- `POST /api/donations` - Create donation
- `GET /api/donations/me` - My donations
- `GET /api/channels/:id/revenue` - Channel revenue
- `GET /api/payouts` - Get payouts
- `POST /api/payouts/request` - Request payout

### Interactions
- `POST /api/polls` - Create poll
- `GET /api/polls/:id` - Get poll
- `POST /api/polls/:id/vote` - Vote on poll
- `POST /api/reactions` - Send reaction
- `POST /api/gifts` - Send gift

### Gaming/Tournaments
- `POST /api/tournaments` - Create tournament
- `GET /api/tournaments/:id` - Get tournament
- `POST /api/tournaments/:id/join` - Join tournament
- `GET /api/leaderboards/:name` - Get leaderboard
- `GET /api/leaderboards/:name/entries/:userId` - Get user rank

### Moderation
- `GET /api/moderation/queue` - Get mod queue
- `POST /api/moderation/queue/:id/approve` - Approve
- `POST /api/moderation/queue/:id/reject` - Reject
- `POST /api/channels/:id/bans` - Ban user
- `DELETE /api/channels/:id/bans/:userId` - Unban user
- `GET /api/channels/:id/bans` - Get bans

## Real-time Events (Socket.io)

### Stream Events
- `stream:started` - Stream went live
- `stream:ended` - Stream ended
- `stream:updated` - Stream metadata changed
- `viewers:updated` - Viewer count changed
- `viewers:joined` - User joined stream
- `viewers:left` - User left stream

### Chat Events
- `chat:message` - New chat message
- `chat:deleted` - Message deleted
- `chat:cleared` - Chat cleared
- `chat:emote` - Emote sent
- `chat:ban` - User banned

### Interaction Events
- `poll:created` - Poll started
- `poll:voted` - Someone voted
- `poll:ended` - Poll ended
- `reaction:sent` - Reaction/emote displayed
- `gift:sent` - Gift displayed to chat

### Monetization Events
- `subscription:new` - New subscriber
- `donation:received` - Donation received
- `milestone:reached` - Milestone (100 followers, etc.)

## WebSocket Message Format

```json
{
  "type": "event_type",
  "payload": {
    // Event-specific data
  },
  "timestamp": "2026-02-07T12:00:00Z"
}
```

## Error Responses

```json
{
  "error": true,
  "code": "ERROR_CODE",
  "message": "Human readable message",
  "status": 400
}
```

## Rate Limiting

- Public endpoints: 100 req/min per IP
- Authenticated endpoints: 300 req/min per user
- Streaming endpoints: 50 req/min
- Chat: 5 messages/10 seconds per user

## Pagination

```
GET /api/resource?page=1&limit=20
```

Response:
```json
{
  "data": [...],
  "total": 100,
  "page": 1,
  "limit": 20,
  "hasMore": true
}
```