Spotizerr-Phoenix API Documentation¶

A comprehensive music download service API built with FastAPI that supports Spotify content downloading, playlist/artist watching, and user authentication.

🚀 Base URL¶

http://localhost:7171/api

🔐 Authentication¶

Authentication System¶

Type: JWT-based authentication with optional SSO (Google/GitHub)
Token: Bearer token in Authorization header
When Disabled: System user with admin privileges automatically applied

Auth Status¶

Check authentication configuration and current user status.

`GET /auth/status`¶

Response:

{
  "auth_enabled": true,
  "authenticated": false,
  "user": null,
  "registration_enabled": true,
  "sso_enabled": true,
  "sso_providers": ["google", "github"]
}

`POST /auth/login`¶

Request:

{
  "username": "string",
  "password": "string"
}

Response:

{
  "access_token": "jwt-token",
  "token_type": "bearer",
  "user": {
    "username": "string",
    "email": "string",
    "role": "user|admin",
    "created_at": "2024-01-01T00:00:00",
    "last_login": "2024-01-01T00:00:00",
    "sso_provider": null,
    "is_sso_user": false
  }
}

`POST /auth/register`¶

Request:

{
  "username": "string",
  "password": "string",
  "email": "string"
}

`POST /auth/logout`¶

Logs out the current user.

User Management (Admin Only)¶

`GET /auth/users`¶

List all users.

`POST /auth/users/create`¶

Request:

{
  "username": "string",
  "password": "string",
  "email": "string",
  "role": "user|admin"
}

`DELETE /auth/users/{username}`¶

Delete a user.

`PUT /auth/users/{username}/role`¶

Request:

{
  "role": "user|admin"
}

`PUT /auth/users/{username}/password`¶

Admin password reset. Request:

{
  "new_password": "string"
}

Profile Management¶

`GET /auth/profile`¶

Get current user profile.

`PUT /auth/profile/password`¶

Change own password. Request:

{
  "current_password": "string",
  "new_password": "string"
}

SSO Authentication¶

`GET /auth/sso/status`¶

Get SSO configuration and available providers.

`GET /auth/sso/login/google`¶

Redirect to Google OAuth.

`GET /auth/sso/login/github`¶

Redirect to GitHub OAuth.

`GET /auth/sso/callback/google`¶

Google OAuth callback.

`GET /auth/sso/callback/github`¶

GitHub OAuth callback.

`POST /auth/sso/unlink/{provider}`¶

Unlink SSO provider from account.

🎵 Content Download Endpoints¶

Track Downloads¶

`GET /track/download/{track_id}`¶

Download a single track. Response:

{
  "task_id": "uuid"
}

Status Code: 202 (Accepted)

`GET /track/download/cancel`¶

Query Parameters:

task_id: Task ID to cancel

`GET /track/info`¶

Get track metadata. Query Parameters:

id: Spotify track ID

Response:

{
  "id": "string",
  "name": "string",
  "artists": [{ "name": "string" }],
  "album": { "name": "string" },
  "duration_ms": 180000,
  "explicit": false,
  "external_urls": { "spotify": "url" }
}

Album Downloads¶

`GET /album/download/{album_id}`¶

Download an entire album. Response:

{
  "task_id": "uuid"
}

`GET /album/download/cancel`¶

Query Parameters:

task_id: Task ID to cancel

`GET /album/info`¶

Get album metadata. Query Parameters:

id: Spotify album ID
limit: Tracks page size (optional)
offset: Tracks page offset (optional)

Playlist Downloads¶

`GET /playlist/download/{playlist_id}`¶

Download an entire playlist. Response:

{
  "task_id": "uuid"
}

`GET /playlist/download/cancel`¶

Query Parameters:

task_id: Task ID to cancel

`GET /playlist/info`¶

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. Query Parameters:

id: Spotify playlist ID

`GET /playlist/tracks`¶

Get playlist tracks. Query Parameters:

id: Spotify playlist ID

Artist Downloads¶

`GET /artist/download/{artist_id}`¶

Download artist's discography. Query Parameters:

album_type: Comma-separated values (album,single,compilation,appears_on)

Response:

{
  "status": "complete",
  "message": "Artist discography processing initiated. X albums queued.",
  "queued_albums": ["task_id1", "task_id2"],
  "duplicate_albums": ["existing_task_id"]
}

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

Monitor playlists and artists for new content and automatically download updates.

Playlist Watching¶

`PUT /playlist/watch/{playlist_spotify_id}`¶

Add playlist to watch list. Request:

{
  "watch_new_additions": true,
  "download_existing": false
}

`GET /playlist/watch/{playlist_spotify_id}/status`¶

Get playlist watch status.

`DELETE /playlist/watch/{playlist_spotify_id}`¶

