{"openapi":"3.1.0","info":{"title":"Bitsound public catalog API","version":"1.0.0","description":"Read-only access to the published Bitsound catalog. No sign-in needed. For AI clients there is also an MCP server at /mcp (with sign-in) and /mcp/public (without). Please keep requests moderate, there are rate limits."},"servers":[{"url":"https://bitsound.com"}],"paths":{"/api/v1/releases":{"get":{"summary":"List published releases","operationId":"listReleases","parameters":[{"name":"q","in":"query","description":"Text in release title, artist name or track titles","schema":{"type":"string","maxLength":100}},{"name":"genre","in":"query","description":"Matches the main or the second genre","schema":{"type":"string","enum":["Electronic","House","Techno","Trance","Ambient","Downtempo","Synthwave","Pop","Rock","Indie","Jazz","Classical","Hip-Hop","Soundtrack","Experimental","RnB","Metal","Folk","Blues","Country","Reggae","Latin","World","DrumAndBass","Dubstep","Schlager","Kids","SpokenWord","Other"]}},{"name":"mood","in":"query","description":"Releases with at least one track of this mood","schema":{"type":"string","enum":["calm","relaxed","energetic","danceable","dark","happy","melancholic","aggressive"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["new","title"],"default":"new"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":48}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseSummary"}},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}}},"/api/v1/releases/{id}":{"get":{"summary":"One published release with its tracks, lyrics, stories and credits","operationId":"getRelease","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"release":{"allOf":[{"$ref":"#/components/schemas/ReleaseSummary"},{"type":"object","properties":{"tracks":{"type":"array","items":{"$ref":"#/components/schemas/Track"}}}}]},"moreFromArtist":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseSummary"}}}}}}},"404":{"description":"Not found"}}}},"/api/v1/tracks/{id}/extras":{"get":{"summary":"Lyrics, story and credits of a published track","operationId":"getTrackExtras","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"trackId":{"type":"string","format":"uuid"},"title":{"type":"string"},"releaseId":{"type":"string","format":"uuid"},"lyrics":{"type":"string"},"story":{"type":"string"},"credits":{"type":"array","items":{"type":"object"}}}}}}},"404":{"description":"Not found"}}}},"/api/v1/artists/{slug}":{"get":{"summary":"An artist with bio, links and published releases","operationId":"getArtist","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"artist":{"allOf":[{"$ref":"#/components/schemas/ArtistSummary"},{"type":"object","properties":{"bio":{"type":"string"},"links":{"type":"array","items":{"type":"string"}}}}]},"releases":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseSummary"}}}}}}},"404":{"description":"Not found"}}}},"/api/v1/search":{"get":{"summary":"Search releases, artists, tracks and lyrics","operationId":"search","parameters":[{"name":"q","in":"query","description":"Search text, required unless mood is given","schema":{"type":"string","maxLength":100}},{"name":"mood","in":"query","description":"Only tracks and releases with this mood","schema":{"type":"string","enum":["calm","relaxed","energetic","danceable","dark","happy","melancholic","aggressive"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"releases":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseSummary"}},"artists":{"type":"array","items":{"$ref":"#/components/schemas/ArtistSummary"}},"tracks":{"type":"array","items":{"type":"object"}},"lyrics":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/v1/genres":{"get":{"summary":"Genres with the number of published releases","operationId":"listGenres","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"genre":{"type":"string"},"releases":{"type":"integer"}}}}}}}}}}}},"/api/v1/moods":{"get":{"summary":"Moods with the number of published releases and tracks","operationId":"listMoods","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"mood":{"type":"string","enum":["calm","relaxed","energetic","danceable","dark","happy","melancholic","aggressive"]},"releases":{"type":"integer"},"tracks":{"type":"integer"}}}}}}}}}}}},"/api/v1/home":{"get":{"summary":"Newest releases and artists, as on the start page","operationId":"home","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"releases":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseSummary"}},"artists":{"type":"array","items":{"$ref":"#/components/schemas/ArtistSummary"}}}}}}}}}}},"components":{"schemas":{"ArtistSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"imageUrl":{"type":["string","null"]},"location":{"type":"string"}}},"ReleaseSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"type":{"type":"string","enum":["album","ep","single"]},"genre":{"type":"string"},"secondaryGenre":{"type":"string","description":"Optional second genre, empty when not set"},"description":{"type":"string"},"releaseDate":{"type":["string","null"],"format":"date"},"aiGenerated":{"type":["string","null"],"enum":["no","partly","yes",null],"description":"AI labelling by the artist, null when not specified"},"priceCents":{"type":"integer","description":"Price of the whole release in cents"},"currency":{"type":"string","example":"EUR"},"coverUrl":{"type":["string","null"],"description":"Path relative to the site"},"publishedAt":{"type":["string","null"],"format":"date-time"},"artist":{"$ref":"#/components/schemas/ArtistSummary"},"trackCount":{"type":"integer"},"durationMs":{"type":"integer"}}},"Track":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"position":{"type":"integer"},"title":{"type":"string"},"priceCents":{"type":"integer"},"durationMs":{"type":["integer","null"]},"moods":{"type":"array","items":{"type":"string","enum":["calm","relaxed","energetic","danceable","dark","happy","melancholic","aggressive"]},"description":"Up to 3 moods, detected from the audio or set by the artist"},"lyrics":{"type":"string"},"story":{"type":"string"},"credits":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"name":{"type":"string"},"detail":{"type":"string"}}}}}}}}}