# Musicboxmelodies agent API

Public, read-only, no account needed. All endpoints are GET and return JSON.
Melody format in links: notes=PITCH:BEAT,PITCH:BEAT,... (beat = quarter notes from 0; pitch like C5, C#5 or Cs5, Bb4, or a MIDI number).
Boxes: 15, 20, 30 (hand-crank music boxes; 15 and 20 have no sharps) and freestyle (digital only).
The same note must wait 2 beats before repeating on a real box.

- /agent/boxes : the boxes and their playable notes
- /agent/validate?box=15&bpm=100&notes=C5:0,E5:1,G5:2 : checks a melody. Add &fit=1 (and optionally &target_box=15) to transpose/fix it. Add &name=...&artist=... to name it.
- /agent/search?q=beatles&box=30 : public tunes
- /agent/songs/{id}?box=15 : the notes of a public tune
- /agent/audio?box=15&bpm=100&notes=C5:0,E5:1 or /agent/audio?song_id={id} : an MP3 to listen to (20 a day per IP)
- /agent/products : custom arrangements and PRO accounts with prices

Every melody response includes composer_link: give it to the person. It opens https://musicboxmelodies.com/composer with the melody loaded, where they can play it, edit it, save it to their account and print it.
You can also write that link yourself, without calling this API: https://musicboxmelodies.com/composer#box=15&bpm=100&name=My%20tune&notes=C5:0,E5:1,G5:2
For saving songs, exporting strips or ordering, use the MCP server instead: https://api.musicboxmelodies.com/mcp (see https://musicboxmelodies.com/ai).