{"id":"agent-pitch-map","name":"Agent Pitch Map","description":"AI-navigable pitch map for notes, scales, chords, sound, and tab across piano and standard guitar.","version":"2026-06-28","audience":["human musicians learning piano/guitar/theory relationships","AI agents explaining note geography, scales, chords, and guitar tab options","teachers, songwriters, producers, and learners moving ideas between MIDI, piano, and guitar"],"principles":["read-only public API routes are safe for agents to call","musical pitch is represented as MIDI first and labels are derived","exact pitch, same note name, and theory membership are separate overlays","agent and recipe annotations are semantic overlay marks with selectors and roles","browser agents should prefer API routes and stable data attributes before visual inference"],"primaryHumanRoute":"https://www.agentpitchmap.com/","agentGuide":"https://www.agentpitchmap.com/agent","llmsTxt":"https://www.agentpitchmap.com/llms.txt","openapi":"https://www.agentpitchmap.com/openapi.json","endpoints":[{"method":"GET","path":"/api/map","description":"Resolve a note or MIDI pitch to piano keys, standard guitar positions, same-note-name matches, theory membership, and interval function.","example":"https://www.agentpitchmap.com/api/map?note=D4&root=C&scale=major&piano=49-key","sideEffects":"none"},{"method":"GET","path":"/api/voicings","description":"Discover playable standard-guitar chord voicings for a root and chord quality.","example":"https://www.agentpitchmap.com/api/voicings?root=C&chord=major","sideEffects":"none"},{"method":"GET","path":"/api/composer","description":"Return literature-informed composer moves from the current pitch state: circle neighbors, common tones, guide-tone pivots, chromatic mediants, and nearby guitar anchors.","example":"https://www.agentpitchmap.com/api/composer?note=G2&root=C&scale=major","sideEffects":"none"},{"method":"GET","path":"/api/scales","description":"Return the structured scale catalog with intervals, degrees, families, common chords, and characteristic tones.","example":"https://www.agentpitchmap.com/api/scales?family=jazz","sideEffects":"none"},{"method":"GET","path":"/api/scale-map","description":"Map a rooted scale to pitch classes, selected-note degree membership, and guitar anchors.","example":"https://www.agentpitchmap.com/api/scale-map?root=C&scale=lydian&note=G2","sideEffects":"none"},{"method":"GET","path":"/api/chord-scale","description":"Rank chord-scale choices for a chord in optional key context, including available tensions and guitar anchors.","example":"https://www.agentpitchmap.com/api/chord-scale?root=G&chord=dominant7&contextRoot=C","sideEffects":"none"},{"method":"GET","path":"/api/scales/containing","description":"Find rooted scales that contain arbitrary pitch material such as notes, chord tones, or riff fragments.","example":"https://www.agentpitchmap.com/api/scales/containing?notes=C,E,G,Bb","sideEffects":"none"},{"method":"GET","path":"/api/recipes/tab","description":"Generate a complete shareable beginner tab recipe with project JSON, ASCII tab, app URL, tab export URL, and semantic teaching overlays.","example":"https://www.agentpitchmap.com/api/recipes/tab?key=D&scale=naturalMinor&style=beginner-riff","sideEffects":"none"},{"method":"GET","path":"/api/project","description":"Return canonical Agent Pitch Map project JSON from query state or an encoded project URL parameter.","example":"https://www.agentpitchmap.com/api/project?note=D4&root=C&scale=major&piano=49-key","sideEffects":"none"},{"method":"GET","path":"/api/tab/export","description":"Export ASCII tab from an encoded read-only project state URL parameter.","example":"https://www.agentpitchmap.com/api/tab/export?project=<encoded-project-state>","sideEffects":"none"},{"method":"GET","path":"/api/capabilities","description":"Return this manifest as JSON for agent discovery.","example":"https://www.agentpitchmap.com/api/capabilities","sideEffects":"none"}],"safeAgentActions":["fetch /llms.txt","fetch /agent","fetch /openapi.json","fetch /api/map with a note, root, scale, chord, or piano preset","fetch /api/voicings with a root and chord quality","fetch /api/composer with a note, root, scale, chord, or layer for composition moves","fetch /api/scales for the scale catalog","fetch /api/scale-map for rooted scale degree and guitar-anchor data","fetch /api/chord-scale for chord-scale advice","fetch /api/scales/containing for scale discovery from notes or riffs","fetch /api/recipes/tab to generate a shareable tab example with semantic overlays","fetch /api/project for portable project JSON","fetch /api/tab/export with an encoded project for derived ASCII tab","click piano/fretboard controls using data-testid/data-note/data-midi/data-agent-role attributes"],"notYetSupported":["authenticated save/load across users","server-side tab project persistence","write-capable A2A or MCP task execution","sampled instrument playback","alternate tunings beyond standard guitar and capo logic"]}