Skip to content

YTMDL REST API Reference ​

All API endpoints are served under /api/v1. Successful responses return JSON payloads wrapped in {"data": ...}. Error responses return JSON error envelopes formatted as {"error": {"code": "...", "message": "...", "request_id": "..."}}.

State-changing requests (POST, PUT, PATCH, DELETE) require a valid CSRF token passed via the X-CSRF-Token header and the ytmdl_csrf cookie.

A signed-out client gets its ytmdl_csrf cookie only from GET /api/v1/auth/status; fetch it before the first state-changing request (sign-in, setup, device start). No other endpoint issues a token to a signed-out client, so parallel first requests cannot hand a client competing tokens. Sign-in (/auth/login, /auth/setup, an authorized /auth/device/poll) sets the cookie to a token bound to the new session, and any later response for a session that has no cookie sets that same token. An existing cookie is otherwise never replaced.


Authentication & Sessions ​

MethodEndpointAccessPurpose
GET/api/v1/auth/statusPublicCheck if the system has completed first-run setup.
POST/api/v1/auth/setupPublicCreate the initial administrator account on first run.
POST/api/v1/auth/loginPublicAuthenticate user credentials and issue session cookie.
GET/api/v1/auth/meUserGet current authenticated user details and role.
POST/api/v1/auth/logoutUserTerminate current session and invalidate cookie.
POST/api/v1/auth/devicePublicRequest a short-lived device sign-in code.
POST/api/v1/auth/device/pollPublicPoll the opaque secret; exchange an approved code for a session cookie.
POST/api/v1/auth/device/previewUserInspect the requesting device without approving it.
POST/api/v1/auth/device/confirmUserExplicitly approve a device using the short code.

Device routes also require CSRF. See device-code sign-in for expiry, polling intervals, confirmation and revocation.

Native Apple clients reuse cookie authentication and CSRF. Device pairing adds POST /api/v1/auth/device (start), POST /api/v1/auth/device/poll (exchange), and authenticated POST /api/v1/auth/device/preview and POST /api/v1/auth/device/confirm. Every POST requires the normal CSRF cookie and header, including pre-auth start/poll. Codes expire after five minutes; poll no faster than the returned interval and back off on slow_down. See the Apple client security design for the one-time exchange, limits and account permissions.


User & Profile Management ​

MethodEndpointAccessPurpose
GET/api/v1/profileUserRetrieve current user profile.
PATCH/api/v1/profileUserUpdate username or display preferences.
POST/api/v1/profile/passwordUserChange current user password.
GET/api/v1/profile/sessionsUserList all active sessions for current user.
DELETE/api/v1/profile/sessions/{id}UserRevoke a specific active session.
POST/api/v1/profile/sessions/revoke-othersUserRevoke all sessions except the current one.
GET/api/v1/usersAdminList all registered user accounts.
POST/api/v1/usersAdminCreate a new user account.
GET/api/v1/users/{id}AdminGet specific user account details.
PATCH/api/v1/users/{id}AdminUpdate user details or role.
POST/api/v1/users/{id}/reset-passwordAdminReset a user's password.
DELETE/api/v1/users/{id}AdminDelete a user account (last admin protected).

Discovery & Downloads ​

MethodEndpointAccessPurpose
GET/api/v1/providersUserList configured metadata and media providers and health.
GET/api/v1/search/artists?q=UserSearch artists across configured providers.
GET/api/v1/resolve?url=UserResolve external URL (YouTube/Spotify/Deezer) to entity.
GET/api/v1/artists/{id}UserRetrieve artist metadata.
GET/api/v1/artists/{id}/discographyUserFetch artist discography, filterable by release type.
GET/api/v1/releases/{id}UserRetrieve release details and track list.
POST/api/v1/downloads/artistUserEnqueue download job for an artist discography.
POST/api/v1/downloads/releaseUserEnqueue download job for a release.
POST/api/v1/downloads/trackUserEnqueue download job for a single track.

Subscriptions ​

MethodEndpointAccessPurpose
GET/api/v1/subscriptionsUserList all artist subscriptions and latest sync status.
POST/api/v1/subscriptionsUserSubscribe to an artist.
GET/api/v1/subscriptions/{id}UserGet subscription details and sync report.
PATCH/api/v1/subscriptions/{id}UserUpdate subscription filters, auto-download, or priority.
DELETE/api/v1/subscriptions/{id}UserRemove artist subscription.
POST/api/v1/subscriptions/{id}/syncUserTrigger immediate discography check (returns 202 Accepted).
GET/api/v1/subscriptions/exportUserExport subscriptions as JSON.
POST/api/v1/subscriptions/import/previewUserPreview subscription import file.
POST/api/v1/subscriptions/import/applyUserApply subscription import.

Queue & Job Execution ​

