{"openapi":"3.1.0","info":{"title":"Agent Pitch Map Agent API","version":"2026-06-28","description":"AI-navigable pitch map for notes, scales, chords, sound, and tab across piano and standard guitar."},"servers":[{"url":"https://www.agentpitchmap.com"}],"paths":{"/api/map":{"get":{"operationId":"getPitchMap","summary":"Map a note to piano, guitar, and theory positions","parameters":[{"name":"note","in":"query","schema":{"type":"string","examples":["D4","Bb3","C#"]},"description":"Note name with optional octave. Without octave, octave 4 is used for exact pitch and the pitch class is still mapped across octaves."},{"name":"midi","in":"query","schema":{"type":"integer","minimum":0,"maximum":127,"examples":[62]},"description":"MIDI pitch. Used when note is omitted."},{"name":"root","in":"query","schema":{"type":"string","examples":["C","F#","Bb"]},"description":"Theory root."},{"name":"layer","in":"query","schema":{"type":"string","enum":["scale","chord"],"default":"scale"}},{"name":"scale","in":"query","schema":{"type":"string","examples":["major","dorian","lydianDominant","altered","blues"],"default":"major"}},{"name":"chord","in":"query","schema":{"type":"string","enum":["major","minor","diminished","dominant7","major7","minor7"],"default":"major"}},{"name":"piano","in":"query","schema":{"type":"string","enum":["25-key","49-key","61-key","88-key"],"default":"49-key"}}],"responses":{"200":{"description":"Pitch map with exact and same-note-name positions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PitchMap"}}}},"400":{"description":"Invalid note or query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/voicings":{"get":{"operationId":"getGuitarVoicings","summary":"Discover playable guitar chord voicings","parameters":[{"name":"root","in":"query","schema":{"type":"string","examples":["C","F#","Bb"]},"description":"Chord root."},{"name":"chord","in":"query","schema":{"type":"string","enum":["major","minor","diminished","dominant7","major7","minor7"],"default":"major"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":24,"default":12}}],"responses":{"200":{"description":"Playable standard-guitar voicings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoicingResult"}}}},"400":{"description":"Invalid root or chord.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/composer":{"get":{"operationId":"getComposerBridge","summary":"Suggest composition moves from the current pitch state","parameters":[{"name":"note","in":"query","schema":{"type":"string","examples":["G2","D4","Bb3"]},"description":"Selected note with optional octave. Used for the current state label."},{"name":"midi","in":"query","schema":{"type":"integer","minimum":0,"maximum":127,"examples":[43]},"description":"Selected MIDI pitch. Used when note is omitted."},{"name":"root","in":"query","schema":{"type":"string","examples":["C","F#","Bb"]},"description":"Current tonal center."},{"name":"layer","in":"query","schema":{"type":"string","enum":["scale","chord"],"default":"scale"}},{"name":"scale","in":"query","schema":{"type":"string","examples":["major","dorian","lydianDominant","altered","blues"],"default":"major"}},{"name":"chord","in":"query","schema":{"type":"string","enum":["major","minor","diminished","dominant7","major7","minor7"],"default":"major"}}],"responses":{"200":{"description":"Composer bridge with circle context and structured move suggestions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComposerBridge"}}}},"400":{"description":"Invalid note or query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/scales":{"get":{"operationId":"listScales","summary":"List the structured scale catalog","parameters":[{"name":"family","in":"query","schema":{"type":"string","enum":["major","minor","modal","pentatonic","blues","jazz","symmetric","synthetic"]}}],"responses":{"200":{"description":"Scale definitions with intervals, degrees, and theory metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScaleCatalog"}}}},"400":{"description":"Invalid scale family.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/scale-map":{"get":{"operationId":"getScaleMap","summary":"Map a rooted scale to notes, degree membership, and guitar anchors","parameters":[{"name":"root","in":"query","schema":{"type":"string","examples":["C","F#","Bb"]}},{"name":"scale","in":"query","schema":{"type":"string","examples":["major","lydian","altered"]}},{"name":"note","in":"query","schema":{"type":"string","examples":["G2","Bb3"]}},{"name":"midi","in":"query","schema":{"type":"integer","minimum":0,"maximum":127}}],"responses":{"200":{"description":"Rooted scale map.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScaleMap"}}}},"400":{"description":"Invalid root, scale, or note.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/chord-scale":{"get":{"operationId":"getChordScaleAdvisor","summary":"Rank chord-scale choices for a chord in optional key context","parameters":[{"name":"root","in":"query","schema":{"type":"string","examples":["G","C","Bb"]},"description":"Chord root."},{"name":"chord","in":"query","schema":{"type":"string","enum":["major","minor","diminished","dominant7","major7","minor7"],"default":"major"}},{"name":"contextRoot","in":"query","schema":{"type":"string","examples":["C"]},"description":"Optional key or tonal-center root."},{"name":"contextScale","in":"query","schema":{"type":"string","examples":["major","harmonicMinor"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":16,"default":8}}],"responses":{"200":{"description":"Chord-scale candidates ranked by fit and context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChordScaleAdvisor"}}}},"400":{"description":"Invalid chord-scale query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/scales/containing":{"get":{"operationId":"findScalesContaining","summary":"Find scales containing supplied pitch material","parameters":[{"name":"notes","in":"query","required":true,"schema":{"type":"string","examples":["C,E,G,Bb","60,64,67"]}},{"name":"root","in":"query","schema":{"type":"string","examples":["C"]},"description":"Optional root filter."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":48,"default":24}}],"responses":{"200":{"description":"Scale matches containing all supplied pitch classes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContainingScales"}}}},"400":{"description":"Invalid notes query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/recipes/tab":{"get":{"operationId":"buildTabRecipe","summary":"Generate a shareable tab recipe with semantic overlays","parameters":[{"name":"key","in":"query","schema":{"type":"string","default":"D","examples":["D","A","F#"]},"description":"Root/key for the generated tab recipe."},{"name":"scale","in":"query","schema":{"type":"string","default":"naturalMinor","examples":["naturalMinor","major","dorian"]}},{"name":"style","in":"query","schema":{"type":"string","default":"beginner-riff","enum":["beginner-riff"]}},{"name":"difficulty","in":"query","schema":{"type":"string","default":"easy","enum":["easy"]}}],"responses":{"200":{"description":"Generated tab recipe with app URL, ASCII tab, project state, and semantic overlay marks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TabRecipe"}}}},"400":{"description":"Unsupported recipe input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/project":{"get":{"operationId":"getProjectState","summary":"Return portable Agent Pitch Map project JSON","parameters":[{"name":"project","in":"query","schema":{"type":"string"},"description":"Optional encoded project state from a share URL."}],"responses":{"200":{"description":"Portable project state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectState"}}}},"400":{"description":"Invalid project state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/tab/export":{"get":{"operationId":"exportTabAscii","summary":"Export ASCII tab from encoded project state","parameters":[{"name":"project","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ASCII tab derived from structured tab events.","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Invalid or missing project state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/capabilities":{"get":{"operationId":"getCapabilities","summary":"Get agent-facing tool manifest","responses":{"200":{"description":"Agent-facing capabilities and route list."}}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"PitchMap":{"type":"object","required":["apiVersion","selected","piano","fretboard","theory","examples"],"properties":{"apiVersion":{"type":"string"},"selected":{"type":"object"},"piano":{"type":"object"},"fretboard":{"type":"object"},"theory":{"type":"object"},"examples":{"type":"object"}}},"ProjectState":{"type":"object","required":["app","version","selectedPitch","theory","mapping","transport","tabProject"],"properties":{"app":{"type":"string"},"version":{"type":"string"},"selectedPitch":{"type":"object"},"theory":{"type":"object"},"mapping":{"type":"object"},"transport":{"type":"object"},"tabProject":{"type":"object"},"overlays":{"type":"array","items":{"type":"object"},"description":"Semantic teaching overlays with role-based marks and selectors."}}},"TabRecipe":{"type":"object","required":["appUrl","asciiTab","asciiTabUrl","project","recipe"],"properties":{"agentUsage":{"type":"array","items":{"type":"string"}},"appUrl":{"type":"string"},"asciiTab":{"type":"string"},"asciiTabUrl":{"type":"string"},"explanation":{"type":"string"},"overlays":{"type":"array","items":{"type":"object"}},"project":{"$ref":"#/components/schemas/ProjectState"},"recipe":{"type":"object"}}},"VoicingResult":{"type":"object","required":["apiVersion","root","chord","voicings"],"properties":{"apiVersion":{"type":"string"},"root":{"type":"string"},"chord":{"type":"string"},"voicings":{"type":"array","items":{"type":"object"}}}},"ComposerBridge":{"type":"object","required":["apiVersion","circle","current","moves","researchBasis"],"properties":{"apiVersion":{"type":"string"},"circle":{"type":"object"},"current":{"type":"object"},"moves":{"type":"array","items":{"type":"object","required":["id","title","relation","targetRoot","targetChord","sharedPitchClasses","guitarAnchors"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"relation":{"type":"string"},"targetRoot":{"type":"string"},"targetChord":{"type":"string"},"sharedPitchClasses":{"type":"array","items":{"type":"string"}},"guitarAnchors":{"type":"array","items":{"type":"object"}}}}},"researchBasis":{"type":"array","items":{"type":"string"}}}},"ScaleCatalog":{"type":"object","required":["apiVersion","count","families","scales"],"properties":{"apiVersion":{"type":"string"},"count":{"type":"integer"},"families":{"type":"array","items":{"type":"string"}},"scales":{"type":"array","items":{"type":"object"}}}},"ScaleMap":{"type":"object","required":["apiVersion","id","name","root","family","pitchClasses","guitarAnchors"],"properties":{"apiVersion":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"root":{"type":"string"},"family":{"type":"string"},"pitchClasses":{"type":"array","items":{"type":"object"}},"selected":{"type":"object"},"guitarAnchors":{"type":"array","items":{"type":"object"}}}},"ChordScaleAdvisor":{"type":"object","required":["apiVersion","chord","candidates"],"properties":{"apiVersion":{"type":"string"},"chord":{"type":"object"},"context":{"type":"object"},"candidates":{"type":"array","items":{"type":"object"}}}},"ContainingScales":{"type":"object","required":["apiVersion","matches"],"properties":{"apiVersion":{"type":"string"},"matches":{"type":"array","items":{"type":"object"}}}}}}}