hooktheory.com APIwww.hooktheory.com ↗
Search 65,000+ songs in Hooktheory's TheoryTab database. Retrieve chords, melody notes, keys, tempos, and time signatures by song section.
curl -X GET 'https://api.parse.bot/scraper/6b249d06-c1b6-4e17-ad83-675d92275ddc/search_songs?limit=3&query=let+it+be' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for songs in the TheoryTab database by keyword. Returns matching songs with basic chord information, key, and section type. Results are paginated via offset and limit.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of results to return (max 200) |
| queryrequired | string | Search keyword (song name, artist, etc.) |
| offset | integer | Offset for pagination |
{
"type": "object",
"fields": {
"limit": "integer, max results requested",
"query": "string, the search query echoed back",
"offset": "integer, current pagination offset",
"results": "array of objects with id, song, artist, section, key, youtube_id, chords_absolute, chords_relative",
"total_hits": "integer, total number of matching results"
},
"sample": {
"data": {
"limit": 3,
"query": "let it be",
"offset": 0,
"results": [
{
"id": 703,
"key": "C major",
"song": "Let It Be",
"artist": "The Beatles",
"section": "Verse",
"youtube_id": "CGj85pVzRJs",
"chords_absolute": "qqCqqGqqAmqqFqqDmqqCqqGqqFqqCqqDmqqCqq",
"chords_relative": "qqIqqVqqwjqqIVqqjjqqIqqVqqIVqqIqqjjqqIqq"
}
],
"total_hits": 3
},
"status": "success"
}
}About the hooktheory.com API
The Hooktheory TheoryTab API gives programmatic access to music theory data for over 65,000 songs across 3 endpoints. The search_songs endpoint returns chord and key information for matching tracks, while get_song_sections lists every section (verse, chorus, bridge, etc.) and get_section_notes delivers the full breakdown: chords with root, type, and inversion, melody notes with scale degree and octave, time signatures, and BPM data.
Search and Navigation
The search_songs endpoint accepts a query string (song name, artist name, or any keyword) and returns an array of matching results. Each result includes the song and artist names, a section label, key, and both absolute and relative chord representations. Pagination is controlled via limit (up to 200) and offset, and the total_hits field tells you the full match count for multi-page traversal.
Retrieving Song Sections
Once you have a target song, get_song_sections maps the artist and song URL slugs (e.g. the-beatles, let-it-be) to a list of sections. Each entry in the sections array carries a section_id and a human-readable section_name. The endpoint also returns the canonical TheoryTab URL for the song. These section IDs are the required input for the next step.
Full Music Theory Detail
Passing a section_id to get_section_notes returns the densest data in the API. The chords array contains objects with root, type, inversion, beat, duration, and harmony annotations including applied, adds, omits, alterations, suspensions, and borrowed. The notes array represents the melody line, with each note carrying scale_degree, octave, beat, duration, and an is_rest flag. Key changes are tracked in the keys array (each entry has beat, tonic, and scale), tempo shifts in tempos (with bpm, swingFactor, and swingBeat), and meter changes in meters (with numBeats and beatUnit). A youtube object links to a synced video clip when available.
Coverage and Structure
Data is organized by section rather than by full song, which reflects how TheoryTab's database is structured — different sections of the same song can have different keys, tempos, and meters. The end_beat field on get_section_notes responses marks the total length of the section in beats, useful for sequencing or rendering.
- Build a chord progression explorer that searches songs by artist and displays relative chords for music students
- Analyze borrowed chords and modal mixture across a genre by querying
chords.borrowedfields on section data - Generate MIDI or sheet music from melody
notesarrays including scale degree, octave, and duration - Study how key signatures change mid-song using the beat-stamped
keysarray fromget_section_notes - Create a tempo and time signature database by aggregating
tempos.bpmandmeters.numBeatsacross thousands of songs - Map YouTube sync windows to specific song sections using
youtube.sync_startandsync_endfor annotated playback - Compare verse versus chorus harmony for a catalog of songs by fetching all sections and diffing their chord arrays
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Hooktheory have an official developer API?+
What does `get_section_notes` return for chords beyond basic root and type?+
root, type, inversion, beat, and duration, plus harmony extensions: applied (secondary dominant target), adds, omits, alterations, suspensions, and borrowed (modal mixture). The is_rest flag marks beats with no chord. This level of detail is only available through get_section_notes using a section_id obtained from get_song_sections.Can I retrieve audio files or sheet music PDFs for a song?+
Is artist or song metadata like genre, release year, or album available?+
song, artist, section, key, and YouTube ID from search results, but does not expose genre, release year, album, or chart data. You can fork the API on Parse and revise it to add an endpoint pulling from a music metadata source to enrich results.How does section-based pagination work, and are there limits on search results?+
search_songs endpoint supports offset and limit (maximum 200 per request) for paging through results. The total_hits field in the response gives the full match count so you can calculate how many pages to fetch. Section retrieval via get_song_sections returns all sections for a song in one response with no pagination.