Overview

← Back to Home

Overview

Introduction

The Juice WRLD API provides programmatic access to the most comprehensive Juice WRLD music database — over 2,700 catalogued songs, unreleased tracks, file browsing, and rich metadata. No API key required for public read endpoints.

Base URL: https://juicewrldapi.com/juicewrld

Open live API docs

Index & Health Check

GET /

API index. Absolute URIs to the major collections, useful as a quick sanity check or a starting point for API explorers.

{
  "artists": "https://…/juicewrld/artists/",
  "albums": "https://…/juicewrld/albums/",
  "songs": "https://…/juicewrld/songs/",
  "versions": "https://…/juicewrld/versions/",
  "eras": "https://…/juicewrld/eras/",
  "stats": "https://…/juicewrld/stats/",
  "categories": "https://…/juicewrld/categories/"
}

GET /health/

Liveness check. { "status": "ok" }, nothing else.

Endpoint Overview

Method	Path	Description
GET	/	API index with links to the major collections
GET	/health/	Health check
GET	/artists/	List artists
GET	/artists/{id}/	Single artist by ID
GET	/albums/	List albums
GET	/albums/{id}/	Single album by ID
GET	/songs/	List, filter, search and paginate songs
GET	/songs/{id}/	Single song by internal ID
GET	/categories/	Available category values with labels
GET	/eras/	All eras — paginated (34 total, 20 per page)
GET	/eras/{id}/	Single era by ID
GET	/stats/	Database-wide counts by category and era
GET	/radio/random/	Random playable song with full metadata
GET	/radio/live/	Live 999 FM station state — now playing, votes, listeners
GET	/radio/library/	Track list backing the live station, grouped by era
GET	/radio/stream.mp3	Live radio MP3 stream (WebSocket /ws/radio/ carries the same audio + metadata)
GET	/files/channels/	List active comp channels (public)
GET	/files/browse/	Browse the file system
GET	/files/list-all/	Flat listing of every file in a comp channel
GET	/files/info/	Metadata for a single file
GET	/files/cover-art/	Cover art image for an audio file
GET	/files/thumbnail/	Thumbnail image for a file
GET	/files/download/	Stream/download audio — supports Range requests
GET	/files/download-compressed/	Transcoded MP3 stream at a chosen bitrate
GET	/files/image-thumbnail/	Resized JPEG thumbnail for an image file
POST	/files/zip-selection/	Immediate ZIP stream of selected paths (not a background job)
GET	/zip-jobs/{filename}	Download the finished ZIP from a background job
GET	/versions/	All song-version rows (bulk mode via ?all=true)
GET	/versions/{song_id}/	Version rows for one song, if linked
GET	/versions/{song_id}/{id}/	A single version row by its own ID
POST	/versions/	Link a song into a version group (editor+)
PATCH	/versions/{song_id}/	Update a song's version label/title/group (editor+)
POST	/playlists/share/	Create a public shared playlist link
GET	/playlists/shared/{share_id}/	Fetch a shared playlist by ID
POST	/plays/	Record a play event (no auth required)
GET	/plays/stats/	Site-wide play stats: top songs, albums, eras, recent plays
GET	/heardle/leaderboard/	Heardle leaderboards: streak, today, versus
GET	/heardle/clip/	Signed Heardle audio clip (HMAC round token, not a user token)
GET	/feeds/tracker.rss	RSS feed of approved song edits
GET	/feeds/comp.rss	RSS feed of comp file commits
GET	/feeds/tracker.json	JSON feed of approved song edits
GET	/feeds/comp.json	JSON feed of comp file commits
GET	/cover/{name}	Static cover art image by filename
GET	/media/{path}	Static media file (news covers, attachments, etc.)
GET	/accounts/account/me/	Current user info (public-facing), incl. per-song preferences + playlist folders
PATCH	/accounts/account/me/	Update user_preferences (custom titles, covers, default version, playcounts) and/or playlist_folders
GET	/accounts/me/	Current user with role — editor/admin dashboards
POST	/feedback/	Submit API feedback (no auth)
GET	/feedback/	List submitted feedback (requires auth)
POST	/reports/	Report wrong info on a song (no auth)
GET	/reports/	List song reports (editor+)
PATCH	/reports/{id}/	Review a song report (editor+)
POST	/accounts/logout/	Invalidate the current token
GET	/accounts/application/	Fetch the logged-in user's editor or contributor application
POST	/accounts/application/	Apply to become an editor or contributor
GET	/accounts/editor/proposals/	List your own edit proposals
POST	/accounts/editor/proposals/	Submit an edit proposal (editor+)
PATCH	/accounts/editor/proposals/{id}/	Edit a pending proposal
DELETE	/accounts/editor/proposals/{id}/	Withdraw a proposal
GET	/accounts/editor/leaderboard/	Editor approved-count leaderboard with badges
GET	/accounts/contributor/proposals/	List your own comp-file proposals (contributor+)
POST	/accounts/contributor/proposals/	Submit a comp-file proposal — multipart (contributor+)
PATCH	/accounts/contributor/proposals/{id}/	Edit a pending comp-file proposal — multipart
DELETE	/accounts/contributor/proposals/{id}/	Withdraw a comp-file proposal
GET	/accounts/admin/comp-proposals/	List all comp-file proposals (admin)
POST	/accounts/admin/comp-proposals/{id}/review/	Approve/reject a comp-file proposal (admin)
POST	/accounts/admin/comp-proposals/{id}/reverse/	Reverse an approved comp-file proposal (admin)
GET	/accounts/admin/comp-proposals/{id}/staging/	Download the staged file for review (admin)
GET	/accounts/admin/comp-files/{filepath}/history/	Revision history for a compilation file (admin)
GET	/accounts/admin/channels/	List all comp channels, incl. inactive (admin)
POST	/accounts/admin/channels/	Create a comp channel (admin)
PATCH	/accounts/admin/channels/{id}/	Rename/describe/reactivate a comp channel (admin)
DELETE	/accounts/admin/channels/{id}/	Deactivate a comp channel (admin)
GET	/accounts/admin/channels/{id}/members/	List a comp channel's per-user role memberships (admin)
POST	/accounts/admin/channels/{id}/members/	Set a user's editor/contributor/manager flags for a comp channel (admin)
GET	/news/	Paginated news feed. Filter: ?channel=, sort: ?ordering=
GET	/news/{id}/	Single news post
POST	/news/	Create a news post (is_news or admin)
PATCH	/news/{id}/	Edit a news post — own post only unless admin (is_news or admin)
DELETE	/news/{id}/	Delete a news post — own post only unless admin (is_news or admin)
GET	/news/channels/	List news channels
POST	/news/channels/	Create a news channel (admin)
PATCH	/news/channels/{slug}/	Rename/describe a news channel (admin)
DELETE	/news/channels/{slug}/	Delete a news channel — only if empty (admin)
POST	/news/uploads/	Upload a post attachment — multipart, ≤25MB (is_news or admin)
GET	/news/attachments/{id}/stream/	Stream/download a hosted attachment
GET	/library/favorites/	List personal favorites (any logged-in user)
POST	/library/favorites/	Add a favorite
DELETE	/library/favorites/{song_id}/	Remove a favorite
GET	/library/playlists/	List personal playlists
POST	/library/playlists/	Create a personal playlist
GET	/library/playlists/{id}/	Get a personal playlist with tracks
PATCH	/library/playlists/{id}/	Update name, description, cover, visibility, track order
DELETE	/library/playlists/{id}/	Delete a personal playlist
POST	/library/playlists/{id}/items/	Add a track to a playlist
DELETE	/library/playlists/{id}/items/{song_id}/	Remove a track from a playlist
GET	/library/playlists/public/{id}/	Fetch a playlist marked public — no auth required

