{"id":"agent-pitch-map","name":"Agent Pitch Map","description":"AI-navigable pitch decision engine for piano-to-guitar mapping, ranked playable routes, scales, chords, sound, and tab.","version":"2026-07-01","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","examples":"https://www.agentpitchmap.com/examples","llmsTxt":"https://www.agentpitchmap.com/llms.txt","llmsFullTxt":"https://www.agentpitchmap.com/llms-full.txt","openapi":"https://www.agentpitchmap.com/openapi.json","workflows":[{"id":"note-translation","task":"Map C4 to piano identity, guitar positions, interval role, and proof fields.","endpoint":"https://www.agentpitchmap.com/api/map?note=C4&root=C&scale=major&piano=61-key","proof":["selected.midi","selected.frequencyHz","fretboard.exactPositions","theory.interval"]},{"id":"position-ranking","task":"Rank C4 as playable standard-guitar single-note positions with exact-pitch, hand-window, theory, and fingering proof.","endpoint":"https://www.agentpitchmap.com/api/positions?note=C4&root=C&scale=major&position=first&maxFret=12","proof":["bestPosition.string","bestPosition.fret","bestPosition.proof","bestPosition.fingering","positions[].cost","appUrl","compactUrl"]},{"id":"route-planning","task":"Rank a short melody as playable first-position guitar decisions with tab-ready events, optionally preserving a supplied guitar shape hand window.","endpoint":"https://www.agentpitchmap.com/api/route?notes=F4,G4,A4&root=F&scale=major&position=first&maxFret=12&frets=1,3,3,2,1,1","proof":["routes[0].efficiencyScore","routes[0].proof","routes[0].fingering","routes[0].tabNotes","shapeContext.barres[]","shapeContext.proof","singleNoteFallback.exactBestPosition","singleNoteFallback.pitchClassBestPosition","tabRenderProof","tabRenderRequest","POST tabRenderRequest.path -> eventProof[].stringFretMatchesMidi","project.tabProject.measures[0].notes","compactUrl"],"procedure":["Inspect live route cards with data-agent-role=\"route-tab-render-proof-target\", data-agent-role=\"route-tab-render-request\", data-agent-role=\"render-route-tab-request\", data-agent-role=\"route-render-proof-link\", and data-agent-role=\"route-tab-render-response-proof\".","Inspect route ergonomics with data-agent-role=\"route-fingering-proof\" and data-agent-role=\"route-fingering-path\".","Read shapeContext, routes[0].fingering, tabRenderProof, tabRenderRequest.path, tabRenderRequest.body, and routes[0].tabNotes from the route response.","Confirm tabRenderProof.expectedEventCount === routes[0].tabNotes.length and tabRenderProof.expectedEventProof === \"eventProof[].stringFretMatchesMidi\" before posting.","POST tabRenderRequest.path with tabRenderRequest.body.","Verify eventProof[].stringFretMatchesMidi === true and project.tabProject.measures[0].notes.length === routes[0].tabNotes.length before reporting rendered tab as canonical."]},{"id":"voice-leading-resolution","task":"Rank three G7 to Cmaj7 guitar resolutions by common-tone, guide-tone, and movement proof.","endpoint":"https://www.agentpitchmap.com/api/voice-leading?fromRoot=G&fromChord=dominant7&toRoot=C&toChord=major7&limit=3","proof":["transitions[0..2]","transitions[].proof","transitionLinks[]","asciiTab"]},{"id":"shape-identification","task":"Identify a standard-guitar fret shape as ranked chord hypotheses with omissions, extra tones, bass role proof, barre proof, and playable next moves.","endpoint":"https://www.agentpitchmap.com/api/identify?frets=1,3,3,2,1,1&contextRoot=F&limit=5","proof":["candidates[0].name","candidates[].missingPitchClasses","candidates[].bass","barres[]","playability.requiresBarre","barreDisplayProof","candidates[].nextMoves"]},{"id":"constrained-riff-composition","task":"Compile a D Dorian two-measure guitar idea into ProjectState, tab, overlays, and share URLs.","endpoint":"https://www.agentpitchmap.com/api/compose?key=D&scale=dorian&chord=minor7&motif=dorian-compass&position=first&bars=2","proof":["project.tabProject","asciiTab","overlays","compactUrl"]},{"id":"practice-drill","task":"Compile a C guide-tone practice loop into MIDI targets, route-ranked tab events, pulse timing, and share URLs.","endpoint":"https://www.agentpitchmap.com/api/practice/drill?target=guide-tones&key=C&level=beginner&position=first","proof":["targets[]","pulse[]","routePlan.routes[0].proof","projectState","compactUrl"]},{"id":"practice-position-drill","task":"Return drillable exact string/fret targets from the ranked practice route so a player can follow the best guitar position sequence.","endpoint":"https://www.agentpitchmap.com/api/practice/drill?target=guide-tones&key=C&level=beginner&position=first&maxFret=7","proof":["positionDrill[].string","positionDrill[].fret","positionDrill[].startBeat","positionDrill[].targetId","positionTabPacket.tabNotes[]","positionTabPacket.tabInsertion","positionTabPacket.tabRenderRequest","routePlan.routes[0].proof.handWindow"]},{"id":"tracker-synth-pattern","task":"Compile practice, route, or compose output into tracker rows, synth instruments, scheduled playback events, tab events, and proof.","endpoint":"https://www.agentpitchmap.com/api/tracker/pattern?source=practice&target=guide-tones&key=C&position=first&maxFret=7","proof":["tracker.patterns[0].cells[]","tracker.instruments[]","rendered.scheduledEvents[]","rendered.tabNotes[]","rendered.proof.eventProof[].stringFretMatchesMidi","project.tracker","compactUrl"]}],"endpoints":[{"method":"GET","path":"/api/health","description":"Return service status and the public agent discovery routes.","example":"https://www.agentpitchmap.com/api/health","sideEffects":"none"},{"method":"GET","path":"/api/note","description":"Resolve note or MIDI input to canonical MIDI, note name, octave, frequency, and map URL.","example":"https://www.agentpitchmap.com/api/note?note=C4","sideEffects":"none"},{"method":"GET","path":"/api/fretboard","description":"Return standard-guitar string/fret coordinates, optionally filtered to an exact note or pitch class.","example":"https://www.agentpitchmap.com/api/fretboard?note=C&maxFret=12","sideEffects":"none"},{"method":"GET","path":"/api/positions","description":"Rank playable single-note standard-guitar positions with exact-pitch, hand-window, theory-membership, fingering, tab-event, and share URL proof.","example":"https://www.agentpitchmap.com/api/positions?note=C4&root=C&scale=major&position=first&maxFret=12","sideEffects":"none"},{"method":"GET","path":"/api/chord","description":"Stable chord endpoint alias for optimized standard-guitar voicings.","example":"https://www.agentpitchmap.com/api/chord?root=C&chord=major&limit=3","sideEffects":"none"},{"method":"GET","path":"/api/identify","description":"Identify a standard-guitar fret shape as ranked chord hypotheses with omitted-tone, extra-tone, duplicate, bass-role, barre, and key-context proof.","example":"https://www.agentpitchmap.com/api/identify?frets=1,3,3,2,1,1&contextRoot=F&limit=5","sideEffects":"none"},{"method":"GET","path":"/api/practice/drill","description":"Compile a read-only practice loop into MIDI targets, count-in/loop pulse events, ranked guitar routes, drillable string/fret targets, tab events, ASCII tab, and share URLs.","example":"https://www.agentpitchmap.com/api/practice/drill?target=guide-tones&key=C&level=beginner&position=first","sideEffects":"none"},{"method":"GET","path":"/api/tracker/pattern","description":"Compile practice, route, or compose constraints into TrackerProject rows, synth instruments, scheduled events, structured tab, ProjectState, URLs, and proof.","example":"https://www.agentpitchmap.com/api/tracker/pattern?source=practice&target=guide-tones&key=C&position=first&maxFret=7","sideEffects":"none"},{"method":"POST","path":"/api/tracker/render","description":"Render a supplied TrackerProject into scheduled playback events, structured tab, ASCII tab, ProjectState, URLs, and event proof.","example":"https://www.agentpitchmap.com/api/tracker/render","sideEffects":"none"},{"method":"GET","path":"/api/tracker/instruments","description":"Return the built-in Tracker Synth patch catalog with engine, role, envelope, and browser-playback proof.","example":"https://www.agentpitchmap.com/api/tracker/instruments","sideEffects":"none"},{"method":"GET","path":"/api/tracker/example","description":"Return a deterministic Tracker Synth example for smoke tests, agents, and first-use inspection.","example":"https://www.agentpitchmap.com/api/tracker/example","sideEffects":"none"},{"method":"GET","path":"/api/scale","description":"Stable scale endpoint alias for rooted scale maps and selected-note membership.","example":"https://www.agentpitchmap.com/api/scale?root=C&scale=lydian&note=G2","sideEffects":"none"},{"method":"GET","path":"/api/map","description":"Resolve a note, MIDI pitch, or acoustic frequency to piano keys, standard guitar positions, same-note-name matches, theory membership, interval targets, and theoretical fret coordinates.","example":"https://www.agentpitchmap.com/api/map?frequencyHz=195.998&intervalSemitones=7&scaleLengthIn=25.5","sideEffects":"none"},{"method":"GET","path":"/api/voicings","description":"Discover and optimize playable standard-guitar chord voicings with chord-tone, barre display, and fingering proof.","example":"https://www.agentpitchmap.com/api/voicings?root=C&chord=major","sideEffects":"none"},{"method":"GET","path":"/api/route","description":"Rank playable guitar routes for notes or pitch-class sequences, including optional shapeContext from a supplied six-string fret shape, fret movement, string movement, span, theory membership proof, tab events, and share URLs.","example":"https://www.agentpitchmap.com/api/route?notes=F4,G4,A4&root=F&scale=major&position=first&frets=1,3,3,2,1,1","sideEffects":"none"},{"method":"GET","path":"/api/voice-leading","description":"Rank playable guitar chord-to-chord transitions with top-N options, common-tone, guide-tone, fret-motion, voice-motion, tab-event, and share URL proof.","example":"https://www.agentpitchmap.com/api/voice-leading?fromRoot=G&fromChord=dominant7&toRoot=C&toChord=major7&limit=3","sideEffects":"none"},{"method":"GET","path":"/api/formal-proof","description":"Formalize supported natural-language music-combinatorics problems and prove them by finite exhaustive check over the MIDI-backed model.","example":"https://www.agentpitchmap.com/api/formal-proof?problem=Prove%20there%20exists%20a%20playable%20C%20major%20triad%20voicing%20on%20standard%20guitar%20within%20span%204","sideEffects":"none"},{"method":"GET","path":"/api/extremal-search","description":"Search for cap-set-style extremal constructions in pitch-class or F_3 finite-field spaces and return independently verifiable certificates.","example":"https://www.agentpitchmap.com/api/extremal-search?space=pitch-class&modulus=12","sideEffects":"none"},{"method":"GET","path":"/api/geometry-proof","description":"Solve supported natural-language Euclidean geometry proof schemas with analytic/vector certificates and human-readable proof steps.","example":"https://www.agentpitchmap.com/api/geometry-proof?problem=In%20triangle%20ABC,%20M%20moves%20on%20AB%20with%20AM:MB=1:1%20and%20N%20moves%20on%20AC%20with%20AN:NC=1:1.%20Prove%20MN%20is%20parallel%20to%20BC","sideEffects":"none"},{"method":"GET","path":"/api/proof-repair","description":"Diagnose a supported failed olympiad-style proof attempt, repair the core invariant, and return a minimal formal certificate.","example":"https://www.agentpitchmap.com/api/proof-repair?problem=An%208x8%20chessboard%20has%20two%20opposite%20corners%20removed.%20Can%20it%20be%20tiled%20by%2031%20dominoes?&attempt=The%20area%20is%2062,%20so%2031%20dominoes%20should%20tile%20it.","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/compose","description":"Generate a complete read-only composition project from musical constraints, including ProjectState, ASCII tab, app URL, compact URL, and semantic overlays.","example":"https://www.agentpitchmap.com/api/compose?key=D&scale=dorian&chord=minor7&motif=dorian-compass","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/project/compact","description":"Return a compressed zproject token and compact workbench URL for a project or query-derived state.","example":"https://www.agentpitchmap.com/api/project/compact?project=<encoded-project-state>","sideEffects":"none"},{"method":"POST","path":"/api/tab","description":"Generate ASCII tab and canonical ProjectState from structured MIDI/string/fret tab events.","example":"https://www.agentpitchmap.com/api/tab","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":"POST","path":"/api/project/render","description":"Render a supplied ProjectState into ASCII tab, full workbench URL, compact URL, and render proof.","example":"https://www.agentpitchmap.com/api/project/render","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 /llms-full.txt","fetch /agent","fetch /examples","fetch /openapi.json","fetch /api/health to confirm the public discovery routes","fetch /api/note for canonical note/MIDI/frequency conversion","fetch /api/fretboard for standard-guitar coordinate maps","fetch /api/positions to rank single-note guitar positions by hand window, exact-pitch preservation, and fingering proof","fetch /api/map with a note, MIDI value, frequencyHz, intervalSemitones, scaleLengthIn, root, scale, chord, or piano preset","fetch /api/chord as a stable alias for guitar chord voicing selection","fetch /api/identify with a six-string fret shape to rank chord names, omitted tones, extra tones, bass role, barre proof, and playable next moves","fetch /api/voicings with a root and chord quality","fetch /api/route with notes and constraints to rank playable guitar paths with proof, single-note exact-vs-pitch-class comparison, and tab events","fetch /api/voice-leading to rank guitar chord transitions by common tones, guide tones, and movement proof","fetch /api/practice/drill to compile read-only loopable practice targets with route proof, drillable string/fret targets, and tab events","fetch /api/tracker/pattern to compile practice, route, or compose output into tracker rows, synth instruments, tab events, playback schedule, and proof","POST /api/tracker/render with TrackerProject to derive scheduled events, structured tab, ASCII tab, ProjectState, and event proof","fetch /api/formal-proof with a supported natural-language finite music-combinatorics problem","fetch /api/extremal-search for verified cap-set-style lower-bound constructions","fetch /api/geometry-proof for supported natural-language Euclidean geometry proofs","fetch /api/proof-repair to diagnose and repair supported failed invariant proof attempts","fetch /api/composer with a note, root, scale, chord, or layer for composition moves","fetch /api/compose with key, scale, chord, context, and motif constraints for a complete read-only composition project","fetch /api/scales for the scale catalog","fetch /api/scale-map for rooted scale degree and guitar-anchor data","fetch /api/scale as a stable alias for rooted scale maps","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/project/compact to produce compressed zproject URLs","POST /api/project/render with ProjectState to derive ASCII tab and share URLs","POST /api/tab with structured note/string/fret events to derive ASCII tab and ProjectState","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"]}