Music Theory API (v0.0.1)

The Music Theory API is currently a toy project for me to both practice my developer skills and demonstrate technical writing knowledge around APIs, SaaS, DevOps, and InfoSec. However, in the coming months and years, I hope to turn it into something truly useful that can provide answers to a vast array of music theory questions, and will be able to generate working examples in standard formats such as MusicXML and MIDI.

The API currently provides minimal functionality for a few basic music theory questions, but since this is primarily a demonstration of technical writing at the moment, the documentation covers everything necessary for a development team to work on and support the API as well as how a client would consume it.

Currently, the API allows you to do the following:

• Get the notes of a root-position chord (major, minor, augmented, or diminished)
• Get a few common chord progressions for a key (both Roman numerals and note spellings / pitch classes)
• Get notes for a scale (major, minor, or harmonic minor)
• Get diatonic chords for a scale (major, minor, or harmonic minor)

Eventually, much more functionality will be added, including:

• Output in MusicXML and MIDI formats
• More chord types (inversions, suspensions, 7th, 9th, 11th, 13th, etc.)
• More scales (whole tone, pentatonic, hexatonic, octatonic, modes, etc.)
• More progressions (circle of fifths, secondary dominants, etc.)
• More music theory concepts (counterpoint, voice leading, etc.)

The reference documentation is generated from the source code following the OpenAPI 3.0 specification and is beautifully rendered using redocusaurus (a Redoc wrapper for Docusaurus).

In addition to the reference documentation, this page contains a Quick Start section to help you get started quickly.

The following sections are also available:

• Authentication
• SDK

We will run through the process of creating a user, obtaining a JWT token, and making calls to the API.

To start using the API, you must register using an email address and password.

Run the following command, using your own email and password, to register a new user:

curl 'https://musictheoryapi.com/api/v0/auth/register' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "Email": "user@example.com",
         "Password": "StrongPassword123"
     }'

If all is well, you will receive a 201 Created response with a message saying that the user was created successfully.

If you get a 500 error, try again a few times. Azure can be unreliable at times.

Once registered, you need to obtain a JWT token to make further requests.

Run the following command, using your own email and password, to obtain a JWT token:

curl 'https://musictheoryapi.com/api/v0/auth/login' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "Email": "user@example.com",
         "Password": "StrongPassword123"
     }'

If successful, you will receive a 200 OK response with a JWT token in the token field. This token is valid for one hour and must be included in the Authorization header of all subsequent requests.

Getting the notes of a chord

First, we will get the notes of a B augmented triad. The notes for this are B, D♯, and F𝄪. To get past the burden of special characters and ambiguous URLs, we spell these things out when using the API, but in some instances (e.g., scales) it is also capable of returning a stringified response (in the case of scales) such as "B, D#, F##".

To get the notes of a chord (B augmented triad in this case), run the following command using your own token:

curl 'https://musictheoryapi.com/api/v0/chords/b/augmented' \
     --header 'Authorization: Bearer {token}'

(to be continued...)