chore(docs): update api documentation

docs/api.md

@@ -129,7 +129,7 @@ Get SSO configuration and available providers.
 #### `GET /auth/sso/login/google`
 Redirect to Google OAuth.
 
-#### `GET /auth/sso/login/github`  
+#### `GET /auth/sso/login/github`
 Redirect to GitHub OAuth.
 
 #### `GET /auth/sso/callback/google`
@@ -168,7 +168,7 @@ Get track metadata.
 ```json
 {
   "id": "string",
-  "name": "string", 
+  "name": "string",
   "artists": [{"name": "string"}],
   "album": {"name": "string"},
   "duration_ms": 180000,
@@ -196,6 +196,8 @@ Download an entire album.
 Get album metadata.
 **Query Parameters:**
 - `id`: Spotify album ID
+- `limit`: Tracks page size (optional)
+- `offset`: Tracks page offset (optional)
 
 ### Playlist Downloads
 
@@ -216,6 +218,7 @@ Download an entire playlist.
 Get playlist metadata.
 **Query Parameters:**
 - `id`: Spotify playlist ID
+- `include_tracks`: true to include tracks (default: false)
 
 #### `GET /playlist/metadata`
 Get detailed playlist metadata including tracks.
@@ -244,14 +247,12 @@ Download artist's discography.
 }
 ```
 
-#### `GET /artist/download/cancel`
-**Query Parameters:**
-- `task_id`: Task ID to cancel
-
 #### `GET /artist/info`
 Get artist metadata.
 **Query Parameters:**
 - `id`: Spotify artist ID
+- `limit`: Albums page size (default: 10, min: 1)
+- `offset`: Albums page offset (default: 0, min: 0)
 
 ## 📺 Watch Functionality
 
@@ -371,11 +372,11 @@ Search Spotify content.
 ### Task Monitoring
 
 #### `GET /prgs/list`
-List all tasks with optional filtering.
+List tasks with pagination.
 **Query Parameters:**
-- `status`: Filter by status (`pending`, `running`, `completed`, `failed`)
+- `page`: Page number (default: 1)
-- `download_type`: Filter by type (`track`, `album`, `playlist`)
+- `limit`: Items per page (default: 50, max: 100)
-- `limit`: Results limit
+- `active_only`: If true, only return active tasks
 
 #### `GET /prgs/{task_id}`
 Get specific task details and progress.
@@ -383,7 +384,10 @@ Get specific task details and progress.
 #### `GET /prgs/updates`
 Get task updates since last check.
 **Query Parameters:**
-- `since`: Timestamp to get updates since
+- `since`: Unix timestamp (required for delta updates). If omitted, returns a paginated snapshot.
+- `page`: Page number for non-active tasks (default: 1)
+- `limit`: Items per page for non-active tasks (default: 20, max: 100)
+- `active_only`: If true, only return active tasks
 
 #### `GET /prgs/stream`
 **Server-Sent Events (SSE)** endpoint for real-time progress updates.
@@ -448,13 +452,13 @@ Get download statistics.
 #### `GET /history/search`
 Search download history.
 **Query Parameters:**
-- `q`: Search query
+- `q`: Search query (required)
-- `field`: Field to search (`name`, `artist`, `url`)
+- `limit`: Max results (default: 50, max: 200)
 
 #### `GET /history/recent`
 Get recent downloads.
 **Query Parameters:**
-- `hours`: Hours to look back (default: 24)
+- `limit`: Max results (default: 20, max: 100)
 
 #### `GET /history/failed`
 Get failed downloads.
@@ -464,8 +468,7 @@ Clean up old history entries.
 **Request:**
 ```json
 {
-  "older_than_days": 30,
+  "days_old": 30
-  "keep_failed": true
 }
 ```
 
@@ -641,4 +644,4 @@ curl -X PUT "http://localhost:7171/api/playlist/watch/37i9dQZF1DXcBWIGoYBM5M" \
 
 ---
 
-*This documentation covers all endpoints discovered in the Spotizerr routes directory. The API is designed for high-throughput music downloading with comprehensive monitoring and management capabilities.* 
+*This documentation covers all endpoints discovered in the Spotizerr routes directory. The API is designed for high-throughput music downloading with comprehensive monitoring and management capabilities.*

docs/index.md

@@ -13,4 +13,4 @@ Start with Getting started, then explore the sections below.
 - [History](user/history.md)
 - [Multi-user](user/multi-user.md)
 
-For API details, see [API](API_DOCUMENTATION.md).
+For API details, see [API](api.md).

docs/user/albums.md

@@ -1,18 +1,13 @@
 ## Albums
 
-Open an album from search or artist page.
+- Open from Search or an Artist page.
+- Actions:
+  - Download full album or any track
+  - Browse tracklist (order, artists, duration)
+  - Large albums: tracks load in pages as you scroll
+- Explicit filter hides explicit tracks when enabled in Config
 
