{
 "openapi": "3.1.0",
 "info": {"title": "Magnatune catalog API", "version": "1.0",
  "x-guidance": "Find music with GET /api/albums (q, genre, collection, sort), GET /api/albums/{sku} and GET /api/sql (read-only SQL on the whole catalog); all free. Free song files: GET /api/albums/{sku}/tracks/{n}/file?format=mp3 (voice overlay, CC BY-NC-SA). Clean files for commercial projects need a Magnatune membership: GET /api/albums/{sku}/tracks/{n}/file?format=wav answers 402 with MPP (Stripe) challenges for month $10, year $99 or lifetime $299; pay one and the file comes back with a new login (X-Magnatune-Username / X-Magnatune-Password) to use as HTTP Basic auth from then on. Or buy the membership alone with POST /api/member-pass?offer=month. Credit each track as in GET /api/albums/{sku}/tracks/{n}.",
  "contact": {"name": "Magnatune", "email": "john@magnatune.com", "url": "https://magnatune.com/info/email_us"},
  "description": "Read-only data for Magnatune's music catalog: albums, artists, tracks with free preview streams, genres and collections. To buy an album for a person, give them the album's buy_url (https://magnatune.com/buy/album?sku=SKU): they pay $8 on PayPal, straight to the musician, and get a download key; /albums/{sku}/downloads?key= then lists the download links. Rate limit: 120 requests per minute per IP.",
  "license": {"name": "Music: CC BY-NC-SA 1.0 (commercial projects: Magnatune membership + Project Licence, see https://magnatune.com/info/licensing)", "url": "https://creativecommons.org/licenses/by-nc-sa/1.0/"}},
 "x-service-info": {"categories": ["music", "audio", "media", "licensing"],
  "docs": {"homepage": "https://magnatune.com/", "apiReference": "https://magnatune.com/api/", "llms": "https://magnatune.com/llms.txt"}},
 "servers": [{"url": "https://magnatune.com"}],
 "paths": {
  "/api/albums": {"get": {"security": [], "summary": "Album summaries (paginated, at most 100)", "parameters": [
    {"name":"q","in":"query","schema":{"type":"string","minLength":2},"description":"text in album, artist and track names and descriptions"},
    {"name":"genre","in":"query","schema":{"type":"string"},"description":"a genre slug or name from /genres, e.g. classical"},
    {"name":"collection","in":"query","schema":{"type":"string"},"description":"a collection slug or name from /collections, e.g. background_mix"},
    {"name":"artist","in":"query","schema":{"type":"string"},"description":"an artist page from /artists, e.g. 1kub"},
    {"name":"vocals","in":"query","schema":{"type":"string","enum":["instrumental","vocals","removed","any"]},"description":"instrumental = no singing (incl. vocals-removed versions)"},
    {"name":"mood","in":"query","schema":{"type":"string"},"description":"a mood from /api/vocabulary, e.g. uplifting"},
    {"name":"use","in":"query","schema":{"type":"string"},"description":"a use from /api/vocabulary, e.g. corporate, vlog, trailer"},
    {"name":"energy","in":"query","schema":{"type":"string","pattern":"^[1-5](-[1-5])?$"},"description":"1 (very calm) to 5 (very intense), or a range like 3-5"},
    {"name":"sort","in":"query","schema":{"type":"string","enum":["popular","new","name","duration"]},"description":"default popular; duration = shortest album first"},
    {"name":"offset","in":"query","schema":{"type":"integer","minimum":0}},
    {"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}], "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/albums/{sku}": {"get": {"security": [], "summary": "One album in full: tracks with free preview streams, covers, genres, collections, buy link and related albums", "parameters": [
    {"name":"sku","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. 1kub-frenchkiss"}], "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/albums/{sku}/downloads": {"get": {"security": [], "summary": "After buying: one zip download link per format (MP3, AAC, ALAC, FLAC, OGG, WAV)", "parameters": [
    {"name":"sku","in":"path","required":true,"schema":{"type":"string"}},
    {"name":"key","in":"query","required":true,"schema":{"type":"string"},"description":"the download key the buyer got from /buy/album"}],
    "responses": {"200":{"description":"download links"},"400":{"description":"no key"},"403":{"description":"wrong key"},"404":{"description":"no such album"},"429":{"description":"rate limited"}}}},
  "/api/albums/{sku}/tracks/{n}": {"get": {"security": [], "summary": "One track: free and clean download links, a credit line and the licence terms", "parameters": [
    {"name":"sku","in":"path","required":true,"schema":{"type":"string"}},
    {"name":"n","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"track number"}], "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/albums/{sku}/tracks/{n}/file": {"get": {"summary": "One song's audio file. Without key: the free version, with a short spoken Magnatune voice overlaid on the music every 30 seconds, which may be used only under CC BY-NC-SA 1.0 (non-commercial, credit, share alike). With the album's download key: the clean file. The terms are repeated in the X-License-Notice response header.", "parameters": [
    {"name":"sku","in":"path","required":true,"example":"1kub-frenchkiss","schema":{"type":"string"}},
    {"name":"n","in":"path","required":true,"example":1,"schema":{"type":"integer","minimum":1}},
    {"name":"format","in":"query","required":true,"example":"wav","schema":{"type":"string","enum":["wav","aac","mp3","ogg","opus"]},"description":"wav or aac: the clean file (membership, MPP payment or the album key); mp3, ogg or opus without a key or login: the free version with the voice overlay. default mp3 without a key or login, wav with one; the clean formats need a membership (HTTP Basic, or pay by MPP on the 402) or the album key"},
    {"name":"key","in":"query","schema":{"type":"string"},"description":"the album's download key, from buying it at /buy/album"}],
    "x-payment-info": {"price": {"mode": "fixed", "currency": "USD", "amount": "10.000000"}, "protocols": [{"mpp": {"method": "stripe", "intent": "charge", "currency": "usd"}}], "offers": [{"amount": "1000", "currency": "usd", "description": "Magnatune membership for 1 month (one-off, does not renew)", "intent": "charge", "method": "stripe"}, {"amount": "9900", "currency": "usd", "description": "Magnatune membership for 1 year (one-off, does not renew)", "intent": "charge", "method": "stripe"}, {"amount": "29900", "currency": "usd", "description": "Magnatune lifetime membership", "intent": "charge", "method": "stripe"}]},
    "responses": {"200":{"description":"the audio file (Content-Disposition attachment; Range requests supported); after an MPP payment it also carries Payment-Receipt and the new login in X-Magnatune-Username / X-Magnatune-Password","content":{"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/mp4":{"schema":{"type":"string","format":"binary"}},"audio/ogg":{"schema":{"type":"string","format":"binary"}}}},"402":{"description":"Payment Required: the clean file needs a membership. WWW-Authenticate: Payment challenges (MPP, method stripe, intent charge); pay one and retry with Authorization: Payment to get the file in that response, with the new login in X-Magnatune-Username / X-Magnatune-Password"},"302":{"description":"dev servers only: redirect to the public free file"},"400":{"description":"bad format"},"403":{"description":"wrong key"},"404":{"description":"no such track or file"},"429":{"description":"rate limited"}}}},
  "/api/sql": {"get": {"security": [], "summary": "Run one read-only SQLite SELECT on the whole catalog; without q, the schema, limits and example queries", "parameters": [
    {"name":"q","in":"query","schema":{"type":"string","maxLength":10000},"description":"one SELECT (views album_details and album_subgenres; tables artists, albums, pro, songs, genres, subgenres, collections, ...)"}],
    "responses": {"200":{"description":"{columns, rows, row_count, truncated, ms}"},"400":{"description":"SQL error or not read-only"},"429":{"description":"rate limited"},"503":{"description":"busy"}}},
   "post": {"security": [], "summary": "Same, with the SQL as the body (text/plain), as sql= form data, or as JSON {\"sql\": \"...\"}", "responses": {"200":{"description":"{columns, rows, row_count, truncated, ms}"},"400":{"description":"SQL error"},"429":{"description":"rate limited"}}}},
  "/api/member-pass": {"post": {"summary": "Buy a Magnatune membership from an agent with MPP (one-off): month $10, year $99, lifetime $299. Returns {username, password, expires, receipt}; use the login as HTTP Basic auth. To renew, call it with that login as HTTP Basic auth: the challenge then uses header=Payment-Authorization and the same account is extended", "parameters": [
    {"name":"offer","in":"query","schema":{"type":"string","enum":["month","year","lifetime"]},"description":"default month"},
    {"name":"email","in":"query","schema":{"type":"string"},"description":"optional: for a welcome email"}],
    "x-payment-info": {"price": {"mode": "fixed", "currency": "USD", "amount": "10.000000"}, "protocols": [{"mpp": {"method": "stripe", "intent": "charge", "currency": "usd"}}], "offers": [{"amount": "1000", "currency": "usd", "description": "Magnatune membership for 1 month (one-off, does not renew)", "intent": "charge", "method": "stripe"}, {"amount": "9900", "currency": "usd", "description": "Magnatune membership for 1 year (one-off, does not renew)", "intent": "charge", "method": "stripe"}, {"amount": "29900", "currency": "usd", "description": "Magnatune lifetime membership", "intent": "charge", "method": "stripe"}]},
    "requestBody": {"required": false, "description": "none needed: the offer and optional email go in the query string", "content": {"application/json": {"schema": {"type": "object"}}}},
    "responses": {"200":{"description":"the new login (also in X-Magnatune-Username / X-Magnatune-Password, with Payment-Receipt)","content":{"application/json":{"schema":{"type":"object","required":["ok","offer","username","password","receipt"],"properties":{"ok":{"type":"boolean"},"offer":{"type":"string","enum":["month","year","lifetime"]},"username":{"type":"string"},"password":{"type":"string"},"expires":{"type":["string","null"],"format":"date-time"},"receipt":{"type":"string","description":"Stripe PaymentIntent id"},"use":{"type":"string"},"licence":{"type":"string"},"account":{"type":"string"}}}}}},"402":{"description":"Payment Required (MPP challenge)"}}}},
  "/api/artists": {"get": {"security": [], "summary": "Artist summaries (paginated, at most 100)", "parameters": [
    {"name":"q","in":"query","schema":{"type":"string","minLength":2},"description":"text in the artist's name and description"},
    {"name":"offset","in":"query","schema":{"type":"integer","minimum":0}},
    {"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}], "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/artists/{page}": {"get": {"security": [], "summary": "One artist with bio and all their albums", "parameters": [
    {"name":"page","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. 1kub"}], "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/genres": {"get": {"security": [], "summary": "Genres with album counts", "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/collections": {"get": {"security": [], "summary": "Collections (the player's tags: moods, instruments, styles, composers) with album counts", "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/collections/{slug}": {"get": {"security": [], "summary": "One collection: its albums, or its songs with songs=1 (paginated)", "parameters": [
    {"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. cello, background_mix"},
    {"name":"songs","in":"query","schema":{"type":"integer","enum":[0,1]},"description":"1: list songs instead of albums"},
    {"name":"sort","in":"query","schema":{"type":"string","enum":["popular","new","name","duration"]}},
    {"name":"offset","in":"query","schema":{"type":"integer","minimum":0}},
    {"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}], "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/tracks": {"get": {"security": [], "summary": "Single songs with free previews and credit lines (paginated, at most 100)", "parameters": [
    {"name":"q","in":"query","schema":{"type":"string","minLength":2},"description":"text in song, album and artist names and album descriptions"},
    {"name":"genre","in":"query","schema":{"type":"string"}},
    {"name":"collection","in":"query","schema":{"type":"string"},"description":"a collection slug, e.g. cinematic"},
    {"name":"artist","in":"query","schema":{"type":"string"}},
    {"name":"vocals","in":"query","schema":{"type":"string","enum":["instrumental","vocals","removed","any"]},"description":"instrumental = no singing (incl. vocals-removed versions)"},
    {"name":"mood","in":"query","schema":{"type":"string"},"description":"a mood from /api/vocabulary, e.g. uplifting"},
    {"name":"use","in":"query","schema":{"type":"string"},"description":"a use from /api/vocabulary, e.g. corporate, vlog, trailer"},
    {"name":"energy","in":"query","schema":{"type":"string","pattern":"^[1-5](-[1-5])?$"},"description":"1 (very calm) to 5 (very intense), or a range like 3-5"},
    {"name":"key","in":"query","schema":{"type":"string"},"description":"musical key measured from the audio, e.g. D minor, F# major, Bb, minor"},
    {"name":"instrument","in":"query","schema":{"type":"string"},"description":"an instrument heard in the song, e.g. piano, cello, electricguitar, synthesizer, voice"},
    {"name":"min_bpm","in":"query","schema":{"type":"integer"},"description":"tempo measured from the audio (songs with a steady beat), else the approximate bpm"},
    {"name":"max_bpm","in":"query","schema":{"type":"integer"}},
    {"name":"min_seconds","in":"query","schema":{"type":"integer","minimum":0}},
    {"name":"max_seconds","in":"query","schema":{"type":"integer","minimum":0}},
    {"name":"sort","in":"query","schema":{"type":"string","enum":["popular","new","name","duration"]}},
    {"name":"offset","in":"query","schema":{"type":"integer","minimum":0}},
    {"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}], "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/albums/{sku}/similar": {"get": {"security": [], "summary": "Albums listeners play alongside this one, then popular albums in its genres", "parameters": [
    {"name":"sku","in":"path","required":true,"schema":{"type":"string"}},
    {"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}], "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/vocabulary": {"get": {"security": [], "summary": "The moods and uses albums are described with, and energy levels, with album counts", "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/featured": {"get": {"security": [], "summary": "Featured playlists, hand-picked by Magnatune", "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}},
  "/api/featured/{slug}": {"get": {"security": [], "summary": "One Featured playlist's songs, in order (paginated)", "parameters": [
    {"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. serene-new-age"},
    {"name":"offset","in":"query","schema":{"type":"integer","minimum":0}},
    {"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}], "responses": {"200":{"description":"JSON object; every response includes a license block","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"bad parameter"},"404":{"description":"not found"},"429":{"description":"rate limited"}}}}
 },
 "components": {"securitySchemes": {"memberBasic": {"type": "http", "scheme": "basic", "description": "a Magnatune member login (from signup or POST /api/member-pass); sent with a paid request it unlocks clean files without paying again"},
  "memberOAuth": {"type": "oauth2", "description": "OAuth 2.1 sign-in for members (authorization code + PKCE S256; register your client first with RFC 7591 dynamic registration at https://magnatune.com/oauth/register; metadata: https://magnatune.com/.well-known/oauth-authorization-server and https://magnatune.com/.well-known/oauth-protected-resource/api). Send the access token as Authorization: Bearer; it works on every member feature: clean track files, album zips, /membership/settings, /api/mydownloads.",
   "flows": {"authorizationCode": {"authorizationUrl": "https://magnatune.com/oauth/authorize", "tokenUrl": "https://magnatune.com/oauth/token", "refreshUrl": "https://magnatune.com/oauth/token", "scopes": {"member": "use the member's Magnatune membership: clean files, album zips, library, downloads", "download": "only download clean files and album zips"}}}}}}
}