API Reference¶

Downtify exposes a JSON REST API used by the web UI. All endpoints are served on the same port as the web UI (default: 8000).

General¶

GET /api/version¶

Returns the current Downtify version as a plain string.

Response: "2.6.0"

Search & resolve¶

GET /api/songs/search¶

Search YouTube Music by free text.

Response: Array of song objects (up to 20 results).

GET /api/song/url¶

Resolve a Spotify URL to metadata.

Response:

• Track URL → single song object
• Album URL → array of song objects
• Playlist URL → array of song objects

GET /api/url is an alias for this endpoint.

Downloads¶

POST /api/download/url¶

Download a single track. Blocks until complete.

Response: Filename string of the downloaded file.

POST /api/download/batch¶

Download multiple tracks concurrently (up to 4 at a time). Returns immediately; progress is broadcast over WebSocket.

Request body:

{
  "songs": [ /* array of song objects */ ],
  "playlist_url": "https://open.spotify.com/playlist/…",
  "generate_m3u": true
}

Response:

{
  "job_ids": ["track_id_1", "track_id_2"],
  "count": 2
}

Queue¶

GET /api/queue¶

List all download jobs (queued, in progress, done, error).

Response: Array of job objects.

DELETE /api/queue¶

Clear the entire download queue/history.

Response: { "cleared": true }

DELETE /api/queue/item¶

Remove a single job from the queue.

Response: { "removed": true } or { "removed": false }

Settings¶

GET /api/settings¶

Return the current settings.

Response:

{
  "audio_providers": ["youtube-music"],
  "lyrics_providers": ["lrclib"],
  "download_lyrics": true,
  "format": "mp3",
  "bitrate": "320",
  "output": "{artists} - {title}.{output-ext}",
  "generate_m3u": true,
  "organize_by_artist": false
}

POST /api/settings/update¶

Update one or more settings. Takes effect immediately and is persisted to disk.

Request body: Partial settings object with any subset of the fields above.

Response: Full settings object after the update.

File management¶

GET /list¶

List all audio files in the downloads directory (recursive).

Response: Sorted array of relative paths (e.g. ["My Playlist/Song.mp3", "Artist - Track.mp3"]).

DELETE /delete¶

Delete a downloaded file.

Response: { "deleted": true } or { "deleted": false, "error": "…" }

GET /cover¶

Return the embedded cover art for a file.

Response: Image bytes (image/jpeg or image/png). Returns 404 if no embedded cover is found.

Playlist M3U¶

POST /api/playlist/m3u¶

Write an M3U file for a playlist after per-track downloads are complete.

Request body:

{
  "playlist_url": "https://open.spotify.com/playlist/…",
  "tracks": [
    {
      "filename": "My Playlist/Artist - Title.mp3",
      "title": "Title",
      "artist": "Artist",
      "duration": 210
    }
  ]
}

Response: { "path": "/downloads/…/playlist.m3u", "count": 12 }

Playlist Monitor¶

GET /api/monitor/playlists¶

List all monitored playlists.

Response: Array of playlist monitor objects.

POST /api/monitor/playlists¶

Add a playlist to the monitor. Triggers an immediate initial download.

Request body:

{
  "url": "https://open.spotify.com/playlist/…",
  "interval_minutes": 60
}

Response: Playlist monitor object.

PATCH /api/monitor/playlists/{playlist_id}¶

Update a monitored playlist (interval, enabled state).

Request body: Partial object with interval_minutes and/or enabled.

Response: Updated playlist monitor object.

DELETE /api/monitor/playlists/{playlist_id}¶

Stop monitoring a playlist.

Response: { "deleted": true } or { "deleted": false }

POST /api/monitor/playlists/{playlist_id}/check¶

Trigger an immediate check for a specific playlist outside the normal schedule.

Response: { "downloaded": 3 }

WebSocket¶

WS /api/ws¶

Real-time download progress events.

Events received from the server:

{
  "song": { /* song metadata object */ },
  "progress": 42.5,
  "message": "Downloading…",
  "status": "downloading",
  "filename": null
}

status is one of: queued · downloading · done · error.

filename is set (non-null) on the final done event.