The five calls

Everything THIRI does is reachable through five calls. They are the same five whether you reach them over REST at chords.thiri.ai or as tools in the MCP server. This chapter is the musician’s reading of each one; the field-by-field reference is on the API page.

analyze: what is this chord doing?

Give it a symbol and a key. It returns the chord’s parts (root, quality, intervals, notes) and its job in the key: scale degree, roman numeral, function, and whether it is diatonic or borrowed.

Ask for Dm7b5 in C and you get iiø7, “predominant (borrowed)”, with Locrian and Locrian ♮2 as the primary scales and the altered and half-whole diminished scales as secondary colours. That is the answer a good theory teacher gives, and it is the same answer every time.

resolve: which notes, exactly?

Give it a symbol. It spells the chord: note names, interval names, semitones from the root, MIDI numbers, and frequencies in hertz at the default octave. C13 comes back as C E G B♭ D A, MIDI 60 64 67 70 74 81, with Mixolydian and Lydian dominant as the scales that fit.

This is the call a synth, a notation program or a tuner needs. There is nothing to interpret; the numbers go straight into a note-on.

voicing: how should an instrument play it?

Give it a symbol, a style, and optionally the previous chord’s notes. It returns an instrument-ready voicing and a voice-leading score. The styles are the ones arrangers use: rootless (the default), Bill Evans rootless, shell, triad, pad, guide tones (both, or either one), drop-2 and drop-3. An unknown style name falls back to the default without complaint, so read the style echoed in the response.

With the previous voicing supplied, THIRI minimises motion between chords. C13 after a Gm7 voiced G3 B♭3 D4 F4 comes back rootless as E3 A3 B♭3: the third and seventh stay as guide tones, the thirteenth takes the fifth’s seat, and the fifth and ninth are listed as omitted so you know exactly what was left out.

reharmonize: what else could this be?

Give it a progression and a key. It returns alternatives, each named by technique, with the exact changes and a one-sentence explanation. For Gm7 C7 Fmaj7 in F the first alternative is the tritone substitution, Gm7 G♭7 Fmaj7: the dominant a tritone away shares the guide tones and slides the bass down a half step into the target. Seven more follow: a ii–V insertion, modal interchange, secondary dominants, a chain of dominants, Coltrane changes, the backdoor dominant.

The explanations are part of the output on purpose. An agent that shows its reasoning is one a musician can argue with.

conduct: make it a band

Give it a sentence. “4-bar swung loop in F for piano, bass and drums” returns a conductor object (tempo 80, key F, 4/4, four bars, swing 0.55, an energy curve), four lanes of note events (harmony, pattern, bass, drums) at 480 ticks per quarter, a lead sheet (| Gm9 | C13 | Fmaj9 | Fmaj9 |), and a complete multi-track MIDI file encoded in base64.

The engine is pure JavaScript. It decides; something else plays. On this site the Conductor instrument renders the lanes with Csound in the browser. In a DAW you drop the MIDI on four tracks.

What every response carries

• A JSON object you can snapshot. There is no sampling, so a golden file written today is still correct tomorrow unless the changelog says the grid changed.
• Two headers, X-Quota-Limit and X-Quota-Used, so a client always knows where it stands in the month.
• On failure, a stable error code and a human message. The errors page lists them.

What the engine will not do

It will not guess a chord it cannot parse; it returns invalid_chord and the symbol it choked on. It will not accept a mode as a key; ask for B♭ Lydian through the parent key of F and the chord you want. And it will not render audio: that is the job of whatever you plug it into, which is the subject of the next part.