Remove playlist from watch list.

`POST /playlist/watch/{playlist_spotify_id}/tracks`¶

Add specific tracks to watch for a playlist. Request:

{
  "track_ids": ["track_id1", "track_id2"]
}

`DELETE /playlist/watch/{playlist_spotify_id}/tracks`¶

Remove specific tracks from watch. Request:

{
  "track_ids": ["track_id1", "track_id2"]
}

`GET /playlist/watch/list`¶

List all watched playlists.

`POST /playlist/watch/trigger_check`¶

Manually trigger watch check for all playlists.

`POST /playlist/watch/trigger_check/{playlist_spotify_id}`¶

Manually trigger watch check for specific playlist.

Artist Watching¶

`PUT /artist/watch/{artist_spotify_id}`¶

Add artist to watch list. Request:

{
  "watch_new_releases": true,
  "album_types": ["album", "single"]
}

`GET /artist/watch/{artist_spotify_id}/status`¶

Get artist watch status.

`DELETE /artist/watch/{artist_spotify_id}`¶

Remove artist from watch list.

`POST /artist/watch/{artist_spotify_id}/albums`¶

Add specific albums to watch for an artist. Request:

{
  "album_ids": ["album_id1", "album_id2"]
}

`DELETE /artist/watch/{artist_spotify_id}/albums`¶

Remove specific albums from watch.

`GET /artist/watch/list`¶

List all watched artists.

`POST /artist/watch/trigger_check`¶

Manually trigger watch check for all artists.

`POST /artist/watch/trigger_check/{artist_spotify_id}`¶

Manually trigger watch check for specific artist.

🔍 Search¶

`GET /search/`¶

Search Spotify content. Query Parameters:

q: Search query (required)
search_type or type: Content type (track, album, artist, playlist, episode, show)
limit: Results limit (default: 20)
main: Account context

Response:

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "type": "track",
      "artists": [{ "name": "string" }],
      "external_urls": { "spotify": "url" }
    }
  ]
}

📊 Progress & Task Management¶

Task Monitoring¶

`GET /prgs/list`¶

List tasks with pagination. Query Parameters:

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.

`GET /prgs/updates`¶

Get task updates since last check. Query Parameters:

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. Response: Continuous stream of task updates.

Task Control¶

`POST /prgs/cancel/{task_id}`¶

Cancel a specific task.

`POST /prgs/cancel/all`¶

Cancel all running tasks.

`DELETE /prgs/delete/{task_id}`¶

Delete completed/failed task from history.

📜 Download History¶

History Retrieval¶

`GET /history/`¶

Get download history with pagination. Query Parameters:

limit: Max records (default: 100, max: 500)
offset: Records to skip (default: 0)
download_type: Filter by type (track, album, playlist)
status: Filter by status (completed, failed, skipped, in_progress)

Response:

