{"openapi":"3.1.0","info":{"title":"audiometa.io Web API","version":"1.0.0","description":"Catalog REST API for artists, albums, and tracks — including enrichment such as social stats, playcounts, and audio features.\n\n## Authentication\n\nCreate API keys in the [Audiometa dashboard](https://audiometa.io/dashboard/api).\n\n```http\nAuthorization: Bearer amsk_…\n```\n\nAlso accepted: `x-api-key: amsk_…`\n\n- Up to **3 keys** per account\n- The raw secret is returned **only at creation or rotation time**\n\n## Rate limiting\n\nEach API key is limited to 1 request every 2 seconds. Limits are enforced per key (not per account). Exceeding the limit returns HTTP 429.\n\n- Window: **2 seconds** · Max: **1 request** per key\n- Applies to all authenticated `/v1` endpoints (docs and OpenAPI are not counted)\n- When limited, the response uses status `429` with the standard error JSON shape\n\n## Errors\n\nAll errors use the same JSON shape:\n\n```json\n{ \"error\": { \"status\": 401, \"message\": \"Invalid API key.\" } }\n```\n\nCommon statuses: 400 bad params, 401 auth, 404 not found, 429 rate limited, 500 server error.\n\n## Pagination\n\nList endpoints return offset/limit paging:\n\n```json\n{\n  \"href\": \"…\",\n  \"items\": [],\n  \"limit\": 20,\n  \"next\": \"…\",\n  \"offset\": 0,\n  \"previous\": null,\n  \"total\": 0\n}\n```\n\n## Object conventions\n\nShared fields: `id`, `type`, `href`, `uri` (`audiometa:artist:amart_…`), `external_urls`, `images`, `name`, `popularity`.\n\nAudiometa extensions:\n\n- **Artist** — `stats`, `bio`, `genres`, `country_code`\n- **Track** — `playcounts`, `audio_features`\n- **Album** — `label`, `upc`, `album_type`, `release_date`, `release_date_precision`\n\nBrowse tracks with `/tracks/by-key`, `/tracks/by-tempo`, `/tracks/by-label` (`sort` + `order` supported).\n\nMerged audiometa.io IDs resolve to the canonical entity. Unknown IDs return `404`.\n\n## Base URL\n\nProduction: `https://api.audiometa.io/v1`\n\nInteractive docs: https://api.audiometa.io/v1/docs · OpenAPI: https://api.audiometa.io/v1/openapi.json","contact":{"name":"audiometa.io","url":"https://audiometa.io"}},"servers":[{"url":"https://api.audiometa.io","description":"Production"}],"tags":[{"name":"Search","description":"Full-text search across the catalog."},{"name":"Artists","description":"Artist profiles, discography, top tracks, and related artists."},{"name":"Albums","description":"Album metadata and tracklists."},{"name":"Tracks","description":"Tracks with playcounts and audio features, plus browse by key, tempo, and label."}],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Audiometa API key (`amsk_…`). Create keys in the dashboard."},"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Alternative to Bearer auth. Same `amsk_…` secret."}},"schemas":{"SearchResponse":{"type":"object","properties":{"artists":{"$ref":"#/components/schemas/ArtistPaging"},"albums":{"$ref":"#/components/schemas/AlbumPaging"},"tracks":{"$ref":"#/components/schemas/TrackPaging"}}},"ArtistPaging":{"type":"object","properties":{"href":{"type":"string"},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SimplifiedArtist"},{"type":"object","properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"popularity":{"type":"integer"}}}]}},"limit":{"type":"integer"},"next":{"type":"string","nullable":true},"offset":{"type":"integer"},"previous":{"type":"string","nullable":true},"total":{"type":"integer"}},"required":["href","items","limit","next","offset","previous","total"]},"Image":{"type":"object","properties":{"url":{"type":"string"},"height":{"type":"integer","nullable":true},"width":{"type":"integer","nullable":true}},"required":["url","height","width"]},"SimplifiedArtist":{"type":"object","properties":{"id":{"type":"string","example":"amart_01hxyz…"},"name":{"type":"string","example":"Drake"},"type":{"type":"string","enum":["artist"]},"href":{"type":"string"},"uri":{"type":"string","example":"audiometa:artist:amart_…"},"external_urls":{"type":"object","additionalProperties":{"type":"string"}}},"required":["id","name","type","href","uri","external_urls"]},"AlbumPaging":{"type":"object","properties":{"href":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SimplifiedAlbum"}},"limit":{"type":"integer"},"next":{"type":"string","nullable":true},"offset":{"type":"integer"},"previous":{"type":"string","nullable":true},"total":{"type":"integer"}},"required":["href","items","limit","next","offset","previous","total"]},"SimplifiedAlbum":{"type":"object","properties":{"id":{"type":"string","example":"amalb_01hxyz…"},"name":{"type":"string"},"type":{"type":"string","enum":["album"]},"href":{"type":"string"},"uri":{"type":"string"},"album_type":{"type":"string","example":"album"},"total_tracks":{"type":"integer","nullable":true},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"release_date":{"type":"string","nullable":true,"example":"2024-03-15"},"release_date_precision":{"type":"string","nullable":true,"example":"day","description":"year | month | day"},"artists":{"type":"array","items":{"$ref":"#/components/schemas/SimplifiedArtist"}},"external_urls":{"type":"object","additionalProperties":{"type":"string"}}},"required":["id","name","type","href","uri","album_type","total_tracks","images","release_date","release_date_precision","artists","external_urls"]},"TrackPaging":{"type":"object","properties":{"href":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SimplifiedTrack"}},"limit":{"type":"integer"},"next":{"type":"string","nullable":true},"offset":{"type":"integer"},"previous":{"type":"string","nullable":true},"total":{"type":"integer"}},"required":["href","items","limit","next","offset","previous","total"]},"SimplifiedTrack":{"type":"object","properties":{"id":{"type":"string","example":"amtrk_01hxyz…"},"name":{"type":"string"},"type":{"type":"string","enum":["track"]},"href":{"type":"string"},"uri":{"type":"string"},"duration_ms":{"type":"integer","nullable":true},"explicit":{"type":"boolean"},"popularity":{"type":"integer"},"preview_url":{"type":"string","nullable":true},"disc_number":{"type":"integer","nullable":true},"track_number":{"type":"integer","nullable":true},"artists":{"type":"array","items":{"$ref":"#/components/schemas/SimplifiedArtist"}},"external_urls":{"type":"object","additionalProperties":{"type":"string"}}},"required":["id","name","type","href","uri","duration_ms","explicit","popularity","preview_url","disc_number","track_number","artists","external_urls"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","example":401},"message":{"type":"string","example":"Invalid API key."}},"required":["status","message"]}},"required":["error"]},"ArtistsResponse":{"type":"object","properties":{"artists":{"type":"array","items":{"$ref":"#/components/schemas/Artist"}}},"required":["artists"]},"Artist":{"allOf":[{"$ref":"#/components/schemas/SimplifiedArtist"},{"type":"object","properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"popularity":{"type":"integer"},"genres":{"type":"array","items":{"type":"string"}},"country_code":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"external_ids":{"type":"object","additionalProperties":{"type":"string"}},"followers":{"type":"object","properties":{"total":{"type":"integer","nullable":true}},"required":["total"]},"stats":{"type":"object","properties":{"spotify_monthly_listeners":{"type":"integer","nullable":true},"spotify_followers":{"type":"integer","nullable":true},"youtube_subscribers":{"type":"integer","nullable":true},"instagram_followers":{"type":"integer","nullable":true},"tiktok_followers":{"type":"integer","nullable":true},"soundcloud_followers":{"type":"integer","nullable":true},"facebook_followers":{"type":"integer","nullable":true}},"required":["spotify_monthly_listeners","spotify_followers","youtube_subscribers","instagram_followers","tiktok_followers","soundcloud_followers","facebook_followers"]}},"required":["images","popularity","genres","country_code","bio","external_ids","followers","stats"]}]},"ArtistTrackPaging":{"type":"object","properties":{"href":{"type":"string"},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SimplifiedTrack"},{"type":"object","properties":{"album":{"allOf":[{"$ref":"#/components/schemas/SimplifiedAlbum"},{"nullable":true}]},"playcounts":{"type":"object","properties":{"spotify":{"type":"integer","nullable":true},"youtube":{"type":"integer","nullable":true},"soundcloud":{"type":"integer","nullable":true}},"required":["spotify","youtube","soundcloud"]}}}]}},"limit":{"type":"integer"},"next":{"type":"string","nullable":true},"offset":{"type":"integer"},"previous":{"type":"string","nullable":true},"total":{"type":"integer"}},"required":["href","items","limit","next","offset","previous","total"]},"TopTracksResponse":{"type":"object","properties":{"tracks":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SimplifiedTrack"},{"type":"object","properties":{"album":{"allOf":[{"$ref":"#/components/schemas/SimplifiedAlbum"},{"nullable":true}]},"playcounts":{"type":"object","properties":{"spotify":{"type":"integer","nullable":true},"youtube":{"type":"integer","nullable":true},"soundcloud":{"type":"integer","nullable":true}},"required":["spotify","youtube","soundcloud"]}}}]}}},"required":["tracks"]},"RelatedArtistsResponse":{"type":"object","properties":{"artists":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SimplifiedArtist"},{"type":"object","properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"popularity":{"type":"integer"},"country_code":{"type":"string","nullable":true}}}]}}},"required":["artists"]},"AlbumsResponse":{"type":"object","properties":{"albums":{"type":"array","items":{"$ref":"#/components/schemas/Album"}}},"required":["albums"]},"Album":{"allOf":[{"$ref":"#/components/schemas/SimplifiedAlbum"},{"type":"object","properties":{"label":{"type":"string","nullable":true},"upc":{"type":"string","nullable":true},"popularity":{"type":"integer"},"external_ids":{"type":"object","additionalProperties":{"type":"string"}},"tracks":{"allOf":[{"$ref":"#/components/schemas/TrackPaging"},{"nullable":true}]}},"required":["label","upc","popularity","external_ids","tracks"]}]},"TracksResponse":{"type":"object","properties":{"tracks":{"type":"array","items":{"$ref":"#/components/schemas/Track"}}},"required":["tracks"]},"Track":{"allOf":[{"$ref":"#/components/schemas/SimplifiedTrack"},{"type":"object","properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"external_ids":{"type":"object","additionalProperties":{"type":"string"}},"album":{"allOf":[{"$ref":"#/components/schemas/SimplifiedAlbum"},{"nullable":true}]},"playcounts":{"type":"object","properties":{"spotify":{"type":"integer","nullable":true},"youtube":{"type":"integer","nullable":true},"soundcloud":{"type":"integer","nullable":true}},"required":["spotify","youtube","soundcloud"]},"audio_features":{"$ref":"#/components/schemas/AudioFeatures"}},"required":["images","external_ids","album","playcounts","audio_features"]}]},"AudioFeatures":{"type":"object","nullable":true,"properties":{"tempo":{"type":"number","nullable":true},"key":{"type":"integer","nullable":true},"mode":{"type":"integer","nullable":true},"energy":{"type":"number","nullable":true},"danceability":{"type":"number","nullable":true},"valence":{"type":"number","nullable":true},"loudness":{"type":"number","nullable":true},"time_signature":{"type":"integer","nullable":true}},"required":["tempo","key","mode","energy","danceability","valence","loudness","time_signature"]},"BrowseTrackPaging":{"type":"object","properties":{"href":{"type":"string"},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SimplifiedTrack"},{"type":"object","properties":{"album":{"allOf":[{"$ref":"#/components/schemas/SimplifiedAlbum"},{"type":"object","nullable":true,"properties":{"label":{"type":"string","nullable":true}}}]},"audio_features":{"$ref":"#/components/schemas/AudioFeatures"}}}]}},"limit":{"type":"integer"},"next":{"type":"string","nullable":true},"offset":{"type":"integer"},"previous":{"type":"string","nullable":true},"total":{"type":"integer"}},"required":["href","items","limit","next","offset","previous","total"]}},"parameters":{}},"paths":{"/v1/search":{"get":{"tags":["Search"],"summary":"Search the catalog","description":"Search artists, albums, and/or tracks by free-text query. Returns a paging object per requested type.","parameters":[{"schema":{"type":"string","minLength":1,"example":"drake","description":"Search query string."},"required":true,"description":"Search query string.","name":"q","in":"query"},{"schema":{"type":"string","example":"artist,album,track","description":"Comma-separated entity types to include: `artist`, `album`, `track`. Defaults to all three."},"required":false,"description":"Comma-separated entity types to include: `artist`, `album`, `track`. Defaults to all three.","name":"type","in":"query"},{"schema":{"type":"string","example":"20","description":"Page size (default 20, max 50 unless noted)."},"required":false,"description":"Page size (default 20, max 50 unless noted).","name":"limit","in":"query"},{"schema":{"type":"string","example":"0","description":"Number of items to skip."},"required":false,"description":"Number of items to skip.","name":"offset","in":"query"}],"responses":{"200":{"description":"Search results grouped by type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artists":{"get":{"tags":["Artists"],"summary":"Get several artists","description":"Fetch multiple artists by audiometa.io ID. Pass up to 50 comma-separated IDs. Unknown IDs are omitted from the response.","parameters":[{"schema":{"type":"string","minLength":1,"example":"amart_01h…,amart_01i…","description":"Comma-separated artist IDs (max 50)."},"required":true,"description":"Comma-separated artist IDs (max 50).","name":"ids","in":"query"}],"responses":{"200":{"description":"Artists in request order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtistsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artists/{id}":{"get":{"tags":["Artists"],"summary":"Get an artist","description":"Full artist object including genres, bio, follower totals, and social/platform stats.","parameters":[{"schema":{"type":"string","minLength":1,"example":"amart_01hxyz…","description":"audiometa.io ID (merged IDs resolve to the canonical entity)."},"required":true,"description":"audiometa.io ID (merged IDs resolve to the canonical entity).","name":"id","in":"path"}],"responses":{"200":{"description":"Artist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artist"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artists/{id}/albums":{"get":{"tags":["Artists"],"summary":"Get an artist's albums","description":"All albums credited to an artist, paginated. Optionally filter with `include_groups` (e.g. `album,single,ep,compilation`).","parameters":[{"schema":{"type":"string","minLength":1,"example":"amart_01hxyz…","description":"audiometa.io ID (merged IDs resolve to the canonical entity)."},"required":true,"description":"audiometa.io ID (merged IDs resolve to the canonical entity).","name":"id","in":"path"},{"schema":{"type":"string","example":"album,single,ep","description":"Comma-separated album types to include."},"required":false,"description":"Comma-separated album types to include.","name":"include_groups","in":"query"},{"schema":{"type":"string","example":"20","description":"Page size (default 20, max 50 unless noted)."},"required":false,"description":"Page size (default 20, max 50 unless noted).","name":"limit","in":"query"},{"schema":{"type":"string","example":"0","description":"Number of items to skip."},"required":false,"description":"Number of items to skip.","name":"offset","in":"query"}],"responses":{"200":{"description":"Album paging object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlbumPaging"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artists/{id}/tracks":{"get":{"tags":["Artists"],"summary":"Get an artist's tracks","description":"All tracks credited to an artist, paginated and ordered by popularity. Each item may include album and Spotify playcount.","parameters":[{"schema":{"type":"string","minLength":1,"example":"amart_01hxyz…","description":"audiometa.io ID (merged IDs resolve to the canonical entity)."},"required":true,"description":"audiometa.io ID (merged IDs resolve to the canonical entity).","name":"id","in":"path"},{"schema":{"type":"string","example":"20","description":"Page size (default 20, max 50 unless noted)."},"required":false,"description":"Page size (default 20, max 50 unless noted).","name":"limit","in":"query"},{"schema":{"type":"string","example":"0","description":"Number of items to skip."},"required":false,"description":"Number of items to skip.","name":"offset","in":"query"}],"responses":{"200":{"description":"Track paging object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtistTrackPaging"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artists/{id}/top-tracks":{"get":{"tags":["Artists"],"summary":"Get an artist's top tracks","description":"Most popular tracks for an artist (up to 10), ordered by popularity.","parameters":[{"schema":{"type":"string","minLength":1,"example":"amart_01hxyz…","description":"audiometa.io ID (merged IDs resolve to the canonical entity)."},"required":true,"description":"audiometa.io ID (merged IDs resolve to the canonical entity).","name":"id","in":"path"}],"responses":{"200":{"description":"Top tracks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopTracksResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artists/{id}/related-artists":{"get":{"tags":["Artists"],"summary":"Get related artists","description":"Artists related to the given artist in the Audiometa catalog.","parameters":[{"schema":{"type":"string","minLength":1,"example":"amart_01hxyz…","description":"audiometa.io ID (merged IDs resolve to the canonical entity)."},"required":true,"description":"audiometa.io ID (merged IDs resolve to the canonical entity).","name":"id","in":"path"}],"responses":{"200":{"description":"Related artists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelatedArtistsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/albums":{"get":{"tags":["Albums"],"summary":"Get several albums","description":"Fetch multiple albums by audiometa.io ID. Pass up to 20 comma-separated IDs. Unknown IDs are omitted from the response.","parameters":[{"schema":{"type":"string","minLength":1,"example":"amalb_01h…,amalb_01i…","description":"Comma-separated album IDs (max 20)."},"required":true,"description":"Comma-separated album IDs (max 20).","name":"ids","in":"query"}],"responses":{"200":{"description":"Albums in request order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlbumsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/albums/{id}":{"get":{"tags":["Albums"],"summary":"Get an album","description":"Album details including label, UPC, popularity, and an embedded first page of tracks.","parameters":[{"schema":{"type":"string","minLength":1,"example":"amart_01hxyz…","description":"audiometa.io ID (merged IDs resolve to the canonical entity)."},"required":true,"description":"audiometa.io ID (merged IDs resolve to the canonical entity).","name":"id","in":"path"}],"responses":{"200":{"description":"Album","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Album"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/albums/{id}/tracks":{"get":{"tags":["Albums"],"summary":"Get an album's tracks","description":"Paginated tracklist for an album (default limit 50, max 50).","parameters":[{"schema":{"type":"string","minLength":1,"example":"amart_01hxyz…","description":"audiometa.io ID (merged IDs resolve to the canonical entity)."},"required":true,"description":"audiometa.io ID (merged IDs resolve to the canonical entity).","name":"id","in":"path"},{"schema":{"type":"string","example":"20","description":"Page size (default 20, max 50 unless noted)."},"required":false,"description":"Page size (default 20, max 50 unless noted).","name":"limit","in":"query"},{"schema":{"type":"string","example":"0","description":"Number of items to skip."},"required":false,"description":"Number of items to skip.","name":"offset","in":"query"}],"responses":{"200":{"description":"Track paging object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackPaging"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracks":{"get":{"tags":["Tracks"],"summary":"Get several tracks","description":"Fetch multiple tracks by audiometa.io ID. Pass up to 50 comma-separated IDs. Unknown IDs are omitted from the response.","parameters":[{"schema":{"type":"string","minLength":1,"example":"amtrk_01h…,amtrk_01i…","description":"Comma-separated track IDs (max 50)."},"required":true,"description":"Comma-separated track IDs (max 50).","name":"ids","in":"query"}],"responses":{"200":{"description":"Tracks in request order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TracksResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracks/by-key":{"get":{"tags":["Tracks"],"summary":"Get tracks by musical key","description":"Browse tracks matching a Spotify pitch-class key (0–11). Optionally filter by mode (`0` minor, `1` major). Supports `sort` (`popularity`, `tempo`, `name`, `key`) and `order` (`asc`, `desc`).","parameters":[{"schema":{"type":"string","minLength":1,"example":"0","description":"Pitch class 0–11 (C=0, C#=1, …, B=11)."},"required":true,"description":"Pitch class 0–11 (C=0, C#=1, …, B=11).","name":"key","in":"query"},{"schema":{"type":"string","example":"1","description":"Optional mode filter: 0 = minor, 1 = major."},"required":false,"description":"Optional mode filter: 0 = minor, 1 = major.","name":"mode","in":"query"},{"schema":{"type":"string","enum":["popularity","tempo","name","key"],"example":"popularity","description":"Sort field: popularity | tempo | name | key."},"required":false,"description":"Sort field: popularity | tempo | name | key.","name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"example":"desc","description":"Sort direction (default desc)."},"required":false,"description":"Sort direction (default desc).","name":"order","in":"query"},{"schema":{"type":"string","example":"20","description":"Page size (default 20, max 50 unless noted)."},"required":false,"description":"Page size (default 20, max 50 unless noted).","name":"limit","in":"query"},{"schema":{"type":"string","example":"0","description":"Number of items to skip."},"required":false,"description":"Number of items to skip.","name":"offset","in":"query"}],"responses":{"200":{"description":"Paged tracks with audio features","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrowseTrackPaging"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracks/by-tempo":{"get":{"tags":["Tracks"],"summary":"Get tracks by BPM range","description":"Browse tracks whose tempo falls between `tempo_min` and `tempo_max` (inclusive). Supports `sort` (`popularity`, `tempo`, `name`, `key`) and `order` (`asc`, `desc`).","parameters":[{"schema":{"type":"string","minLength":1,"example":"120","description":"Minimum BPM (inclusive)."},"required":true,"description":"Minimum BPM (inclusive).","name":"tempo_min","in":"query"},{"schema":{"type":"string","minLength":1,"example":"128","description":"Maximum BPM (inclusive)."},"required":true,"description":"Maximum BPM (inclusive).","name":"tempo_max","in":"query"},{"schema":{"type":"string","enum":["popularity","tempo","name","key"],"example":"popularity","description":"Sort field: popularity | tempo | name | key."},"required":false,"description":"Sort field: popularity | tempo | name | key.","name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"example":"desc","description":"Sort direction (default desc)."},"required":false,"description":"Sort direction (default desc).","name":"order","in":"query"},{"schema":{"type":"string","example":"20","description":"Page size (default 20, max 50 unless noted)."},"required":false,"description":"Page size (default 20, max 50 unless noted).","name":"limit","in":"query"},{"schema":{"type":"string","example":"0","description":"Number of items to skip."},"required":false,"description":"Number of items to skip.","name":"offset","in":"query"}],"responses":{"200":{"description":"Paged tracks with audio features","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrowseTrackPaging"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracks/by-label":{"get":{"tags":["Tracks"],"summary":"Get tracks by record label","description":"Browse tracks on albums whose label name contains `label` (case-insensitive). Supports `sort` (`popularity`, `tempo`, `name`, `key`) and `order` (`asc`, `desc`).","parameters":[{"schema":{"type":"string","minLength":1,"example":"OVO","description":"Label name substring to match on the album."},"required":true,"description":"Label name substring to match on the album.","name":"label","in":"query"},{"schema":{"type":"string","enum":["popularity","tempo","name","key"],"example":"popularity","description":"Sort field: popularity | tempo | name | key."},"required":false,"description":"Sort field: popularity | tempo | name | key.","name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"example":"desc","description":"Sort direction (default desc)."},"required":false,"description":"Sort direction (default desc).","name":"order","in":"query"},{"schema":{"type":"string","example":"20","description":"Page size (default 20, max 50 unless noted)."},"required":false,"description":"Page size (default 20, max 50 unless noted).","name":"limit","in":"query"},{"schema":{"type":"string","example":"0","description":"Number of items to skip."},"required":false,"description":"Number of items to skip.","name":"offset","in":"query"}],"responses":{"200":{"description":"Paged tracks with album label + audio features","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrowseTrackPaging"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracks/{id}":{"get":{"tags":["Tracks"],"summary":"Get a track","description":"Full track object including album, credits, playcounts, and audio features when available.","parameters":[{"schema":{"type":"string","minLength":1,"example":"amtrk_01hxyz…","description":"audiometa.io ID (merged IDs resolve to the canonical entity)."},"required":true,"description":"audiometa.io ID (merged IDs resolve to the canonical entity).","name":"id","in":"path"}],"responses":{"200":{"description":"Track","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Track"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (1 request / 2 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}