MethodEndpointAccessPurpose
GET/api/v1/jobsUserList jobs with status, priority, and progress. Supports view=all|active|queued|paused|done|failed together with status, type, priority, limit and offset. Group filters apply before pagination; meta.total counts matching jobs. Paused overlaps queued/active; done includes completed/cancelled. Unknown groups return INVALID_REQUEST.
GET/api/v1/jobs/summaryUserGlobal queue counters (active, queued, paused, done, failed) used by the Downloads tab badges.
GET/api/v1/jobs/{id}UserInspect job items, attempts, and error details.
PATCH/api/v1/jobs/{id}UserUpdate job priority and/or paused state ({"priority": "...", "paused": true}).
POST/api/v1/jobs/{id}/pauseUserPause a specific job.
POST/api/v1/jobs/{id}/resumeUserResume a paused job.
POST/api/v1/jobs/{id}/retry-failedUserRetry all failed items in a job.
POST/api/v1/jobs/{job_id}/items/{item_id}/retryUserRetry a specific failed job item.
DELETE/api/v1/jobs/{id}UserCancel an active or pending job.
DELETE/api/v1/jobs/historyAdminClear completed and cancelled job history.
GET/api/v1/eventsUserServer-Sent Events (SSE) stream for real-time progress.

Playlists & Favorites ​

Playlists and favorites are strictly scoped to the authenticated user.

MethodEndpointAccessPurpose
GET/api/v1/playlistsUserList the current user's playlists.
GET/api/v1/playlists/{id}UserGet one playlist with its ordered tracks.
POST/api/v1/playlistsUserCreate a playlist.
PATCH/api/v1/playlists/{id}UserRename a playlist.
DELETE/api/v1/playlists/{id}UserDelete a playlist.
POST/api/v1/playlists/{id}/tracksUserAdd a track to a playlist.
DELETE/api/v1/playlists/{id}/tracks/{track_id}UserRemove a track (positions re-compact to 1..N).
PUT/api/v1/playlists/{id}/tracks/reorderUserReorder playlist tracks.
GET/api/v1/favoritesUserList favorited tracks.
GET/api/v1/favorites/idsUserList favorited track IDs only.
GET/api/v1/favorites/{track_id}UserCheck whether a track is favorited.
PUT/api/v1/favorites/{track_id}UserMark a track as favorite.
DELETE/api/v1/favorites/{track_id}UserRemove a favorite.

Library & Streaming ​

MethodEndpointAccessPurpose
GET/api/v1/library/statsUserLibrary storage, codec, and lyrics statistics.
GET/api/v1/library/searchUserSearch local catalog across artists, releases, and tracks.
GET/api/v1/library/artistsUserPaginated local artists list.
GET/api/v1/library/artists/{id}UserLocal artist detail with releases and size.
GET/api/v1/library/releasesUserPaginated local releases list.
GET/api/v1/library/releases/{id}UserLocal release detail with track listing and multi-disc grouping.
GET/api/v1/library/tracksUserPaginated local tracks list.
GET/api/v1/library/tracks/{id}UserTechnical audio inspector (bitrate, sample rate, channels, codec).
GET/HEAD/api/v1/library/tracks/{id}/streamUserStream track audio (supports HTTP 206 Partial Content range requests).
GET/HEAD/api/v1/library/files/{id}/streamUserStream audio file by file ID.
GET/api/v1/library/tracks/{id}/lyricsUserRetrieve synchronized or plain lyrics for a track.
POST/api/v1/library/tracks/{id}/lyrics/refreshUserRe-query lyrics provider chain (LRCLIB -> YTM -> Genius).
DELETE/api/v1/library/tracks/{id}/lyricsUserDelete lyrics and remove sidecar file.
GET/api/v1/library/lyrics/backfill/previewUserRead-only scan of missing vs. eligible lyrics tracks.
GET/api/v1/library/lyrics/backfillUserGet status of running lyrics backfill job.
POST/api/v1/library/lyrics/backfillUserStart background lyrics backfill for missing tracks.
POST/api/v1/library/tracks/{id}/redownloadUserRe-enqueue download for a missing track file.
POST/api/v1/library/tracks/{id}/retagUserLosslessly rewrite Vorbis comment tags from database.
GET/api/v1/library/compatibilityUserMedia server compatibility report.
POST/api/v1/library/reorganizeUserReorganize files into canonical directory layout.
GET/api/v1/library/scanUserRead-only reconciliation scan: physical files vs. database (files table), including legacy/orphan issues.
POST/api/v1/library/scanUserStart a background reconciliation scan.
DELETE/api/v1/library/scan/issues/{id}AdminResolve a specific orphan/legacy scan issue (may quarantine the unreferenced file).

Library Maintenance & Audits ​