{
  "downloads": [
    {
      "task_id": "uuid",
      "download_type": "track",
      "url": "spotify_url",
      "name": "Track Name",
      "artist": "Artist Name",
      "status": "completed",
      "created_at": "2024-01-01T00:00:00",
      "completed_at": "2024-01-01T00:05:00",
      "file_path": "/path/to/file.mp3"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "returned_count": 50
  }
}

`GET /history/{task_id}`¶

Get specific download history entry.

`GET /history/{task_id}/children`¶

Get child tasks (for album/playlist downloads).

`GET /history/stats`¶

Get download statistics.

`GET /history/search`¶

Search download history. Query Parameters:

q: Search query (required)
limit: Max results (default: 50, max: 200)

`GET /history/recent`¶

Get recent downloads. Query Parameters:

limit: Max results (default: 20, max: 100)

`GET /history/failed`¶

Get failed downloads.

`POST /history/cleanup`¶

Clean up old history entries. Request:

{
  "days_old": 30
}

⚙️ System Configuration¶

Configuration Management¶

`GET /config/`¶

Get current system configuration.

`POST /config/` / `PUT /config/`¶

Update system configuration. Request:

{
  "maxConcurrentDownloads": 3,
  "service": "spotify",
  "fallback": true,
  "spotifyQuality": "high",
  "deezerQuality": "flac",
  "realTime": true,
  "downloadPath": "/downloads",
  "fileFormat": "mp3"
}

`GET /config/check`¶

Validate current configuration.

`POST /config/validate`¶

Validate provided configuration.

Watch Configuration¶

`GET /config/watch`¶

Get watch system configuration.

`POST /config/watch` / `PUT /config/watch`¶

Update watch configuration. Request:

{
  "enabled": true,
  "check_interval": 3600,
  "max_concurrent_checks": 2,
  "retry_failed_after": 1800
}

`POST /config/watch/validate`¶

Validate watch configuration.

🔑 Credentials Management¶

Service Credentials¶

`GET /credentials/{service}`¶

List credentials for service (spotify or deezer).

`GET /credentials/{service}/{name}`¶

Get specific credential set.

`POST /credentials/{service}/{name}`¶

Create new credential set. Request:

{
  "client_id": "string",
  "client_secret": "string"
}

`PUT /credentials/{service}/{name}`¶

Update credential set.

`DELETE /credentials/{service}/{name}`¶

Delete credential set.

`GET /credentials/all/{service}`¶

Get all credentials for service.

Spotify API Configuration¶

`GET /credentials/spotify_api_config`¶

Get Spotify API configuration.

`PUT /credentials/spotify_api_config`¶

Update Spotify API configuration.

`GET /credentials/markets`¶

Get available Spotify markets.

🚨 Error Handling¶

HTTP Status Codes¶

200: Success
202: Accepted (async operations)
400: Bad Request (validation errors)
401: Unauthorized (auth required)
403: Forbidden (insufficient permissions)
404: Not Found
409: Conflict (duplicate downloads)
500: Internal Server Error

Error Response Format¶

{
  "error": "Error description",
  "details": "Additional details",
  "traceback": "Stack trace (dev mode)"
}

Common Error Scenarios¶

Duplicate Downloads: 409 status with existing task ID
Missing Spotify Metadata: 404 when track/album/playlist not found
Invalid Credentials: Authentication errors when service credentials are wrong
Rate Limiting: Temporary failures when hitting Spotify API limits

💡 Usage Examples¶

Download a Track¶

curl -X GET "http://localhost:7171/api/track/download/4iV5W9uYEdYUVa79Axb7Rh" \
  -H "Authorization: Bearer your-jwt-token"

Search for Music¶

curl -X GET "http://localhost:7171/api/search/?q=bohemian%20rhapsody&search_type=track" \
  -H "Authorization: Bearer your-jwt-token"

Monitor Progress with SSE¶

const eventSource = new EventSource("/api/prgs/stream");
eventSource.onmessage = function (event) {
  const data = JSON.parse(event.data);
  console.log("Progress update:", data);
};

Add Playlist to Watch¶

curl -X PUT "http://localhost:7171/api/playlist/watch/37i9dQZF1DXcBWIGoYBM5M" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"watch_new_additions": true, "download_existing": false}'

🔧 Development Notes¶

Authentication Middleware¶

Routes are protected by require_auth_from_state dependency
Admin routes use require_admin_from_state dependency
When auth is disabled, system returns mock admin user

Task System¶

All downloads are async using Celery
Progress tracked via Redis
Real-time updates via SSE
Task cancellation supported

File Structure¶

Downloads stored in configurable directory
Metadata stored in JSON files
History persisted in database

Rate Limiting¶

Spotify API rate limits respected
Concurrent download limits configurable
Retry logic for failed requests

This documentation covers all endpoints discovered in the Spotizerr-Phoenix routes directory. The API is designed for high-throughput music downloading with comprehensive monitoring and management capabilities.

Spotizerr-Phoenix API Documentation¶

🚀 Base URL¶

🔐 Authentication¶

Authentication System¶

Auth Status¶

GET /auth/status¶

Login & Registration¶

POST /auth/login¶

POST /auth/register¶

POST /auth/logout¶

User Management (Admin Only)¶

GET /auth/users¶

POST /auth/users/create¶

DELETE /auth/users/{username}¶

PUT /auth/users/{username}/role¶

PUT /auth/users/{username}/password¶

Profile Management¶

GET /auth/profile¶

PUT /auth/profile/password¶

SSO Authentication¶

GET /auth/sso/status¶

GET /auth/sso/login/google¶

GET /auth/sso/login/github¶

GET /auth/sso/callback/google¶

GET /auth/sso/callback/github¶

POST /auth/sso/unlink/{provider}¶

🎵 Content Download Endpoints¶

Track Downloads¶

GET /track/download/{track_id}¶

GET /track/download/cancel¶

GET /track/info¶

Album Downloads¶

GET /album/download/{album_id}¶

GET /album/download/cancel¶

GET /album/info¶

Playlist Downloads¶

GET /playlist/download/{playlist_id}¶

GET /playlist/download/cancel¶

GET /playlist/info¶

GET /playlist/metadata¶

GET /playlist/tracks¶

Artist Downloads¶

GET /artist/download/{artist_id}¶

GET /artist/info¶

📺 Watch Functionality¶

Playlist Watching¶

PUT /playlist/watch/{playlist_spotify_id}¶

GET /playlist/watch/{playlist_spotify_id}/status¶

DELETE /playlist/watch/{playlist_spotify_id}¶

