{"openapi":"3.0.3","info":{"title":"Songsterr API","version":"0.3.2","description":"Public part of the Songsterr API.\n\nChanges are backward compatible:\n- New fields can appear in responses at any time; ignore fields you do not know.\n- Only required fields are guaranteed. Optional fields can be removed; fields marked deprecated will be.\n\nThe requester's country is taken from the IP address; songs restricted in that country are never returned.\nPlease send a `User-Agent` that identifies your app and version."},"servers":[{"url":"https://www.songsterr.com"}],"paths":{"/api/search":{"get":{"summary":"Search songs","description":"Searches the catalog by artist and title. Results are filtered by the requester's country, taken from the IP address. Responses are cached: 10 seconds for a search, 10 minutes for the popular list without a pattern.","parameters":[{"schema":{"type":"string"},"in":"query","name":"pattern","required":false,"description":"Free text matched against artist and title. Up to 250 characters; a longer pattern returns no results. Without a pattern, songs are listed by popularity."},{"schema":{"anyOf":[{"type":"string","enum":["guitar"]},{"type":"string","enum":["bass"]},{"type":"string","enum":["drums"]}]},"in":"query","name":"inst","required":false,"description":"Only songs with an interactive player and a track of this instrument. Also ranks results by that instrument and picks `defaultTrack` among its tracks."},{"schema":{"type":"string"},"in":"query","name":"tuning","required":false,"description":"Only songs with a track in this tuning: comma-separated MIDI note numbers from the highest string, for example `64,59,55,50,45,40` for standard guitar tuning. Without `inst`, matches guitar and bass tracks."},{"schema":{"anyOf":[{"type":"string","enum":["0"]},{"type":"string","enum":["1"]},{"type":"string","enum":["2"]}]},"in":"query","name":"difficulty","required":false,"description":"Difficulty level of a track: `0` easy, `1` intermediate, `2` hard."},{"schema":{"type":"boolean"},"in":"query","name":"latest","required":false,"description":"Order by the date of the latest revision instead of popularity."},{"schema":{"type":"number"},"in":"query","name":"size","required":false,"description":"Page size, 10 by default, at most 250; a larger value is rejected with 422. `from + size` is capped at 9999."},{"schema":{"type":"number"},"in":"query","name":"from","required":false,"description":"Offset of the first result, 0 by default."},{"schema":{"type":"boolean"},"in":"query","name":"explicit","required":false,"description":"Show (`true`) or hide (`false`) songs with explicit titles. By default they are hidden unless the pattern itself contains explicit words."},{"schema":{"type":"boolean"},"in":"query","name":"exhaustive","required":false,"description":"Ignored; kept for compatibility."},{"schema":{"type":"boolean"},"in":"query","name":"prefix","required":false,"description":"Ignored; kept for compatibility."},{"schema":{"type":"boolean"},"in":"query","name":"more","required":false,"description":"With track filters (`inst`, `tuning`, `difficulty`) on the first page, also report how many songs match the pattern without them in `hasMoreWithoutFilters` and `additionalResultsCount`."},{"schema":{"type":"boolean"},"in":"query","name":"stats","required":false,"description":"Include view and favorite counters in each record."},{"schema":{"type":"boolean"},"in":"query","name":"work","required":false,"description":"Include `work` in each record: the tab's place among the tabs of the same song, and the tab it duplicates."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["songId","artistId","artist","title","hasChords","hasPlayer","tracks","defaultTrack","popularTrack"],"properties":{"songId":{"type":"number","description":"Song id. The tab page is `https://www.songsterr.com/a/wsa/<slug>-tab-s<songId>`; the slug is cosmetic and the server redirects to the canonical URL, keeping the query string."},"artistId":{"type":"number"},"artist":{"type":"string","description":"Artist name."},"title":{"type":"string","description":"Song title."},"hasChords":{"type":"boolean","description":"A chord sheet exists for the song."},"isCover":{"type":"boolean","description":"The tab is a cover version rather than the original recording."},"isJunk":{"type":"boolean","deprecated":true,"description":"Low-quality record. Will be removed once the catalog is cleaned up; treat a missing value as `false`."},"hasPlayer":{"type":"boolean","description":"An interactive tab with the player exists for the song."},"tracks":{"type":"array","items":{"type":"object","required":["instrumentId","instrument","views"],"properties":{"instrumentId":{"type":"number","description":"General MIDI program number of the instrument; drums are 1024."},"instrument":{"type":"string","description":"Human-readable instrument name."},"name":{"type":"string","description":"Track name given by the author."},"tuning":{"type":"array","items":{"type":"number"},"description":"MIDI note numbers of the open strings, from the highest string."},"difficulty":{"type":"number","description":"Difficulty from 1 (easy) to 8 (hard). Levels for the `difficulty` filter: 1-2 easy, 3-5 intermediate, 6-8 hard."},"views":{"type":"number","description":"View count of this track."},"hash":{"type":"string","description":"Content hash of the track."}}},"description":"Tracks of the latest revision."},"defaultTrack":{"type":"number","description":"Index in `tracks` of the track that best matches the request: the most viewed track satisfying the `inst`, `tuning` and `difficulty` filters."},"popularTrack":{"type":"number","description":"Index in `tracks` of the most viewed track of any instrument."},"popularTrackGuitar":{"type":"number","description":"Index in `tracks` of the most viewed guitar track; absent when the song has none."},"popularTrackBass":{"type":"number","description":"Index in `tracks` of the most viewed bass track; absent when the song has none."},"popularTrackDrum":{"type":"number","description":"Index in `tracks` of the most viewed drum track; absent when the song has none."},"popularTrackVocals":{"type":"number","description":"Index in `tracks` of the most viewed vocal track; absent when the song has none."},"addedAt":{"type":"string"},"lastViewedAt":{"type":"string"},"totalViews":{"type":"number","description":"Views of the song; only with `stats=true`."},"guitarViews":{"type":"number","description":"Views of guitar tracks; only with `stats=true`."},"bassViews":{"type":"number","description":"Views of bass tracks; only with `stats=true`."},"drumsViews":{"type":"number","description":"Views of drum tracks; only with `stats=true`."},"favoritesCount":{"type":"number","description":"Number of users who added the song to favorites; only with `stats=true`."},"duplicateOf":{"type":"number","deprecated":true,"description":"Id of the song this record duplicates. Will be removed once the catalog is cleaned up; use `work.duplicateOf`."},"work":{"anyOf":[{"type":"object","required":["id","mainSongId","role","recording","tuning","duplicateOf"],"properties":{"id":{"type":"number","description":"The work: the tabs of one song by one artist."},"mainSongId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The work's main tab; `null` while undecided."},"role":{"anyOf":[{"anyOf":[{"type":"string","enum":["main"]},{"type":"string","enum":["copy"]},{"type":"string","enum":["variant"]},{"type":"string","enum":["part"]},{"type":"string","enum":["arrangement"]},{"type":"string","enum":["junk"]}]},{"type":"null"}],"description":"What the tab is within the work; `null` while undecided."},"recording":{"anyOf":[{"anyOf":[{"type":"string","enum":["album"]},{"type":"string","enum":["live"]},{"type":"string","enum":["demo"]},{"type":"string","enum":["cover"]},{"type":"string","enum":["unknown"]}]},{"type":"null"}],"description":"Which recording the tab transcribes; `null` while undecided."},"tuning":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The retuning the tab is in, e.g. `Drop D`; `null` for the recording's own tuning."},"duplicateOf":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Song id of the tab this one adds nothing over: a `copy` of the work's main tab (its notes are all in it, at the same pitch). Hiding it in a list that has that tab loses nothing."}}},{"type":"null"}],"description":"Only with `work=true`: the tab's work, `null` when the song is in none."}}},"description":"Matching songs: by text match first, then by popularity (or by date with `latest=true`)."},"hasMoreWithoutFilters":{"type":"boolean","description":"Only with `more=true`: more songs match the pattern without the track filters."},"additionalResultsCount":{"type":"number","description":"Only with `more=true`: estimated number of those extra songs."}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["songId","artistId","artist","title","hasChords","hasPlayer","tracks","defaultTrack","popularTrack"],"properties":{"songId":{"type":"number","description":"Song id. The tab page is `https://www.songsterr.com/a/wsa/<slug>-tab-s<songId>`; the slug is cosmetic and the server redirects to the canonical URL, keeping the query string."},"artistId":{"type":"number"},"artist":{"type":"string","description":"Artist name."},"title":{"type":"string","description":"Song title."},"hasChords":{"type":"boolean","description":"A chord sheet exists for the song."},"isCover":{"type":"boolean","description":"The tab is a cover version rather than the original recording."},"isJunk":{"type":"boolean","deprecated":true,"description":"Low-quality record. Will be removed once the catalog is cleaned up; treat a missing value as `false`."},"hasPlayer":{"type":"boolean","description":"An interactive tab with the player exists for the song."},"tracks":{"type":"array","items":{"type":"object","required":["instrumentId","instrument","views"],"properties":{"instrumentId":{"type":"number","description":"General MIDI program number of the instrument; drums are 1024."},"instrument":{"type":"string","description":"Human-readable instrument name."},"name":{"type":"string","description":"Track name given by the author."},"tuning":{"type":"array","items":{"type":"number"},"description":"MIDI note numbers of the open strings, from the highest string."},"difficulty":{"type":"number","description":"Difficulty from 1 (easy) to 8 (hard). Levels for the `difficulty` filter: 1-2 easy, 3-5 intermediate, 6-8 hard."},"views":{"type":"number","description":"View count of this track."},"hash":{"type":"string","description":"Content hash of the track."}}},"description":"Tracks of the latest revision."},"defaultTrack":{"type":"number","description":"Index in `tracks` of the track that best matches the request: the most viewed track satisfying the `inst`, `tuning` and `difficulty` filters."},"popularTrack":{"type":"number","description":"Index in `tracks` of the most viewed track of any instrument."},"popularTrackGuitar":{"type":"number","description":"Index in `tracks` of the most viewed guitar track; absent when the song has none."},"popularTrackBass":{"type":"number","description":"Index in `tracks` of the most viewed bass track; absent when the song has none."},"popularTrackDrum":{"type":"number","description":"Index in `tracks` of the most viewed drum track; absent when the song has none."},"popularTrackVocals":{"type":"number","description":"Index in `tracks` of the most viewed vocal track; absent when the song has none."},"addedAt":{"type":"string"},"lastViewedAt":{"type":"string"},"totalViews":{"type":"number","description":"Views of the song; only with `stats=true`."},"guitarViews":{"type":"number","description":"Views of guitar tracks; only with `stats=true`."},"bassViews":{"type":"number","description":"Views of bass tracks; only with `stats=true`."},"drumsViews":{"type":"number","description":"Views of drum tracks; only with `stats=true`."},"favoritesCount":{"type":"number","description":"Number of users who added the song to favorites; only with `stats=true`."},"duplicateOf":{"type":"number","deprecated":true,"description":"Id of the song this record duplicates. Will be removed once the catalog is cleaned up; use `work.duplicateOf`."},"work":{"anyOf":[{"type":"object","required":["id","mainSongId","role","recording","tuning","duplicateOf"],"properties":{"id":{"type":"number","description":"The work: the tabs of one song by one artist."},"mainSongId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The work's main tab; `null` while undecided."},"role":{"anyOf":[{"anyOf":[{"type":"string","enum":["main"]},{"type":"string","enum":["copy"]},{"type":"string","enum":["variant"]},{"type":"string","enum":["part"]},{"type":"string","enum":["arrangement"]},{"type":"string","enum":["junk"]}]},{"type":"null"}],"description":"What the tab is within the work; `null` while undecided."},"recording":{"anyOf":[{"anyOf":[{"type":"string","enum":["album"]},{"type":"string","enum":["live"]},{"type":"string","enum":["demo"]},{"type":"string","enum":["cover"]},{"type":"string","enum":["unknown"]}]},{"type":"null"}],"description":"Which recording the tab transcribes; `null` while undecided."},"tuning":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The retuning the tab is in, e.g. `Drop D`; `null` for the recording's own tuning."},"duplicateOf":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Song id of the tab this one adds nothing over: a `copy` of the work's main tab (its notes are all in it, at the same pitch). Hiding it in a list that has that tab loses nothing."}}},{"type":"null"}],"description":"Only with `work=true`: the tab's work, `null` when the song is in none."}}},"description":"Matching songs: by text match first, then by popularity (or by date with `latest=true`)."},"hasMoreWithoutFilters":{"type":"boolean","description":"Only with `more=true`: more songs match the pattern without the track filters."},"additionalResultsCount":{"type":"number","description":"Only with `more=true`: estimated number of those extra songs."}}}}}}}}}}}