# Task 5: Watchlist API Structure Documentation

## Base URL
`http://localhost:3000/api/watchlist`

## Available Endpoints

### 1. GET /api/watchlist
- **Description**: List all watchlist items for current user
- **Auth**: Required (JWT Bearer token)
- **Query Params**: 
  - `status` (optional): Filter by status (active, paused, completed, archived)
- **Response 200**: `{"watchlist": [], "total": 0, "filters": {"status": null}}`
- **Response 403**: `{"detail": "Not authenticated"}`

### 2. POST /api/watchlist
- **Description**: Add a new anime to the watchlist
- **Auth**: Required
- **Body**: 
  ```json
  {
    "anime_title": "string",
    "anime_url": "string",
    "provider_id": "string",
    "lang": "vostfr",
    "auto_download": true,
    "quality_preference": "auto",
    "poster_image": "string (optional)",
    "cover_image": "string (optional)",
    "synopsis": "string (optional)",
    "genres": ["string"] (optional)
  }
  ```
- **Response**: `{"status": "added", "item": {...}}`

### 3. GET /api/watchlist/{item_id}
- **Description**: Get details of a specific watchlist item
- **Auth**: Required
- **Response 200**: `{"item": {...}}`
- **Response 404**: `{"detail": "Watchlist item not found"}`
- **Response 403**: `{"detail": "Access denied"}`

### 4. PUT /api/watchlist/{item_id}
- **Description**: Update a watchlist item
- **Auth**: Required
- **Response**: `{"status": "updated", "item": {...}}`

### 5. DELETE /api/watchlist/{item_id}
- **Description**: Remove an anime from the watchlist
- **Auth**: Required
- **Response**: `{"status": "deleted", "item_id": "string"}`

### 6. GET /api/watchlist/{item_id}/episodes
- **Description**: Get all downloaded episodes for a watchlist item
- **Auth**: Required

### 7. POST /api/watchlist/{item_id}/download/{episode}
- **Description**: Download a specific episode
- **Auth**: Required
- **Response**: `{"status": "downloading", "task_id": "string", "episode": int, "item_id": "string"}`

### 8. GET /api/watchlist/stats ⚠️ BUG
- **Description**: Get watchlist statistics
- **Auth**: Required
- **Expected Response**: 
  ```json
  {
    "total": 0,
    "active": 0,
    "paused": 0,
    "completed": 0,
    "archived": 0,
    "auto_download_enabled": 0,
    "total_episodes_downloaded": 0,
    "providers": {}
  }
  ```
- **Actual Response**: 404 "Watchlist item not found" (ROUTING BUG)

### 9. GET /api/watchlist/settings ⚠️ BUG
- **Description**: Get watchlist settings
- **Auth**: Required
- **Expected Response**: `{"settings": {...}}`
- **Actual Response**: 404 "Watchlist item not found" (ROUTING BUG)

### 10. GET /api/watchlist/notifications ⚠️ BUG
- **Description**: Get user notifications
- **Auth**: Required
- **Query Params**: `unread_only` (bool)
- **Expected Response**: `{"notifications": [], "total": 0, "unread_only": false}`
- **Actual Response**: 404 "Watchlist item not found" (ROUTING BUG)

### 11. PUT /api/watchlist/notifications/{notification_id}/read
- **Description**: Mark a notification as read
- **Auth**: Required

### 12. PUT /api/watchlist/settings
- **Description**: Update watchlist settings
- **Auth**: Required

## Authentication
- Uses JWT Bearer tokens
- Token obtained from POST /api/auth/login
- Pass as: `Authorization: Bearer <token>`

## Bug Summary
- **Issue**: 3 endpoints return 404 instead of correct responses
- **Affected**: /stats, /settings, /notifications
- **Cause**: Route ordering - `/{item_id}` catch-all defined before these specific routes
- **Location**: app/routes/watchlist.py
- **Fix needed**: Move specific routes BEFORE the `/{item_id}` route