# Guitar Luthier API
> Guitar and luthier maths as an API, computed locally and deterministically — the string-tension and fret numbers a player, builder or tech sets an instrument up with. The string-tension endpoint gives the tension a string pulls at pitch from the physics, tension = unit weight × (2 × scale length × frequency)² ÷ 386.4, where the unit weight (lb/in) comes from the string maker's chart — a .010 plain-steel high E on a 25.5-inch scale tuned to 329.6 Hz pulls about 16 lb. The fret-position endpoint gives the distance from the nut to any fret in equal temperament, scale × (1 − 2^(−fret/12)), so the 12th fret sits exactly halfway and the first fret of a 25.5-inch scale is 1.43 inches down — the maths behind every fretboard slot. The set-tension endpoint sums a whole string set into the total load on the neck (a typical six-string runs ~95–120 lb), the number that decides whether a gauge or tuning change needs a truss-rod re-setup. Everything is computed locally and deterministically, so it is instant and private. Ideal for luthier and guitar-tech apps, string-tension and fret-slotting calculators, setup and re-string tools, and music-gear sites. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. Get unit weights from the string maker's chart. For note↔frequency conversion use a music-theory 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/guitar-api/..."
```

## Pricing
- **Free** (Free) — 700 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 16,500 calls/Mo, 8 req/s
- **Pro** ($16/Mo) — 98,000 calls/Mo, 20 req/s
- **Mega** ($48/Mo) — 330,000 calls/Mo, 48 req/s

## Endpoints

### Guitar

#### `GET /v1/fret-position` — Fret distance from the nut

**Parameters:**
- `scale_length_in` (query, required, string) — Scale length in inches Example: `25.5`
- `fret_number` (query, required, string) — Fret number Example: `12`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/guitar-api/v1/fret-position?scale_length_in=25.5&fret_number=12"
```

**Response:**
```json
{
    "data": {
        "note": "Fret distance from the nut = scale length × (1 − 2^(−fret/12)) — equal temperament, where each fret is the twelfth root of two higher in pitch. The 12th fret sits exactly halfway (the octave), and the frets crowd together toward the bridge. The rule of 18 (≈ 17.817) is the old luthier's approximation of the same maths.",
        "inputs": {
            "fret_number": 12,
            "scale_length_in": 25.5
        },
        "distance_from_nut_in": 12.75,
        "remaining_to_bridge_in": 12.75,
        "spacing_from_previous_in": 0.7582
    },
    "meta": {
        "timestamp": "2026-06-06T23:54:00.359Z",
        "request_id": "6a20607d-cb93-480a-b00f-e4c6c5a6c276"
    },
    "status": "ok",
    "message": "Fret position",
    "success": true
}
```

#### `GET /v1/set-tension` — Total neck tension of a set

**Parameters:**
- `unit_weights_lb_in` (query, required, string) — Comma-separated unit weights (lb/in) Example: `0.0003297,0.0001705,0.0000889,0.00006402,0.00003744,0.00002215`
- `frequencies_hz` (query, required, string) — Comma-separated frequencies (Hz) Example: `82.41,110,146.83,196,246.94,329.63`
- `scale_length_in` (query, required, string) — Scale length in inches Example: `25.5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/guitar-api/v1/set-tension?unit_weights_lb_in=0.0003297%2C0.0001705%2C0.0000889%2C0.00006402%2C0.00003744%2C0.00002215&frequencies_hz=82.41%2C110%2C146.83%2C196%2C246.94%2C329.63&scale_length_in=25.5"
```

**Response:**
```json
{
    "data": {
        "note": "Total neck load = the sum of every string's tension — a typical 6-string set runs ~95–120 lb. The neck and truss rod are set up for that load, so a big jump (heavier gauge, higher tuning) bows the neck and needs a re-setup; a big drop leaves it back-bowed. Keep the total in the same ballpark when you change strings.",
        "inputs": {
            "frequencies_hz": [
                82.41,
                110,
                146.83,
                196,
                246.94,
                329.63
            ],
            "scale_length_in": 25.5,
            "unit_weights_lb_in": [
                0.0003297,
                0.0001705,
                8.89e-5,
                6.402e-5,
                3.744e-5,
                2.215e-5
            ]
        },
        "total_tension_kg": 40.8,
        "total_tension_lb": 90,
        "per_string_tension_lb": [
            15.07,
            13.89,
            12.9,
            16.56,
            15.37,
            16.2
        ]
    },
    "meta": {
        "timestamp": "2026-06-06T23:54:00.458Z",
        "request_id": "6871c9ec-099c-428a-9384-ff7ee3e6fcc6"
    },
    "status": "ok",
    "message": "Set tension",
    "success": true
}
```

#### `GET /v1/string-tension` — Tension of one string

**Parameters:**
- `unit_weight_lb_in` (query, required, string) — Unit weight in lb/in (maker chart) Example: `0.00002215`
- `scale_length_in` (query, required, string) — Scale length in inches Example: `25.5`
- `frequency_hz` (query, required, string) — Tuned frequency in Hz Example: `329.63`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/guitar-api/v1/string-tension?unit_weight_lb_in=0.00002215&scale_length_in=25.5&frequency_hz=329.63"
```

**Response:**
```json
{
    "data": {
        "note": "String tension = unit weight × (2 × scale length × frequency)² ÷ 386.4, with the unit weight (lb/in) from the maker's chart — a .010 plain steel high-E (≈ 0.0000221 lb/in) on a 25.5-inch scale tuned to 329.6 Hz pulls about 16 lb. Match tensions across a set for even feel, and watch the total load when you change gauge or tuning.",
        "inputs": {
            "frequency_hz": 329.63,
            "scale_length_in": 25.5,
            "unit_weight_lb_in": 2.215e-5
        },
        "tension_kg": 7.35,
        "tension_lb": 16.2
    },
    "meta": {
        "timestamp": "2026-06-06T23:54:00.551Z",
        "request_id": "185023d8-92b1-444d-9f22-07d0d5fb60c6"
    },
    "status": "ok",
    "message": "String tension",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "US units (inches, Hz, lb). Tension = unit weight × (2·L·f)² ÷ 386.4; fret = scale × (1 − 2^(−n/12)). Get unit weights from the string maker's chart. For note↔frequency use a music-theory API.",
        "service": "guitar-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/set-tension": "Total neck tension from a string set (parallel CSV lists).",
            "GET /v1/fret-position": "Distance from the nut to a fret (equal temperament).",
            "GET /v1/string-tension": "Tension of a single string from its unit weight, scale length and frequency."
        },
        "description": "Guitar / luthier maths: string tension from frequency, fret positions along a scale, and the total tension a string set puts on the neck."
    },
    "meta": {
        "timestamp": "2026-06-06T23:54:00.626Z",
        "request_id": "0884a349-9d60-4557-96bd-c9403d8bed3e"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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