Audit reads are available to any authenticated user; starting audits, cancelling them, and every repair or delete action require an Administrator.

MethodEndpointAccessPurpose
GET/api/v1/library/auditsUserList historical library audit runs.
GET/api/v1/library/audits/currentUserGet currently running audit status.
GET/api/v1/library/audits/{id}UserGet audit summary and finding counts.
GET/api/v1/library/audits/{id}/findingsUserPaginated list of audit findings (missing files, orphan files, etc.).
GET/api/v1/library/naming-migrationUserState of the automatic move to the current file naming scheme: counts, and every file left in place with the reason.
GET/api/v1/library/identity-migrationUserState of the background carry-over of stored track identity keys to the current identity scheme: counts, and every track held at its older key with the reason (collision: another track already carries the new key; not_derivable: the stored key no longer follows from the stored title and artists). A held track is still found as before and is looked at again on every start.
POST/api/v1/library/auditsAdminStart new Quick or Deep library audit.
POST/api/v1/library/audits/{id}/cancelAdminCancel in-progress library audit.
POST/api/v1/library/repairs/previewAdminPreview non-destructive audit repair actions.
POST/api/v1/library/repairs/applyAdminApply confirmed repair actions (quarantine orphans, reconcile paths).
POST/api/v1/library/releases/{id}/artwork/previewAdminPreview artwork refresh for a release.
POST/api/v1/library/releases/{id}/artwork/refreshAdminRefresh cover artwork for a release.
POST/api/v1/library/artwork/previewAdminPreview bulk artwork repair for missing covers.
POST/api/v1/library/artwork/refreshAdminExecute bulk artwork repair.
DELETE/api/v1/library/releases/{id}AdminDelete release and tracks (preserves untracked files).
DELETE/api/v1/library/tracks/{id}AdminDelete single track from library and database.

System & Settings ​

MethodEndpointAccessPurpose
GET/api/v1/healthPublicSystem health check (application, database, ffmpeg, yt-dlp).
GET/api/v1/settingsUserGet effective server settings and provider statuses.
PUT/api/v1/settingsAdminUpdate dynamic server settings (workers, lyrics toggles, match score).
GET/api/v1/storage/statusAdminInspect storage volume capacity, mount health, and identity guard.
POST/api/v1/storage/probeAdminRe-probe storage accessibility and guard token.
POST/api/v1/storage/queue/pauseAdminManually pause queue processing for storage maintenance.
POST/api/v1/storage/queue/resumeAdminResume queue processing after storage maintenance.
GET/api/v1/system/updateAdminGet current or cached GitHub release update status.
POST/api/v1/system/update/checkAdminForce a fresh update check against the official release repository (CSRF required).

Managed Media Sessions (Admin Only) ​

Manage authenticated YouTube sessions used for media acquisition. The same handlers are mounted under both /api/v1/media-sessions and /api/v1/admin/media-sessions. See Providers → Managed Media Sessions.

MethodEndpointAccessPurpose
GET/api/v1/media-sessionsAdminList managed sessions and their health status.
GET/api/v1/media-sessions/{id}AdminGet one session's detail and cooldown state.
POST/api/v1/media-sessionsAdminCreate a named session entry.
POST/api/v1/media-sessions/{id}/cookiesAdminUpload / replace the session's Netscape cookies.txt (validated before the previous file is overwritten).
POST/api/v1/media-sessions/{id}/probeAdminRun an on-demand health probe for the session.
PATCH/api/v1/media-sessions/{id}AdminRename or reconfigure a session.
DELETE/api/v1/media-sessions/{id}AdminRemove a session.

Update Status Schema ​

Endpoints under /api/v1/system/update require Administrator privileges. POST /api/v1/system/update/check requires a valid X-CSRF-Token header.

Response Structure ({"data": ...}):

json
{
  "current_version": "0.25.2",
  "latest_version": "0.26.0",
  "state": "update_available",
  "release_name": "YTMDL v0.26.0",
  "published_at": "2026-09-08T12:00:00Z",
  "release_url": "https://github.com/Der-Felix/ytmdl/releases/tag/v0.26.0",
  "release_notes": "...",
  "checked_at": "2026-09-08T14:30:00Z",
  "cached": true
}

Possible state Values:

  • up_to_date: The installed version is identical to or newer than the latest stable release.
  • update_available: A newer stable release is available on GitHub.
  • no_public_release: The repository has no published releases yet (HTTP 404 handled gracefully).
  • disabled: Update checks are disabled (MUSICDL_UPDATE_CHECKS_ENABLED=false).
  • unavailable: GitHub is unreachable, timed out, or rate-limited (403/429).
  • invalid_release: The remote release tag cannot be parsed as valid SemVer, or is a draft/prerelease.
  • development_version: The installed version is a local dev build ("dev").

Released under the Apache 2.0 License.