From df70928950cd4d1d4290aa6aa8f5dc85aa391bb2 Mon Sep 17 00:00:00 2001 From: Xoconoch Date: Sat, 23 Aug 2025 09:15:54 -0600 Subject: [PATCH] chore(docs): update api documentation --- docs/{API_DOCUMENTATION.md => api.md} | 37 +++++++++++++++------------ docs/index.md | 2 +- docs/user/albums.md | 25 ++++++++---------- docs/user/artists.md | 37 ++++++++++++--------------- docs/user/configuration.md | 9 +++---- mkdocs.yml | 2 +- 6 files changed, 51 insertions(+), 61 deletions(-) rename docs/{API_DOCUMENTATION.md => api.md} (93%) diff --git a/docs/API_DOCUMENTATION.md b/docs/api.md similarity index 93% rename from docs/API_DOCUMENTATION.md rename to docs/api.md index 5746202..42e3867 100644 --- a/docs/API_DOCUMENTATION.md +++ b/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`) -- `download_type`: Filter by type (`track`, `album`, `playlist`) -- `limit`: Results limit +- `page`: Page number (default: 1) +- `limit`: Items per page (default: 50, max: 100) +- `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 -- `field`: Field to search (`name`, `artist`, `url`) +- `q`: Search query (required) +- `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, - "keep_failed": true + "days_old": 30 } ``` @@ -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.* \ No newline at end of file +*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.* \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index d62a44b..90ac35f 100644 --- a/docs/index.md +++ b/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). \ No newline at end of file +For API details, see [API](api.md). \ No newline at end of file diff --git a/docs/user/albums.md b/docs/user/albums.md index 8eb1d97..2f3c426 100644 --- a/docs/user/albums.md +++ b/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 - - Download full album - - Download individual tracks from the tracklist -- Tracklist - - 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) \ No newline at end of file +Endpoints: +- GET `/api/album/info?id=...&limit=50&offset=...` — album metadata + paged tracks +- GET `/api/album/download/{album_id}` — queue album download +- GET `/api/prgs/stream` — live progress via SSE \ No newline at end of file diff --git a/docs/user/artists.md b/docs/user/artists.md index 40e1c56..28bda22 100644 --- a/docs/user/artists.md +++ b/docs/user/artists.md @@ -1,31 +1,26 @@ ## Artists -Open an artist from search. - -- Discography - - Albums, Singles, Compilations, Appears On sections - - Infinite loading as you scroll -- Download - - Download all (queues albums respecting filters) +- Open from Search. +- Discography sections: Albums, Singles, Compilations, Appears On (infinite scroll) +- Download: + - Download all (queues albums by selected types) - Download any album individually -- Watch - - Add/remove artist to Watchlist (auto-download new releases when enabled) +- Watch: + - Add/remove artist to Watchlist + - Configure release types and intervals in Configuration → Watch -How-to: monitor an artist - -1. Search for the artist and open their page +How to monitor an artist: +1. Search the artist and open their page 2. Click Watch -3. Configure release types and intervals in Configuration → Watch - -How-to: download discography +3. Configure in Configuration → Watch +How to download discography: 1. Open the artist page -2. Choose release types (e.g., Albums, Singles, Compilations) -3. Click Download All; track progress in Queue and History +2. Select release types (Albums, Singles, Compilations) +3. Click Download All; track in Queue and History -Backend endpoints used: - -- GET `/api/artist/info?id=...&limit=20&offset=...` (metadata + paged albums) -- GET `/api/artist/download/{artist_id}?album_type=album,single,compilation` (queue discography) +Endpoints: +- GET `/api/artist/info?id=...&limit=10&offset=...` — metadata + paged albums +- 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` \ No newline at end of file diff --git a/docs/user/configuration.md b/docs/user/configuration.md index 2b70cd1..4d71ed5 100644 --- a/docs/user/configuration.md +++ b/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` - - Firefox: devtools → Storage → 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` - 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 \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 55d5bf8..1b517da 100644 --- a/mkdocs.yml +++ b/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