Songs Object — Full Shape

{
  "id": 1,
  "public_id": 123,
  "name": "Song Title",
  "original_key": "Original JSON Key",
  "category": "released|unreleased|unsurfaced|recording_session",
  "path": "Compilation/folder/song.mp3",
  "era": {
    "id": 1,
    "name": "Era Name",
    "description": "Era Description",
    "time_frame": "Time Period",
    "play_count": 0
  },
  "track_titles": ["Title 1", "Title 2"],
  "credited_artists": "Artist Names",
  "producers": "Producer Names",
  "engineers": "Engineer Names",
  "recording_locations": "Studio Locations",
  "record_dates": "Recording Dates",
  "length": "3:59",
  "bitrate": "Bitrate Info",
  "additional_information": "Extra Info",
  "file_names": "File Name(s)",
  "instrumentals": "Instrumental beat name",
  "instrumental_names": "Instrumental track names",
  "preview_date": "Preview Date",
  "release_date": "Release Date",
  "dates": "Additional Dates",
  "session_titles": "Session Titles",
  "session_tracking": "Session Tracking",
  "notes": "Internal notes",
  "groupbuy_info": {
    "additional_info": "",
    "price": "",
    "start_date": "",
    "end_date": "",
    "blind": false,
    "finished": false,
    "surfaced_with_og": false
  },
  "lyrics": "Song Lyrics",
  "synced_lyrics": "Timestamped lyrics (karaoke-style)",
  "album": "Album Name",
  "snippets": [],
  "date_leaked": "Leak Date",
  "leak_type": "Leak Type",
  "image_url": "/assets/era-image.webp",
  "version_title": "Version label (only with ?versions=true on /songs/)",
  "versions": []
}

image_url is relative — prepend https://juicewrldapi.com before use.

version_title / versions are omitted unless the request includes ?versions=true — see the /songs/ params in Songs & Search.

synced_lyrics — no separate param, no opt-in flag

Unlike version_title/versions above, synced_lyrics is a plain field on the song object like lyrics — it comes back on every request that returns a song (list, detail, radio, live), with no query param needed to request it. It's null when the song has no synced lyrics.

Format is LRC — one timestamp per line, [mm:ss.xx] (also accepts [mm:ss:xx]), text after the bracket:

[00:12.50]First line
[00:15.80]Second line
[00:19.10](ad-lib) Next line

A line can carry more than one timestamp (repeats the same text at each). Parenthesized runs like (ad-lib) are a convention this app renders dimmer, not part of the LRC spec itself.