{"openapi":"3.1.0","info":{"title":"Free Music API","version":"1.0.0","description":"Real music, cleared for code. A free API serving production-quality, royalty-free music for developers to integrate into apps, games, videos, and AI projects.","contact":{"name":"Free Music API","url":"https://freemusicapi.com"},"license":{"name":"Royalty-Free","url":"https://freemusicapi.com/license"}},"servers":[{"url":"https://api.freemusicapi.com","description":"Production"}],"security":[{"BearerAuth":[]}],"paths":{"/":{"get":{"operationId":"healthCheck","summary":"Health check","description":"Returns API name, version, and status. No authentication required.","tags":["Health"],"security":[],"responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"{music}"},"tagline":{"type":"string","example":"Real music, cleared for code."},"version":{"type":"string","example":"v1"},"docs":{"type":"string","format":"uri","example":"https://freemusicapi.com/docs"}}}}}}}}},"/v1/tracks":{"get":{"operationId":"listTracks","summary":"Search and browse tracks","description":"Returns a paginated list of tracks with full metadata. Supports text search, genre/mood/tag filtering, BPM/energy/duration ranges, and sorting by popularity or release date.","tags":["Tracks"],"parameters":[{"name":"q","in":"query","description":"Full-text search across title and genre","schema":{"type":"string"}},{"name":"genre","in":"query","description":"Filter by genre (case-insensitive)","schema":{"type":"string"}},{"name":"mood","in":"query","description":"Filter by mood","schema":{"type":"string"}},{"name":"bpm_min","in":"query","description":"Minimum BPM","schema":{"type":"integer"}},{"name":"bpm_max","in":"query","description":"Maximum BPM","schema":{"type":"integer"}},{"name":"energy_min","in":"query","description":"Minimum energy (1-10)","schema":{"type":"integer","minimum":1,"maximum":10}},{"name":"energy_max","in":"query","description":"Maximum energy (1-10)","schema":{"type":"integer","minimum":1,"maximum":10}},{"name":"key","in":"query","description":"Musical key (e.g. \"C Major\", \"A Minor\")","schema":{"type":"string"}},{"name":"label","in":"query","description":"Filter by label slug","schema":{"type":"string"}},{"name":"duration_min","in":"query","description":"Minimum duration in seconds","schema":{"type":"integer"}},{"name":"duration_max","in":"query","description":"Maximum duration in seconds","schema":{"type":"integer"}},{"name":"tags","in":"query","description":"Comma-separated tags (all must match)","schema":{"type":"string"}},{"name":"instruments","in":"query","description":"Comma-separated instruments (all must match)","schema":{"type":"string"}},{"name":"vocal","in":"query","description":"Filter by vocal presence","schema":{"type":"boolean"}},{"name":"vocal_gender","in":"query","description":"Vocal gender filter","schema":{"type":"string"}},{"name":"valence","in":"query","description":"Emotional valence filter","schema":{"type":"string"}},{"name":"version","in":"query","description":"Track version filter","schema":{"type":"string"}},{"name":"explicit","in":"query","description":"If false, excludes explicit tracks","schema":{"type":"boolean"}},{"name":"sort","in":"query","description":"Sort order","schema":{"type":"string","enum":["newest","popular"],"default":"newest"}},{"name":"limit","in":"query","description":"Results per page (1-50)","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","description":"Pagination offset","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Paginated track list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TrackListItem"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/tracks/{trackId}":{"get":{"operationId":"getTrack","summary":"Get a single track","description":"Returns full metadata for a track including stream URL, waveform data, and detailed credits.","tags":["Tracks"],"parameters":[{"name":"trackId","in":"path","required":true,"description":"Track UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Track detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TrackDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TierRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tracks/{trackId}/stream":{"post":{"operationId":"getStreamUrl","summary":"Get a streaming URL","description":"Returns a time-limited URL for streaming the track as MP3. Counts as a play event. Demo-tier keys receive a 30-second preview.","tags":["Streaming"],"parameters":[{"name":"trackId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"app_identifier":{"type":"string","description":"Your app name (for analytics)"}}}}}},"responses":{"200":{"description":"Stream URL generated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"stream_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"format":{"type":"string","example":"mp3"},"preview":{"type":"boolean"},"duration_limit":{"type":["integer","null"],"description":"Seconds (null = full track)"},"attribution":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TierRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Monthly play limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracks/{trackId}/download":{"post":{"operationId":"getDownloadUrl","summary":"Get a download URL","description":"Returns a time-limited URL for downloading the track. Requires a registered API key (demo keys cannot download). Supports MP3 and WAV formats.","tags":["Downloads"],"parameters":[{"name":"trackId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["mp3","wav"],"default":"mp3"},"app_identifier":{"type":"string"}}}}}},"responses":{"200":{"description":"Download URL generated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"download_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"format":{"type":"string"},"attribution":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TierRequired"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tracks/{trackId}/similar":{"get":{"operationId":"getSimilarTracks","summary":"Find similar tracks","description":"Returns tracks similar to the given track, scored by genre match, mood overlap, BPM proximity, and energy proximity. Useful for \"More like this\" features and auto-play queues.","tags":["Tracks"],"parameters":[{"name":"trackId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":6},"description":"Number of similar tracks to return (1-20)"}],"responses":{"200":{"description":"List of similar tracks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TrackListItem"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tracks/{trackId}/my-stats":{"get":{"operationId":"getMyTrackStats","summary":"Get your usage stats for a track","description":"Returns the number of plays, downloads, and total API calls you have made for a specific track. Useful for per-user analytics dashboards.","tags":["Analytics"],"parameters":[{"name":"trackId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Your stats for this track","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"track_id":{"type":"string","format":"uuid"},"plays":{"type":"integer"},"downloads":{"type":"integer"},"api_calls":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/plays":{"post":{"operationId":"reportPlay","summary":"Report a play event","description":"Report that a track was played in your app. Used for analytics and play counts.","tags":["Analytics"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["track_id"],"properties":{"track_id":{"type":"string","format":"uuid"},"duration_played_seconds":{"type":"number","description":"How many seconds the user listened"},"completed":{"type":"boolean","default":false,"description":"Whether the track played to completion"},"app_identifier":{"type":"string"}}}}}},"responses":{"201":{"description":"Play recorded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Missing track_id or invalid body"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/genres":{"get":{"operationId":"listGenres","summary":"List all genres","description":"Returns all genres with the number of tracks in each, sorted by count.","tags":["Filters"],"responses":{"200":{"description":"Genre list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FilterItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/moods":{"get":{"operationId":"listMoods","summary":"List all moods","description":"Returns all moods with track counts.","tags":["Filters"],"responses":{"200":{"description":"Mood list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FilterItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/tags":{"get":{"operationId":"listTags","summary":"List all tags","description":"Returns all tags with track counts.","tags":["Filters"],"responses":{"200":{"description":"Tag list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FilterItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/instruments":{"get":{"operationId":"listInstruments","summary":"List all instruments","description":"Returns all instruments with track counts.","tags":["Filters"],"responses":{"200":{"description":"Instrument list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FilterItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/keys":{"get":{"operationId":"listMusicalKeys","summary":"List all musical keys","description":"Returns all musical keys with track counts.","tags":["Filters"],"responses":{"200":{"description":"Musical key list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FilterItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/labels":{"get":{"operationId":"listLabels","summary":"List all labels","description":"Returns all music labels with track counts and genre info.","tags":["Labels"],"responses":{"200":{"description":"Label list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Label"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/playlists":{"get":{"operationId":"listPlaylists","summary":"List curated playlists","description":"Returns all curated playlists, sorted by category.","tags":["Playlists"],"responses":{"200":{"description":"Playlist list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlaylistSummary"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/playlists/{playlistId}":{"get":{"operationId":"getPlaylist","summary":"Get playlist with tracks","description":"Returns a playlist with its full track listing. Accepts UUID or slug.","tags":["Playlists"],"parameters":[{"name":"playlistId","in":"path","required":true,"description":"Playlist UUID or slug","schema":{"type":"string"}}],"responses":{"200":{"description":"Playlist detail with tracks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PlaylistDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/me/usage":{"get":{"operationId":"getUsage","summary":"Get your API usage","description":"Returns current billing period usage for the authenticated API key, including request counts, play counts, and top tracks.","tags":["Usage"],"responses":{"200":{"description":"Usage data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tier":{"type":"string","enum":["free","pro","enterprise"]},"billing_period":{"type":"object","properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"}}},"usage":{"type":"object","properties":{"requests_this_hour":{"type":"integer"},"requests_limit_per_hour":{"type":"integer"},"plays_this_month":{"type":"integer"},"plays_limit_per_month":{"type":"integer"},"top_tracks":{"type":"array","items":{"type":"object","properties":{"track_id":{"type":"string"},"title":{"type":"string"},"plays":{"type":"integer"}}}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/tracks/{trackId}/beats":{"get":{"operationId":"getTrackBeats","summary":"Get beat data for a track","description":"Returns beat positions, bar boundaries, section labels (intro, verse, chorus, build, drop, breakdown, outro), BPM, time signature, and energy curve. Designed for AI video editors (Remotion), visualizers, and music-reactive apps. Pro tracks require a pro API key.","tags":["Beats"],"parameters":[{"name":"trackId","in":"path","required":true,"description":"Track UUID","schema":{"type":"string","format":"uuid"}},{"name":"fps","in":"query","description":"Frame rate — when set, each beat includes a `frame` number (e.g. fps=30 for Remotion)","schema":{"type":"integer","example":30}}],"responses":{"200":{"description":"Beat data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BeatData"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TierRequired"},"404":{"description":"Track not found or beat data not yet generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stream":{"get":{"operationId":"streamAudio","summary":"Stream audio file","description":"Streams the raw audio file. Authenticated via a signed token in the query string (not an API key). Tokens are obtained from the POST /v1/tracks/{id}/stream endpoint.","tags":["Streaming"],"security":[],"parameters":[{"name":"token","in":"query","required":true,"description":"Signed stream token (base64-encoded)","schema":{"type":"string"}},{"name":"dl","in":"query","description":"Set to \"1\" to download as attachment","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Audio stream","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Missing or malformed token"},"401":{"description":"Token expired"},"404":{"description":"Audio file not found"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Pass your API key as a Bearer token: `Authorization: Bearer fma_live_...`"}},"schemas":{"Artist":{"type":"object","properties":{"name":{"type":"string","example":"VYEN"},"role":{"type":"string","enum":["primary","featured","remixer"],"example":"primary"},"profile_url":{"type":"string","format":"uri"}}},"Credits":{"type":"object","properties":{"produced_by":{"type":"string"},"written_by":{"type":"string"},"lyrics_by":{"type":"string"},"performed_by":{"type":"string"},"mixed_by":{"type":"string"},"mastered_by":{"type":"string"}}},"TrackListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","example":"Midnight Drive"},"artists":{"type":"array","items":{"$ref":"#/components/schemas/Artist"}},"label":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"genre":{"type":"string","example":"Lo-Fi"},"subgenre":{"type":"string"},"moods":{"type":"array","items":{"type":"string"},"example":["Chill","Dreamy"]},"tags":{"type":"array","items":{"type":"string"}},"bpm":{"type":"integer","example":85},"key":{"type":"string","example":"C Minor"},"energy":{"type":"integer","minimum":1,"maximum":10},"valence":{"type":"string"},"duration_seconds":{"type":"number","example":195.5},"version":{"type":"string"},"has_vocals":{"type":"boolean"},"vocal_presence":{"type":"string"},"instruments":{"type":"array","items":{"type":"string"}},"explicit":{"type":"boolean"},"release_date":{"type":"string","format":"date"},"credits":{"$ref":"#/components/schemas/Credits"},"attribution":{"type":"string","description":"Required attribution text for using this track"},"artwork_url":{"type":"string","format":"uri"},"tier":{"type":"string","enum":["free","pro"]},"play_count":{"type":"integer"},"download_count":{"type":"integer"},"formats_available":{"type":"array","items":{"type":"string"},"example":["mp3","wav"]},"external_ids":{"type":"object","properties":{"isrc":{"type":"string"},"spotify_uri":{"type":"string"}}}}},"TrackDetail":{"description":"Full track detail including stream URL and waveform data","allOf":[{"$ref":"#/components/schemas/TrackListItem"},{"type":"object","properties":{"stream_url":{"type":"string","format":"uri","description":"Pre-signed streaming URL"},"stream_url_expires_at":{"type":"string","format":"date-time"},"waveform_data":{"type":"object","description":"Audio waveform visualization data"},"has_beats":{"type":"boolean","description":"Whether beat/section data is available for this track"},"beat_data_url":{"type":["string","null"],"description":"URL to fetch full beat data (null if not available)","example":"/v1/tracks/{id}/beats"}}}]},"BeatData":{"type":"object","description":"Beat positions, bar boundaries, sections, and energy data for a track. Generated by neural-network analysis (madmom/essentia/librosa).","properties":{"bpm":{"type":"number","example":128,"description":"Beats per minute"},"time_signature":{"type":"string","example":"4/4","description":"Detected time signature (4/4 or 3/4)"},"duration":{"type":"number","example":215.4,"description":"Track duration in seconds"},"total_beats":{"type":"integer","example":460},"total_bars":{"type":"integer","example":115},"beats":{"type":"array","description":"Every beat position with bar/beat number and downbeat flag","items":{"type":"object","properties":{"time":{"type":"number","description":"Beat time in seconds"},"beat":{"type":"integer","description":"Beat number within bar (1-based)"},"bar":{"type":"integer","description":"Bar number (1-based)"},"downbeat":{"type":"boolean","description":"True if this is beat 1 of a bar"},"frame":{"type":"integer","description":"Frame number (only present when ?fps is set)"}}}},"bars":{"type":"array","description":"Bar boundaries","items":{"type":"object","properties":{"bar":{"type":"integer"},"start":{"type":"number"},"end":{"type":"number"}}}},"sections":{"type":"array","description":"Structural sections (intro, verse, chorus, build, drop, breakdown, outro)","items":{"type":"object","properties":{"label":{"type":"string","enum":["intro","verse","chorus","build","drop","breakdown","outro"]},"start":{"type":"number","description":"Section start in seconds"},"end":{"type":"number","description":"Section end in seconds"},"energy":{"type":"number","description":"Normalized energy level (0-1)"}}}}}},"FilterItem":{"type":"object","properties":{"name":{"type":"string","example":"Lo-Fi"},"track_count":{"type":"integer","example":42}}},"Label":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"tier":{"type":"string","enum":["free","pro"]},"track_count":{"type":"integer"},"genres":{"type":"array","items":{"type":"string"}},"website_url":{"type":"string","format":"uri"}}},"PlaylistSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"artwork_url":{"type":"string","format":"uri"},"category":{"type":"string"},"track_count":{"type":"integer"}}},"PlaylistDetail":{"allOf":[{"$ref":"#/components/schemas/PlaylistSummary"},{"type":"object","properties":{"tracks":{"type":"array","items":{"$ref":"#/components/schemas/TrackListItem"}}}}]},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer","description":"Total matching results"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"unauthorized"},"message":{"type":"string","example":"Invalid or missing API key."}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per hour"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining this hour"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix timestamp when window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TierRequired":{"description":"Higher tier required to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"tags":[{"name":"Health","description":"API health and version info"},{"name":"Tracks","description":"Browse, search, and get track metadata"},{"name":"Streaming","description":"Get streaming URLs and stream audio"},{"name":"Downloads","description":"Download tracks in MP3 or WAV"},{"name":"Beats","description":"Beat positions, sections, and structural analysis for video sync and visualizers"},{"name":"Filters","description":"Discover available genres, moods, tags, instruments, and keys"},{"name":"Labels","description":"Browse music labels"},{"name":"Playlists","description":"Curated playlists and collections"},{"name":"Analytics","description":"Report play events and usage"},{"name":"Usage","description":"Check your API key usage and limits"}]}