# Music Theory API
> Music-theory maths as an API, computed locally and deterministically over the twelve-tone chromatic scale. The interval endpoint gives the number of semitones and the interval name between two notes — C to G is seven semitones, a perfect fifth. The transpose endpoint shifts one or more notes up or down by a number of semitones, so C E G transposed up seven becomes G B D and a negative value transposes down. The chord endpoint returns the notes of a chord from a root and a type — major, minor, diminished, augmented, the sevenths (major7, minor7, dominant7, diminished7, half-diminished7), sixths, suspended, add9, ninth and power chords — so C major is C E G and C7 is C E G B♭. The scale endpoint returns the notes of a scale from a root and a mode — the major and three minor scales, the seven church modes, the major and minor pentatonics, blues, whole-tone and chromatic — so C major is C D E F G A B and A natural-minor is A B C D E F G. Notes use C, C#, D♭ … B, and accidental=flat spells with flats. Everything is computed locally and deterministically, so it is instant and private. Ideal for music-education, ear-training, songwriting, DAW-plugin, notation and instrument app developers, chord-and-scale tools, and practice software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. This is pitch-class theory; for the actual frequency of a note use a music-note API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/musictheory-api/..."
```

## Pricing
- **Free** (Free) — 6,700 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 67,000 calls/Mo, 6 req/s
- **Pro** ($11/Mo) — 315,000 calls/Mo, 15 req/s
- **Mega** ($36/Mo) — 1,670,000 calls/Mo, 40 req/s

## Endpoints

### Music

#### `GET /v1/chord` — Chord tones

**Parameters:**
- `root` (query, required, string) — Root note Example: `C`
- `type` (query, optional, string) — major, minor, dominant7, … Example: `major`
- `accidental` (query, optional, string) — sharp or flat

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/musictheory-api/v1/chord?root=C&type=major"
```

**Response:**
```json
{
    "data": {
        "note": "Chord tones as semitone offsets from the root. C major = C E G (0,4,7); C7 = C E G B♭ (0,4,7,10).",
        "notes": [
            "C",
            "E",
            "G"
        ],
        "inputs": {
            "root": "C",
            "type": "major"
        },
        "intervals": [
            0,
            4,
            7
        ],
        "notes_string": "C E G"
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:11.827Z",
        "request_id": "4de41e0f-189a-48a6-959f-2ddf81e53c96"
    },
    "status": "ok",
    "message": "Chord",
    "success": true
}
```

#### `GET /v1/interval` — Interval between two notes

**Parameters:**
- `from` (query, required, string) — First note Example: `C`
- `to` (query, required, string) — Second note Example: `G`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/musictheory-api/v1/interval?from=C&to=G"
```

**Response:**
```json
{
    "data": {
        "note": "Ascending interval from 'from' to 'to' within an octave (0–12 semitones). C to G is 7 semitones, a perfect 5th.",
        "inputs": {
            "to": "G",
            "from": "C"
        },
        "interval": "perfect 5th",
        "semitones": 7
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:11.931Z",
        "request_id": "af59208e-ad4a-4a09-8750-4b9b76321b90"
    },
    "status": "ok",
    "message": "Interval",
    "success": true
}
```

#### `GET /v1/scale` — Scale notes

**Parameters:**
- `root` (query, required, string) — Tonic note Example: `C`
- `mode` (query, optional, string) — major, natural-minor, dorian, … Example: `major`
- `accidental` (query, optional, string) — sharp or flat

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/musictheory-api/v1/scale?root=C&mode=major"
```

**Response:**
```json
{
    "data": {
        "note": "Scale notes as semitone offsets from the tonic. C major = C D E F G A B; A natural-minor = A B C D E F G.",
        "notes": [
            "C",
            "D",
            "E",
            "F",
            "G",
            "A",
            "B"
        ],
        "inputs": {
            "mode": "major",
            "root": "C"
        },
        "degrees": [
            0,
            2,
            4,
            5,
            7,
            9,
            11
        ],
        "notes_string": "C D E F G A B"
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:12.039Z",
        "request_id": "36ba9312-5648-4f59-a39b-6b80b217b8f0"
    },
    "status": "ok",
    "message": "Scale",
    "success": true
}
```

#### `GET /v1/transpose` — Transpose notes

**Parameters:**
- `notes` (query, required, string) — Notes (comma/space separated) Example: `C E G`
- `semitones` (query, required, string) — Semitones (±) Example: `7`
- `accidental` (query, optional, string) — sharp or flat

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/musictheory-api/v1/transpose?notes=C+E+G&semitones=7"
```

**Response:**
```json
{
    "data": {
        "note": "Each note shifted by the given number of semitones (negative transposes down). C +7 → G.",
        "inputs": {
            "notes": [
                "C",
                "E",
                "G"
            ],
            "semitones": 7
        },
        "transposed": [
            "G",
            "B",
            "D"
        ],
        "transposed_string": "G B D"
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:12.131Z",
        "request_id": "deade6c3-59ca-4eb2-aa17-5b0d0da4a33b"
    },
    "status": "ok",
    "message": "Transpose",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/musictheory-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Notes use C, C#, Db … B (case-insensitive). Set accidental=flat to spell with flats. This is pitch-class theory; for note frequencies use a music-note API.",
        "service": "musictheory-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/chord": "Chord tones from a root and chord type.",
            "GET /v1/scale": "Scale notes from a root and mode.",
            "GET /v1/interval": "Semitones and interval name between two notes.",
            "GET /v1/transpose": "Transpose notes by a number of semitones."
        },
        "chord_types": [
            "6",
            "7",
            "9",
            "major",
            "minor",
            "diminished",
            "augmented",
            "major7",
            "minor7",
            "dominant7",
            "diminished7",
            "half-diminished7",
            "minormajor7",
            "sus2",
            "sus4",
            "minor6",
            "add9",
            "power"
        ],
        "description": "Music theory: intervals, transposition, chords and scales over the 12-tone chromatic scale.",
        "scale_modes": [
            "major",
            "natural-minor",
            "minor",
            "harmonic-minor",
            "melodic-minor",
            "dorian",
            "phrygian",
            "lydian",
            "mixolydian",
            "locrian",
            "pentatonic-major",
            "pentatonic-minor",

…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/musictheory-api
OpenAPI spec: https://www.oanor.com/api/musictheory-api/openapi.json