# Magnatune catalog API

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: OAuth 2.1 sign-in, no password needed** (steps: https://magnatune.com/api/#oauth). AI assistants can instead connect https://magnatune.com/mcp/account. Terminals, SSH and cloud agents with no browser callback: device sign-in (the member enters a short code at https://magnatune.com/device), or run the ready-made `node magnatune-login.mjs --scope download` (https://magnatune.com/api/magnatune-login.mjs, no dependencies).

## 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 token: the member signs in on Magnatune's page; never ask for their password) |
|---|---|---|
| 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_...

**No browser on this machine, or no local callback (SSH, cloud agents, terminals)? Device sign-in (RFC 8628).** No registration needed: use `client_id=magnatune-cli`.

    POST https://magnatune.com/oauth/device_authorization
    client_id=magnatune-cli&scope=download

    -> {"device_code": "...", "user_code": "BCDF-GHJK", "verification_uri": "https://magnatune.com/device", "verification_uri_complete": "https://magnatune.com/device?code=BCDF-GHJK", "expires_in": 900, "interval": 5}

Tell the member: open https://magnatune.com/device and enter the code (or give them `verification_uri_complete`); they sign in on Magnatune's page and click Allow. Meanwhile poll every `interval` seconds:

    POST https://magnatune.com/oauth/token
    grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=...&client_id=magnatune-cli

    -> 400 {"error": "authorization_pending"} until they allow ("slow_down": poll less often; "access_denied" / "expired_token": stop), then the same tokens as step 5

**Ready-made command:** https://magnatune.com/api/magnatune-login.mjs (Node 18+, no dependencies) runs either flow and prints a token, or downloads clean songs:

    curl -O https://magnatune.com/api/magnatune-login.mjs
    node magnatune-login.mjs --scope download                 # prints an access token
    node magnatune-login.mjs --device --get 1kub-frenchkiss/1 # device sign-in, saves the clean WAV

**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

- **JSON version of this page:** <https://magnatune.com/api/index.json> (Markdown: <https://magnatune.com/api/?format=md>)
- **OpenAPI description:** <https://magnatune.com/api/openapi.json> (also at <https://magnatune.com/openapi.json>, with MPP `x-payment-info` on paid routes; OAuth as the `memberOAuth` security scheme)
- **SQL over the whole catalog:** <https://magnatune.com/api/sql> (schema and examples)
- **Search with your own judgement (recommended for AI agents; the `q=` searches below are plain keyword matching):** turn the request into regular expressions and get only the matching catalog lines: `https://magnatune.com/api/grep?re=calm|serene|meditat&re=cello|piano` (Tcl regular expressions: syntax at <https://magnatune.com/api/regex>; case-insensitive, every `re=` must match; compact lines with match snippets by default, `fields=all` for whole lines, `limit=` up to 500; `skus=a,b` for given albums). Then `https://magnatune.com/artists/albums/{sku}/about.md` for everything about an album (Markdown). Whole catalog as text: <https://magnatune.com/api/catalog.txt>
- **Site description for AI agents:** <https://magnatune.com/llms.txt>

## 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> |
| `GET /api/magnatune-login.mjs` | ready-made OAuth sign-in command for members (Node 18+, no dependencies): prints a token or downloads clean songs; no password passes through it |  |

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, free `preview_mp3` / `preview_opus` stream links and, when not signed in, `clean_url` + `clean_auth`: the clean file and how to sign in for it), 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.

- **Without a key** anyone gets the **free version**: the whole song with a short spoken Magnatune voice overlaid on the music every 30 seconds, as `format=mp3` (default), `aac`, `ogg` or `opus`. Anyone using it must follow the [Creative Commons BY-NC-SA 1.0](https://creativecommons.org/licenses/by-nc-sa/1.0/) licence: non-commercial use only, credit the artist and Magnatune, and share alike. Every file response repeats this in its `X-License-Notice` header, and `GET /api/albums/{sku}/tracks/{n}` gives the terms plus a ready-made credit line.
- **With the album's download key** (after buying the album) the same URL gives the **clean** song: `format=wav` (default, lossless), `aac`, `mp3`, `ogg` or `opus`. Add `&key=KEY`.
- **Members** get the clean song too, with no key: sign them in with OAuth (below) and send `Authorization: Bearer <token>`, or send their membership login as HTTP Basic auth. Members may use it in projects under the [Magnatune Project Licence](https://magnatune.com/info/licensing) (commercial use, client work; credit required).
- Commercial projects otherwise need a membership: [join Magnatune](https://magnatune.com/member/signup).

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](https://magnatune.com/info/licensing): 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](https://magnatune.com/musician/contact)).

- **A person** joins at <https://magnatune.com/member/signup>: $10/month or $99/year (renewing), or $299 for life.
- **An agent** can pay by itself with MPP (below): $10 for one month, $99 for one year or $299 for life, each a one-off payment that does not renew.

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

**Only for people who are not members yet:** an existing member signs in with OAuth instead (#oauth above; no payment, no password).

Magnatune accepts the [Machine Payments Protocol](https://mpp.dev) (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)

- **`album_details`**: one row per album with everything you usually filter on: `album_id, sku, album, artist_id, artist, artist_page, city, state, country, release_date` (YYYY-MM-DD), `popularity` (higher = more listened to), `pro` (collecting society short name), `pro_description`, `genres` (comma-separated), `web_url`, `api_url`.
- **`song_vocals`**: `song_id, vocals`, and **`album_vocals`**: `album_id, vocals`. `vocals` is `n` (instrumental: never had vocals), `y` (has singing) or `r` (vocals removed: the "(vocals removed)" albums, whose sku is the original's sku + `nv`, same track numbers), or NULL (not checked yet). For instrumental music use `coalesce(v.vocals,'') <> 'y'`.
- **`album_ai`**: `album_id, moods, uses, energy, instrumentation, sounds_like, summary`: each album described by an AI model for people choosing music for videos. `moods` and `uses` are comma-separated words from fixed lists (`GET https://magnatune.com/api/vocabulary`); match one with `(', ' || moods || ',') LIKE '%, uplifting,%'`. `energy` is 1 (very calm) to 5 (very intense).
- The same data is in the `albums` columns `moods, uses, energy, instrumentation, sounds_like, ai_summary` and the `songs` column `bpm` (in catalogs exported since 2026-10-20).
- **`song_bpm`**: `song_id, bpm`: approximate tempo from automatic detection, folded into 80-160 (fair for rock, electronic and dance; unreliable for ambient and classical).
- **`song_audio`**: `song_id, tempo, tempo_conf, beats_conf, musical_key, key_strength, danceability, loudness_db, energy, audio_moods, audio_instruments`: each song measured from its audio (Essentia). `tempo` is only meaningful when `beats_conf >= 1.5` (a steady beat; ambient, rubato and free-time pieces score lower); `musical_key` like `D minor`; `energy` 1-5 (fifths of the catalog); `audio_moods` (MTG-Jamendo moods/themes such as film, relaxing, energetic, corporate, epic) and `audio_instruments` (piano, cello, electricguitar, synthesizer, drums, voice...) are comma-separated. Also in the `songs` columns of catalogs exported since 2026-10-21.
- **`album_subgenres`**: `album_id, subgenre_id, subgenre`. Use this rather than joining `subgenres_albums` yourself (its ids are off by one in current exports; the view corrects it).

### How the tables join

```text
  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

- An album with its artist and collecting society:
  `SELECT al.sku, al.name AS album, ar.name AS artist, ar.country, p.name AS pro FROM albums al JOIN artists ar ON ar.artists_id = al.artist_id JOIN pro p ON p.pro_id = al.pro WHERE al.sku = '1kub-frenchkiss'`
- An album's tracks, in order:
  `SELECT s.track_no, s.name, s.duration FROM songs s JOIN albums al ON al.album_id = s.album_id WHERE al.sku = '1kub-frenchkiss' ORDER BY s.track_no`
- Albums in a genre:
  `SELECT al.sku, al.name FROM albums al JOIN genres_albums ga ON ga.album_id = al.album_id JOIN genres g ON g.genre_id = ga.genre_id WHERE g.name = 'Jazz'`
- Albums in a subgenre (the raw ids are one low, hence + 1):
  `SELECT al.sku, al.name FROM albums al JOIN subgenres_albums sa ON sa.album_id = al.album_id JOIN subgenres sg ON sg.subgenre_id = sa.subgenre_id + 1 WHERE sg.name = 'Baroque'`
- Albums in a collection:
  `SELECT al.sku, al.name FROM albums al JOIN collections_albums ca ON ca.album_id = al.album_id JOIN collections c ON c.collections_id = ca.collection_id WHERE c.name = 'Background Mix'`
- A playlist's songs, in order, with their albums:
  `SELECT ps.sort_order, s.name AS song, al.sku, s.track_no FROM playlists pl JOIN playlist_songs ps ON ps.playlist_id = pl.playlist_id JOIN songs s ON s.song_id = ps.song_id JOIN albums al ON al.album_id = s.album_id WHERE pl.name = '80s Rock' ORDER BY ps.sort_order`
- Albums recommended for an album:
  `SELECT r.rank, rec.sku, rec.name FROM recommendations r JOIN albums src ON src.album_id = r.album_id JOIN albums rec ON rec.album_id = r.recommended_album_id WHERE src.sku = '1kub-frenchkiss' ORDER BY r.rank`

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

- Jazz artists from outside the USA whose albums are in no collecting society (11 artists: Argentina, Brazil, Czech Republic, England, Germany, Italy, Japan, Russia, Serbia):
  `SELECT DISTINCT artist, city, country, album FROM album_details WHERE genres LIKE '%Jazz%' AND country <> 'USA' AND pro = 'NONE' ORDER BY country, artist`
- French jazz artists, with the collecting society each album is in (none are society-free, so this shows how to relax a filter):
  `SELECT DISTINCT artist, city, album, pro_description FROM album_details WHERE country = 'France' AND genres LIKE '%Jazz%'`
- Short ambient tracks (2-3 minutes) from albums in no collecting society, most popular first:
  `SELECT d.artist, d.album, s.track_no, s.name AS song, s.duration, d.api_url || '/tracks/' || s.track_no AS track_api FROM songs s JOIN album_details d ON d.album_id = s.album_id WHERE d.genres LIKE '%Ambient%' AND d.pro = 'NONE' AND s.duration BETWEEN 120 AND 180 ORDER BY d.popularity DESC LIMIT 50`
- Albums in a subgenre (use the album_subgenres view, not subgenres_albums):
  `SELECT d.artist, d.album, d.release_date FROM album_subgenres x JOIN album_details d ON d.album_id = x.album_id WHERE x.subgenre = 'Baroque' ORDER BY d.release_date DESC`
- Instrumental songs (no singing) of 2-4 minutes in the Cinematic collection:
  `SELECT d.artist, d.album, s.track_no, s.name AS song, s.duration FROM songs s JOIN song_vocals v ON v.song_id = s.song_id JOIN album_details d ON d.album_id = s.album_id JOIN collections_albums ca ON ca.album_id = s.album_id JOIN collections c ON c.collections_id = ca.collection_id WHERE c.name = 'Cinematic' AND coalesce(v.vocals, '') <> 'y' AND s.duration BETWEEN 120 AND 240 ORDER BY d.popularity DESC LIMIT 50`
- Calm, uplifting instrumental songs for a corporate video (moods and uses from album_ai), 2-4 minutes:
  `SELECT d.artist, d.album, s.track_no, s.name AS song, s.duration, ai.energy, ai.summary FROM songs s JOIN album_ai ai ON ai.album_id = s.album_id JOIN song_vocals v ON v.song_id = s.song_id JOIN album_details d ON d.album_id = s.album_id WHERE (', ' || ai.uses || ',') LIKE '%, corporate,%' AND (', ' || ai.moods || ',') LIKE '%, uplifting,%' AND v.vocals IN ('n','r') AND s.duration BETWEEN 120 AND 240 ORDER BY d.popularity DESC LIMIT 50`
- Fast electronic tracks around 128 BPM with high energy, for a workout video:
  `SELECT d.artist, d.album, s.track_no, s.name AS song, b.bpm FROM songs s JOIN song_bpm b ON b.song_id = s.song_id JOIN album_ai ai ON ai.album_id = s.album_id JOIN album_details d ON d.album_id = s.album_id WHERE d.genres LIKE '%Electronica%' AND b.bpm BETWEEN 124 AND 132 AND ai.energy >= 4 ORDER BY d.popularity DESC LIMIT 50`
- Steady-beat songs around 90 BPM in a minor key with piano, under 3 minutes:
  `SELECT d.artist, d.album, s.track_no, s.name AS song, x.tempo, x.musical_key, x.audio_instruments FROM songs s JOIN song_audio x ON x.song_id = s.song_id JOIN album_details d ON d.album_id = s.album_id WHERE x.beats_conf >= 1.5 AND x.tempo BETWEEN 85 AND 95 AND x.musical_key LIKE '% minor' AND (', ' || x.audio_instruments || ',') LIKE '%, piano,%' AND s.duration < 180 ORDER BY d.popularity DESC LIMIT 50`
- Albums per country:
  `SELECT country, count(*) AS albums FROM album_details GROUP BY country ORDER BY albums DESC`
- Albums in a collection (moods, instruments, uses, composers):
  `SELECT d.artist, d.album FROM collections c JOIN collections_albums ca ON ca.collection_id = c.collections_id JOIN album_details d ON d.album_id = ca.album_id WHERE c.name = 'Background Mix'`

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

- **Licence:** all Magnatune music is under [Creative Commons Attribution-NonCommercial-ShareAlike 1.0 (CC BY-NC-SA 1.0)](https://creativecommons.org/licenses/by-nc-sa/1.0/).
- **Listening:** Stream the free previews, or buy an album for $8 to download it in MP3, AAC, ALAC, FLAC, OGG or WAV. 100% of the price goes to the musician.
- **Non-commercial use:** Non-commercial projects may use the music under CC BY-NC-SA 1.0: credit the artist and Magnatune, and share alike.
- **Projects:** Magnatune members may use any Magnatune music in their projects, commercial or not (videos, films, podcasts, games, apps, websites, adverts), including work for clients, under the Magnatune Project Licence. Projects released while a member stay licensed for good; new projects need an active membership. Credit is required. TV or radio broadcast, cinema, and background music in shops, restaurants or on-hold lines are not included: license those from the musician. Membership: $10/month, $99/year or $299 lifetime; agents can buy one themselves with MPP at /api/member-pass ($10 month, $99 year, $299 lifetime, one-off).
- Details: <https://magnatune.com/info/licensing>. How to credit: Name the artist and "Magnatune", with a link to the album's web_url.

## 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

- 120 requests per minute per IP address; over that you get HTTP 429 with `Retry-After`.
- Responses may be cached for 10 minutes. Member, sales and payment data are never served under `/api/`.
