Magnatune catalog API

MarkdownJSONOpenAPIllms.txt

JSON for Magnatune's music catalog (albums, artists, songs with free previews, genres, moods and uses, hand-picked playlists, SQL over everything), plus, for Magnatune members, the clean (no voice-over) songs, album downloads and their own library. Searching and the free versions need no key and no sign-in. Members sign in with OAuth 2.1 (no passwords: see Start here just below); AI assistants can instead connect https://magnatune.com/mcp/account.

Start here (AI agents and programs)

Pick the line that matches what you're doing:

You want to... Do this Sign-in
Find music (recommended for AI agents) Search the catalog text with your own regular expressions: GET https://magnatune.com/api/grep?re=calm\|serene\|meditat&re=cello\|piano (syntax: https://magnatune.com/api/regex), then GET https://magnatune.com/artists/albums/{sku}/about.md for the albums that fit None
Show previews, give links and credit lines; structured filters (length, vocals, moods and uses, energy, tempo) The GET endpoints below, e.g. GET https://magnatune.com/api/albums/{sku} or GET https://magnatune.com/api/tracks?q=calm+piano&vocals=instrumental&max_seconds=180 (keyword search) None
Act for a person who is a Magnatune member (clean songs, album zips, their favorites and playlists) Sign them in with OAuth 2.1 (next section) and send Authorization: Bearer <access_token>. Never ask a member for their password. OAuth
Get clean songs for a person who is not a member Send them to https://magnatune.com/member/signup ($10/month), or let the agent buy a membership itself with MPP ("Paying from an agent" below) MPP
Buy one album for a person Give them the album's buy_url ($8, paid to the musician on PayPal), then use its download key ("Buying an album for a person") Album key
You are an AI assistant with MCP Use the MCP server instead of this API: https://magnatune.com/mcp (no sign-in) or https://magnatune.com/mcp/account (members: your MCP client runs the OAuth flow itself) Optional

What needs what:

Feature No sign-in Member (OAuth Bearer, or HTTP Basic login)
Search, albums, artists, songs, genres, moods, playlists, SQL yes yes
Free song files (with a short spoken Magnatune voice every 30 s, CC BY-NC-SA, non-commercial) yes yes
Clean song files: GET /api/albums/{sku}/tracks/{n}/file?format=wav 402 (sign in, pay by MPP, or add the album's key=) yes
Album zips: GET https://magnatune.com/membership/download3?sku=SKU&format=flac no yes
The member's library: GET https://magnatune.com/membership/settings (favorites, playlists, recently played) no yes
The member's downloads: GET https://magnatune.com/api/mydownloads no yes

Members: sign in with OAuth 2.1 (step by step)

Standard OAuth 2.1 authorization code flow with PKCE (S256), dynamic client registration (RFC 7591), protected-resource metadata (RFC 9728). Scopes: member (everything a member can do) or download (only the clean files and album zips: ask for the narrowest you need). Resource: https://magnatune.com/api.

1. Discover (optional; the URLs are fixed):

GET https://magnatune.com/.well-known/oauth-protected-resource/api
-> {"resource":"https://magnatune.com/api","authorization_servers":["https://magnatune.com"],"scopes_supported":["member"],...}
GET https://magnatune.com/.well-known/oauth-authorization-server
-> {"authorization_endpoint":"https://magnatune.com/oauth/authorize","token_endpoint":"https://magnatune.com/oauth/token","registration_endpoint":"https://magnatune.com/oauth/register",...}

2. Register your client once (no account or approval needed). Redirect URIs must be https, or http to localhost / 127.0.0.1 (any port):

POST https://magnatune.com/oauth/register
Content-Type: application/json

{"client_name": "My Agent", "redirect_uris": ["http://127.0.0.1:8765/callback"], "token_endpoint_auth_method": "none"}

-> 201 {"client_id": "mt_...", "token_endpoint_auth_method": "none", ...}

3. Make a PKCE pair: code_verifier = 43-128 random URL-safe characters; code_challenge = base64url (no padding) of SHA-256(code_verifier).

4. Send the member to sign in (open this in their browser). They sign in on Magnatune's own page and click Allow:

https://magnatune.com/oauth/authorize?response_type=code&client_id=mt_...&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback&code_challenge=...&code_challenge_method=S256&scope=member&state=RANDOM&resource=https://magnatune.com%2Fapi

Magnatune redirects to your redirect URI with ?code=...&state=RANDOM&iss=https://magnatune.com (or ?error=access_denied if they cancel). Codes last 10 minutes and work once.

5. Exchange the code for tokens:

POST https://magnatune.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&client_id=mt_...&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback&code_verifier=...

-> {"access_token": "mta_...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "mtr_...", "scope": "member"}

6. Call the API as the member:

GET https://magnatune.com/api/albums/1kub-frenchkiss/tracks/1/file?format=wav
Authorization: Bearer mta_...
-> 200, the clean WAV

7. Refresh when the access token expires (1 hour). Refresh tokens last 180 days and rotate: each use returns a new one, and reusing an old one revokes the whole sign-in:

POST https://magnatune.com/oauth/token
grant_type=refresh_token&refresh_token=mtr_...&client_id=mt_...

Sign out: POST https://magnatune.com/oauth/revoke with token=...&client_id=.... Tokens also stop working when the membership ends (a request then answers 402/401; sign in again after they rejoin).

How to tell you need to sign in: a clean-file request without a login answers 402 Payment Required whose first WWW-Authenticate header is Bearer resource_metadata="https://magnatune.com/.well-known/oauth-protected-resource/api", scope="member" (sign in), followed by MPP Payment challenges (pay instead).

More

Endpoints

All responses are JSON (application/json; charset=utf-8), allow cross-origin requests, and include a license block.

Endpoint Returns Example
GET /api/albums?q=&genre=&collection=&artist=&sort=&offset=&limit= album summaries; at most 100 per page; sort = popular (default), new or name https://magnatune.com/api/albums?q=piano&sort=new
GET /api/albums/{sku} one album in full: tracks with free preview links, covers, genres, collections, buy link and related albums https://magnatune.com/api/albums/1kub-frenchkiss
GET /api/albums/{sku}/downloads?key= after buying: one zip download link per format and one WAV link per track, for the album's download key after buying
GET /api/albums/{sku}/similar albums listeners play alongside this one, then popular albums in its genres https://magnatune.com/api/albums/1kub-frenchkiss/similar
GET /api/albums/{sku}/tracks/{n} one track: its free and clean download links, a credit line and the licence terms https://magnatune.com/api/albums/1kub-frenchkiss/tracks/1
GET /api/albums/{sku}/tracks/{n}/file?format=&key= one song's audio file. No key: the free version (with a short spoken Magnatune voice overlaid on the music every 30 seconds; mp3, aac, ogg or opus). The clean file (format=wav, aac, mp3, ogg or opus) for members (HTTP Basic), album buyers (key=), or an agent paying right there with MPP (402 -> pay -> the file) https://magnatune.com/api/albums/1kub-frenchkiss/tracks/1/file?format=mp3
GET /api/tracks?q=&genre=&collection=&artist=&vocals=&mood=&use=&energy=&key=&instrument=&min_bpm=&max_bpm=&min_seconds=&max_seconds=&sort= single songs with free previews and credit lines, e.g. for a video edit; sort = popular (default), new, name or duration https://magnatune.com/api/tracks?collection=cinematic&vocals=instrumental&min_seconds=120&max_seconds=180
GET /api/artists?q=&offset=&limit= artist summaries https://magnatune.com/api/artists?q=lute
GET /api/artists/{page} one artist with all their albums https://magnatune.com/api/artists/1kub
GET /api/genres genres with album counts https://magnatune.com/api/genres
GET /api/collections collections (the player's tags: moods, instruments, styles, composers) with album counts https://magnatune.com/api/collections
GET /api/collections/{slug}?songs= one collection: its albums, or its songs with songs=1 https://magnatune.com/api/collections/cello?songs=1
GET /api/vocabulary the moods and uses albums are described with (for mood= and use=), and energy levels, with album counts https://magnatune.com/api/vocabulary
GET /api/featured Featured: playlists hand-picked by Magnatune (moods and styles from across the catalog) https://magnatune.com/api/featured
GET /api/featured/{slug} one Featured playlist: its songs in order, with free previews and credit lines https://magnatune.com/api/featured/serene-new-age
GET /api/sql?q=SELECT... any read-only SQL query on the whole catalog (SQLite); with no query: the schema, limits and examples https://magnatune.com/api/sql?q=SELECT%20country%2C%20count(*)%20FROM%20album_details%20GROUP%20BY%201%20ORDER%20BY%202%20DESC
POST /api/member-pass?offer=month (or year, lifetime) buy a Magnatune membership from an agent with MPP (HTTP 402, card/Link via Stripe): $10 for a month, $99 for a year, $299 for life; returns the new login pay with an MPP client
GET /api/openapi.json OpenAPI 3 description https://magnatune.com/api/openapi.json

Filters for /api/albums: q (text in album, artist, track names and descriptions; at least 2 characters), genre (a slug or name from /api/genres, e.g. classical), collection (a slug or name from /api/collections, e.g. background_mix), artist (an artist's page), sort (popular, new or name), offset, limit (at most 100). Paged results give total and a next link.

An album summary gives sku, name, artist, release_date, genres, cover, web_url, api_url and buy_url. A full album adds description, collections, duration_seconds, tracks (number, name, duration and free preview_mp3 / preview_opus stream links), covers in three sizes, buy (price, formats, how) and related albums.

Single songs, e.g. for a video edit

GET /api/albums/{sku}/tracks/{n}/file returns one song as an audio file, ready to drop into a timeline (Final Cut Pro, DaVinci Resolve, Premiere...). Range requests work, and Content-Disposition gives a sensible file name.

Collections (the "tags" in the web player) are the best way to find music for a purpose: moods, instruments and uses like background_mix, plus one collection per classical composer (kind: theme or composer). GET /api/collections/{slug} lists a collection's albums, or its songs with songs=1. Featured playlists (GET /api/featured) are hand-picked by Magnatune: songs for a mood or style from across the catalog, like "Serene New Age" or "Electronica to work to". GET /api/tracks finds single songs by text, genre, collection, artist and length (min_seconds, max_seconds). Measured from each song's audio: tempo_bpm (only when steady_beat is true), key, song_energy (1-5), song_moods and instruments; filter /api/tracks with key= (e.g. D minor, Bb, minor), instrument= (e.g. cello), min_bpm/max_bpm and energy=. Moods, uses, energy, tempo: every album is described with moods (e.g. uplifting, tense, dreamy), uses (e.g. corporate, vlog, trailer, meditation or yoga) and an energy level 1-5 from fixed lists (GET /api/vocabulary), plus instrumentation, sounds-like artists and a one-line summary, written by an AI model from the album's notes, genres, tags and tracks. Filter /api/tracks and /api/albums with mood=, use= and energy= (e.g. 3-5); songs carry bpm_approx (automatic tempo detection, folded into 80-160: fair for rock, electronic and dance, unreliable for ambient and classical), filterable with min_bpm/max_bpm. Text search (q=) matches the moods and uses too. Vocals: songs and albums say whether they have singing (vocals: instrumental, vocals, vocals removed or unknown), and vocals=instrumental (or vocals, removed) filters /api/tracks, /api/albums, /api/collections/{slug} and /api/featured/{slug}. Many albums with singing have a "(vocals removed)" version: instrumental_version gives its sku (the original's + nv, same track numbers). For anything more specific, use SQL (below).

AI assistants (Claude, ChatGPT, Cursor...) can use all of this through Magnatune's MCP server: https://magnatune.com/mcp (Streamable HTTP, no key needed).

Memberships

A Magnatune membership gives the clean songs (no voice overlay), album downloads in every format, and the Magnatune Project Licence: use the music in projects created and released while a member, commercial or not, including client work, with credit. TV/radio broadcast, cinema and in-store or on-hold use are licensed from the musician instead (contact form).

A member's login works as HTTP Basic auth on every API request, in the web player and in the Magnatune apps.

Paying from an agent (MPP), e.g. to put music straight into a video edit

Magnatune accepts the Machine Payments Protocol (HTTP 402, card or Link through Stripe), so an agent can find music, pay and download it with no person involved:

  1. Find music: GET https://magnatune.com/api/albums?... or GET https://magnatune.com/api/sql?q=..., then GET /api/albums/{sku} for the tracks.
  2. Ask for the clean song: GET https://magnatune.com/api/albums/{sku}/tracks/{n}/file?format=wav. Without a membership the answer is 402 Payment Required with WWW-Authenticate: Payment challenges (method stripe, intent charge): a one-month membership first ($10), then one year ($99) and lifetime ($299).
  3. Pay one challenge with any MPP client (e.g. npx @stripe/link-cli mpp pay '<url>') and retry with Authorization: Payment <credential>.
  4. The same response is the WAV file, with Payment-Receipt, and the new member's login in X-Magnatune-Username / X-Magnatune-Password (and X-Magnatune-Expires).
  5. Every later file: the same URL with that login as HTTP Basic auth, no further payment. Drop the files into the edit, and credit each song with the credit line from GET /api/albums/{sku}/tracks/{n}.

To buy a membership without fetching a file: GET or POST https://magnatune.com/api/member-pass?offer=month (or year, lifetime; add &email= for a receipt and welcome email). It answers 402, and after payment returns {username, password, expires, receipt}.

Renewing a pass: passes don't renew by themselves (an agent's card token pays once). To extend one, call the same URL with the member's login as HTTP Basic auth: the 402 challenge then says header="Payment-Authorization", so send the payment there and keep the login in Authorization. The same account is extended (days are added to the current end date, so renewing early loses nothing), or converted to lifetime. Buyers who gave an email get a reminder 3 days before a month pass ends and 14 days before a year pass ends. Payments are single-use and idempotent: retrying with the same credential returns the same login and is never charged twice.

SQL queries: find music any way you like

GET https://magnatune.com/api/sql?q=SELECT... (or POST the SQL as the body, as sql= form data, or as JSON {"sql": "..."}) runs one read-only SQLite SELECT on the whole catalog and returns {columns, rows, row_count, truncated, ms}. No key needed. Limits: one statement, at most 1000 rows (add LIMIT/OFFSET to page), 3 seconds per query, 20 queries and 10 seconds of query time per minute per IP. GET https://magnatune.com/api/sql with no query returns this schema as JSON.

The same database is downloadable: https://magnatune.com/info/sqlite_normalized.db (SQLite file), https://magnatune.com/info/sqlite_normalized.db.gz (gzipped), https://magnatune.com/info/sqlite_normalized.sql.gz (gzipped SQL dump: gunzip it and run it into an empty SQLite database). It is rebuilt with every new release; https://magnatune.com/info/changed.txt changes when it does.

Ready-made views (start here)

How the tables join

  pro ◄──── albums.pro              (each album: one collecting society)
             │
  artists ◄─ albums.artist_id       (artist 1 : N albums)
             │ album_id
             ├──► songs.album_id                        (album 1 : N songs, ordered by track_no)
             │       └─ song_id ──► playlist_songs ──► playlists   (N : M, ordered by sort_order)
             ├──► genres_albums      ──► genres          (N : M)
             ├──► subgenres_albums   ──► subgenres       (N : M; ids off by one: use the album_subgenres view)
             ├──► collections_albums ──► collections     (N : M)
             └──► recommendations    ──► albums          (album -> recommended album, rank 1 = best)
Foreign key (child) Points to (parent) Relationship
albums.artist_id artists.artists_id each album has one artist; an artist has many albums
albums.pro pro.pro_id the album's collecting society (0 = Unknown, 25 = NONE)
songs.album_id albums.album_id an album's tracks; songs.track_no gives their order
genres_albums.album_id, genres_albums.genre_id albums.album_id, genres.genre_id many-to-many: an album has 1+ genres
subgenres_albums.album_id, subgenres_albums.subgenre_id albums.album_id, subgenres.subgenre_id - 1 many-to-many, but the link ids are one LOW in current exports: join subgenres.subgenre_id = subgenres_albums.subgenre_id + 1, or simply use the album_subgenres view
collections_albums.album_id, collections_albums.collection_id albums.album_id, collections.collections_id many-to-many: moods, instruments, uses, composers
playlist_songs.playlist_id, playlist_songs.song_id playlists.playlist_id, songs.song_id many-to-many, ordered by playlist_songs.sort_order
recommendations.album_id, recommendations.recommended_album_id albums.album_id (both) album-to-album suggestions, rank 1 = best match

Watch the key names: the artist key is artists.artists_id (plural) but albums.artist_id; the collection key is collections.collections_id but collections_albums.collection_id. SQLite doesn't declare these foreign keys in the file (PRAGMA foreign_key_list is empty); the table above is the authority. Indexes exist on every album_id, artist_id, genre_id, subgenre_id and collection_id join column.

Ids are permanent: artists_id, album_id and song_id stay the same from one release to the next and are never reused, so they are safe to store. song_id = album_id * 100 + track_no (albums have at most 99 tracks), so song_id / 100 is the album and song_id % 100 the track. Ids from exports before October 2026 were renumbered on every release and don't match these.

Tables and columns

Table (rows) Column Type Meaning (example)
artists (723) artists_id integer, key permanent: never changes or gets reused
name text, unique display name (Paolo Pavan)
page text URL slug: https://magnatune.com/artists/{page}/ (paolo_pavan)
homepage text same as page (legacy)
description text one-line style summary (Urban funky jazz piano...)
bio text full biography
photo text site path of the photo (/artists/img/paolo_pavan.jpg)
city, state, country text where they're from; state only for the USA (Rome, empty, Italy)
albums (1,927) album_id integer, key permanent: one per sku, never changes or gets reused
artist_id integer -> artists.artists_id
name text, unique album title (French Kiss)
sku text, unique the album's id everywhere in this API (1kub-frenchkiss)
description text album notes
upc text barcode
release_date integer Unix timestamp; date(release_date, 'unixepoch') gives YYYY-MM-DD
popularity integer higher = more listened to
pro integer -> pro.pro_id
itunes_buy_url text legacy, usually empty
pro (51) pro_id, name, description integer, text, text collecting society: NONE (25) = in none, Unknown (0) = not recorded, ASCAP, BMI, PRS, SACEM, GEMA... (description adds the country)
songs (23,771) song_id integer, unique album_id * 100 + track_no, so permanent too (56406 = track 6 of album 564)
album_id integer -> albums.album_id
name text song title
track_no integer 1, 2, ...; the audio: GET /api/albums/{sku}/tracks/{track_no}/file
duration integer seconds
mp3 text the file name on the server (01-I'm Monster-1kub.mp3)
genres (10) genre_id, name integer, text Alt Rock, Ambient, Classical, Electro Rock, Electronica, Hard Rock, Hip Hop, Jazz, New Age, World
subgenres (80) subgenre_id, name integer, text finer styles: Baroque, Blues, Chamber Music...
collections (472) collections_id, name integer, text moods, instruments, uses (Background Mix) and one per classical composer
genres_albums (2,478), subgenres_albums (5,221), collections_albums (3,723) integer pairs the many-to-many links above
playlists (24) playlist_id, sort_order, owner_id, name Magnatune-curated playlists (80s Rock)
playlist_songs (5,867) playlist_id, sort_order, song_id integers the songs of each playlist, in order
recommendations (35,492) album_id, recommended_album_id, rank integers "if you like this, try..."

Join recipes

Text matching: LIKE is case-insensitive for ASCII; genres in album_details.genres are comma-separated, so match with genres LIKE '%Jazz%'. Every album row is a released, visible album.

Example queries

To use what you find: each sku works with /api/albums/{sku} (tracks, covers, credit lines); clean audio needs a membership (see "Paying from an agent").

Buying an album for a person

Every album can be bought for $8: 100% of the price goes to the musician, through their own PayPal.

  1. Find an album: GET https://magnatune.com/api/albums?q=... (or genre=, collection=, artist=), then GET /api/albums/{sku} to check its tracks and previews.
  2. Give the person the album's buy_url (https://magnatune.com/buy/album?sku=SKU). They pay $8 on PayPal (card or PayPal account); the money goes straight to the musician. The agent never handles payment details.
  3. After paying, the person sees a download key (also emailed to them). Lost keys: https://magnatune.com/buy/album/lostkey emails every key bought with an email address.
  4. With the key, GET https://magnatune.com/api/albums/{sku}/downloads?key=KEY lists one download link per format (MP3, AAC, ALAC, FLAC, OGG, WAV), each a zip of the whole album, and one link per song. A single song: GET /api/albums/{sku}/tracks/{n}/file?format=wav&key=KEY (also aac, mp3, ogg, opus).

Using the music

Whole-catalog data

To work with the entire catalog offline, download it as SQLite, XML or CSV from https://magnatune.com/info/api. https://magnatune.com/info/changed.txt holds a number that changes whenever there are new releases.

Limits

← Magnatune