POST /playlist/watch/{playlist_spotify_id}/tracks¶

DELETE /playlist/watch/{playlist_spotify_id}/tracks¶

GET /playlist/watch/list¶

POST /playlist/watch/trigger_check¶

POST /playlist/watch/trigger_check/{playlist_spotify_id}¶

Artist Watching¶

PUT /artist/watch/{artist_spotify_id}¶

GET /artist/watch/{artist_spotify_id}/status¶

DELETE /artist/watch/{artist_spotify_id}¶

POST /artist/watch/{artist_spotify_id}/albums¶

DELETE /artist/watch/{artist_spotify_id}/albums¶

GET /artist/watch/list¶

POST /artist/watch/trigger_check¶

POST /artist/watch/trigger_check/{artist_spotify_id}¶

🔍 Search¶

GET /search/¶

📊 Progress & Task Management¶

Task Monitoring¶

GET /prgs/list¶

GET /prgs/{task_id}¶

GET /prgs/updates¶

GET /prgs/stream¶

Task Control¶

POST /prgs/cancel/{task_id}¶

POST /prgs/cancel/all¶

DELETE /prgs/delete/{task_id}¶

📜 Download History¶

History Retrieval¶

GET /history/¶

GET /history/{task_id}¶

GET /history/{task_id}/children¶

`GET /auth/status`¶

`POST /auth/login`¶

`POST /auth/register`¶

`POST /auth/logout`¶

`GET /auth/users`¶

`POST /auth/users/create`¶

`DELETE /auth/users/{username}`¶

`PUT /auth/users/{username}/role`¶

`PUT /auth/users/{username}/password`¶

`GET /auth/profile`¶

`PUT /auth/profile/password`¶

`GET /auth/sso/status`¶

`GET /auth/sso/login/google`¶

`GET /auth/sso/login/github`¶

`GET /auth/sso/callback/google`¶

`GET /auth/sso/callback/github`¶

`POST /auth/sso/unlink/{provider}`¶

`GET /track/download/{track_id}`¶

`GET /track/download/cancel`¶

`GET /track/info`¶

`GET /album/download/{album_id}`¶

`GET /album/download/cancel`¶

`GET /album/info`¶

`GET /playlist/download/{playlist_id}`¶

`GET /playlist/download/cancel`¶

`GET /playlist/info`¶

`GET /playlist/metadata`¶

`GET /playlist/tracks`¶

`GET /artist/download/{artist_id}`¶

`GET /artist/info`¶

`PUT /playlist/watch/{playlist_spotify_id}`¶

`GET /playlist/watch/{playlist_spotify_id}/status`¶

`DELETE /playlist/watch/{playlist_spotify_id}`¶

`POST /playlist/watch/{playlist_spotify_id}/tracks`¶

`DELETE /playlist/watch/{playlist_spotify_id}/tracks`¶

`GET /playlist/watch/list`¶

`POST /playlist/watch/trigger_check`¶

`POST /playlist/watch/trigger_check/{playlist_spotify_id}`¶

`PUT /artist/watch/{artist_spotify_id}`¶

`GET /artist/watch/{artist_spotify_id}/status`¶

`DELETE /artist/watch/{artist_spotify_id}`¶

`POST /artist/watch/{artist_spotify_id}/albums`¶

`DELETE /artist/watch/{artist_spotify_id}/albums`¶

`GET /artist/watch/list`¶

`POST /artist/watch/trigger_check`¶

`POST /artist/watch/trigger_check/{artist_spotify_id}`¶

`GET /search/`¶

`GET /prgs/list`¶

`GET /prgs/{task_id}`¶

`GET /prgs/updates`¶

`GET /prgs/stream`¶

`POST /prgs/cancel/{task_id}`¶

`POST /prgs/cancel/all`¶

`DELETE /prgs/delete/{task_id}`¶

`GET /history/`¶

`GET /history/{task_id}`¶

`GET /history/{task_id}/children`¶

`GET /history/stats`¶

`GET /history/search`¶

`GET /history/recent`¶

`GET /history/failed`¶

`POST /history/cleanup`¶

`GET /config/`¶

`POST /config/` / `PUT /config/`¶

`GET /config/check`¶

`POST /config/validate`¶

`GET /config/watch`¶

`POST /config/watch` / `PUT /config/watch`¶

`POST /config/watch/validate`¶

`GET /credentials/{service}`¶

`GET /credentials/{service}/{name}`¶

`POST /credentials/{service}/{name}`¶

`PUT /credentials/{service}/{name}`¶

`DELETE /credentials/{service}/{name}`¶

`GET /credentials/all/{service}`¶

`GET /credentials/spotify_api_config`¶

`PUT /credentials/spotify_api_config`¶

`GET /credentials/markets`¶