JDM170/spotizerr-dev
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(docs): update api documentation

Browse Source
This commit is contained in:
Xoconoch
2025-08-23 09:15:54 -06:00
parent 74721db1c9
commit df70928950
6 changed files with 51 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/API_DOCUMENTATION.md → docs/api.md
View File

@@ -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.*
*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.*

2
docs/index.md
View File

@@ -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).

25
docs/user/albums.md
View File

@@ -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)
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

37
docs/user/artists.md
View File

@@ -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`

9
docs/user/configuration.md
View File

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