-- Download
+Endpoints:
-  - Download full album
+- GET `/api/album/info?id=...&limit=50&offset=...` — album metadata + paged tracks
-  - Download individual tracks from the tracklist
+- GET `/api/album/download/{album_id}` — queue album download
-- Tracklist
+- GET `/api/prgs/stream` — live progress via SSE
-  - Shows order, artists, and duration
-  - Respects explicit filter (hidden if enabled)
-- Large albums
-  - Tracks load progressively as you scroll
-
-Backend endpoints used:
-
-- GET `/api/album/info?id=...&limit=50&offset=...` (metadata + paged tracks)
-- GET `/api/album/download/{album_id}` (queue download)
-- GET `/api/progress/stream` (live queue updates)

docs/user/artists.md

@@ -1,31 +1,26 @@
 ## Artists
 
-Open an artist from search.
+- Open from Search.
-
+- Discography sections: Albums, Singles, Compilations, Appears On (infinite scroll)
-- Discography
+- Download:
-  - Albums, Singles, Compilations, Appears On sections
+  - Download all (queues albums by selected types)
-  - Infinite loading as you scroll
-- Download
-  - Download all (queues albums respecting filters)
   - Download any album individually
-- Watch
+- Watch:
-  - Add/remove artist to Watchlist (auto-download new releases when enabled)
+  - Add/remove artist to Watchlist
+  - Configure release types and intervals in Configuration → Watch
 
-How-to: monitor an artist
+How to monitor an artist:
-
+1. Search the artist and open their page
-1. Search for the artist and open their page
 2. Click Watch
-3. Configure release types and intervals in Configuration → Watch
+3. Configure in Configuration → Watch
-
-How-to: download discography
 
+How to download discography:
 1. Open the artist page
-2. Choose release types (e.g., Albums, Singles, Compilations)
+2. Select release types (Albums, Singles, Compilations)
-3. Click Download All; track progress in Queue and History
+3. Click Download All; track in Queue and History
 
-Backend endpoints used:
+Endpoints:
-
+- GET `/api/artist/info?id=...&limit=10&offset=...` — metadata + paged albums
-- GET `/api/artist/info?id=...&limit=20&offset=...` (metadata + paged albums)
+- GET `/api/artist/download/{artist_id}?album_type=album,single,compilation` — queue discography
-- GET `/api/artist/download/{artist_id}?album_type=album,single,compilation` (queue discography)
 - PUT `/api/artist/watch/{artist_id}` / DELETE `/api/artist/watch/{artist_id}`
 - GET `/api/artist/watch/{artist_id}/status`

docs/user/configuration.md

@@ -9,7 +9,7 @@ Open Configuration in the web UI. Tabs:
 - Downloads (admin)
   - Concurrent downloads, retry behavior
   - Quality/format defaults and conversion
-  - Real-time mode (Spotify only): aligns download time with track length
+  - Real-time mode: aligns download time with track length
 - Formatting (admin)
   - File/folder naming patterns (examples)
     - `%artist%/%album%/%tracknum%. %title%`
@@ -17,8 +17,8 @@ Open Configuration in the web UI. Tabs:
 - Accounts (admin)
   - Spotify: use `spotizerr-auth` to add credentials
   - Deezer ARL (optional):
-    - Chrome/Edge: devtools → Application → Cookies → https://www.deezer.com → copy `arl`
+    - Chrome/Edge: DevTools → Application → Cookies → https://www.deezer.com → copy `arl`
-    - Firefox: devtools → Storage → Cookies → https://www.deezer.com → copy `arl`
+    - Firefox: DevTools → Storage → Cookies → https://www.deezer.com → copy `arl`
     - Paste ARL in Accounts
   - Select main account when multiple exist
 - Watch (admin)
@@ -31,17 +31,14 @@ Open Configuration in the web UI. Tabs:
   - Change password, view role and email
 
 Quality formats (reference):
-
 - Spotify: OGG 96k/160k/320k (320k requires Premium)
 - Deezer: MP3 128k/320k (320k may require Premium), FLAC (Premium)
 - Conversion: MP3/FLAC/AAC/OGG/OPUS/WAV/ALAC with custom bitrate
 
 Fallback system:
-
 - Configure primary and fallback services
 - Automatically switches if primary fails (useful for geo/account limits)
 
 Notes:
-
 - Explicit content filter applies in pages (e.g., hides explicit tracks on album/playlist views)
 - Watch system must be enabled before adding items

mkdocs.yml

@@ -21,7 +21,7 @@ nav:
   - Watchlist: user/watchlist
   - History: user/history
   - Multi-user: user/multi-user
-  - API: API_DOCUMENTATION
+  - API: api
 markdown_extensions:
   - toc:
       permalink: true