MeloData API

curl -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  https://melodata.voltenworks.com/api/v1/tracks/USRC17607839/features

melo_sk_{64 hex characters}    # 72 characters total

{
  "data": {
    "isrc": "USRC17607839",
    "title": "Bohemian Rhapsody",
    "features": { ... }
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6",
    "quota": {
      "used": 4521,
      "limit": 25000,
      "resets_at": "2026-05-01T00:00:00Z"
    }
  }
}

{
  "error": {
    "message": "Invalid API key",
    "status": 401
  },
  "meta": {
    "request_id": "req_f6e5d4c3b2a1"
  }
}

{
  "data": {
    "isrc": "USRC17607839",
    "title": "Bohemian Rhapsody",
    "artist": "Queen",
    "features": {
      "bpm": 143.8,
      "tempo_confidence": 0.93,
      "key": "Bb",
      "key_confidence": 0.87,
      "energy": 0.72,
      "danceability": 0.39,
      "valence": 0.23,
      "acousticness": 0.28,
      "loudness": -7.2,
      "instrumentalness": 0.01,
      "speechiness": 0.05,
      "liveness": null,
      "time_signature": 4
    }
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6",
    "quota": { "used": 4521, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" }
  }
}

{
  "data": {
    "isrc": "USRC17607839",
    "status": "analyzing",
    "estimated_seconds": 30
  },
  "meta": {
    "request_id": "req_c3d4e5f6a1b2"
  }
}

{
  "data": {
    "isrc": "XX1234567890",
    "status": "unavailable",
    "reason": "No audio source found for analysis. This track may be unreleased, region-locked, or have an incorrect ISRC."
  }
}

{
  "data": {
    "isrc": "USRC17607839",
    "title": "Bohemian Rhapsody",
    "artist": "Queen",
    "album": "A Night at the Opera",
    "release_date": "1975-10-31",
    "duration_ms": 354320
  },
  "meta": {
    "request_id": "req_d4e5f6a1b2c3",
    "quota": { "used": 4522, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" }
  }
}

{
  "data": {
    "results": [
      {
        "isrc": "USRC17607839",
        "title": "Bohemian Rhapsody",
        "artist": "Queen",
        "album": "A Night at the Opera",
        "release_date": "1975-10-31"
      },
      {
        "isrc": "GBARL9300135",
        "title": "Bohemian Rhapsody (Live)",
        "artist": "Queen",
        "album": "Live at Wembley",
        "release_date": "1992-05-25"
      }
    ],
    "pagination": {
      "offset": 0,
      "limit": 20,
      "count": 2
    }
  },
  "meta": { "request_id": "req_e5f6a1b2c3d4", "quota": { "used": 4523, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" } }
}

curl -G https://melodata.voltenworks.com/api/v1/tracks/resolve \
  -H "Authorization: Bearer melo_sk_your_key_here" \
  --data-urlencode "title=Bohemian Rhapsody" \
  --data-urlencode "artist=Queen"

{
  "data": {
    "query": { "title": "Bohemian Rhapsody", "artist": "Queen" },
    "isrc": "GBUM71029604",
    "matched": {
      "title": "Bohemian Rhapsody",
      "artist": "Queen",
      "album": "A Night at the Opera",
      "release_date": "1975-10-31"
    },
    "confidence": 1,
    "confidence_level": "exact",
    "warning": null,
    "source": "catalog",
    "cached": false,
    "providers": { "deezer": "not_tried", "itunes": "not_tried" },
    "analysis_queued": false
  },
  "meta": { "request_id": "req_a1b2c3d4e5f6", "quota": { "used": 4524, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" } }
}

curl -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  "https://melodata.voltenworks.com/api/v1/recommendations?seed=USRC17607839&seed=GBAYE0601498&target_energy=0.8&limit=5"

{
  "data": {
    "recommendations": [
      {
        "isrc": "GBAYE0601498",
        "title": "Don't Stop Me Now",
        "artist": "Queen",
        "match_score": 0.91,
        "features": { "bpm": 156.2, "energy": 0.84, "danceability": 0.55, "valence": 0.68 }
      },
      {
        "isrc": "USIR10211015",
        "title": "Mr. Brightside",
        "artist": "The Killers",
        "match_score": 0.86,
        "features": { "bpm": 148.1, "energy": 0.78, "danceability": 0.42, "valence": 0.31 }
      }
    ],
    "seed_count": 2
  },
  "meta": { "request_id": "req_a1b2c3d4e5f6", "quota": { "used": 4525, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" } }
}

{
  "isrcs": ["USRC17607839", "GBAYE0601498", "XX0000000000"]
}

{
  "data": {
    "tracks": [
      {
        "isrc": "USRC17607839",
        "title": "Bohemian Rhapsody",
        "artist": "Queen",
        "features": { "bpm": 143.8, "key": "Bb", "energy": 0.72, "danceability": 0.39, ... }
      },
      {
        "isrc": "GBAYE0601498",
        "title": "Don't Stop Me Now",
        "artist": "Queen",
        "features": { "bpm": 156.2, "key": "F", "energy": 0.84, "danceability": 0.55, ... }
      },
      {
        "isrc": "XX0000000000",
        "status": "analyzing"
      }
    ]
  },
  "meta": { "request_id": "req_b2c3d4e5f6a1", "quota": { "used": 4528, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" } }
}

{
  "isrcs": ["USRC17607839", "GBAYE0601498"]
}

{
  "data": {
    "queued": 3,
    "already_analyzed": 1,
    "already_queued": 1,
    "total": 5
  },
  "meta": { "request_id": "req_c3d4e5f6a1b2" }
}

curl -X POST https://melodata.voltenworks.com/api/v1/tracks/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-library-2026-09-07" \
  -d '{"tracks":[{"title":"Blinding Lights","artist":"The Weeknd"}]}'

{
  "data": {
    "isrc": "XX1234567890",
    "status": "queued_for_reanalysis",
    "estimated_seconds": 30
  }
}

const API_KEY = process.env.MELODATA_API_KEY;
const BASE = "https://melodata.voltenworks.com/api/v1";

async function getFeatures(isrc) {
  for (let attempt = 0; attempt < 4; attempt++) {
    const res = await fetch(`${BASE}/tracks/${isrc}/features`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
      signal: AbortSignal.timeout(20000),
    });
    if (res.status === 202) {
      if (attempt === 3) throw new Error("Analysis still pending");
      const delay = Number(res.headers.get("Retry-After") ?? 30);
      if (!Number.isFinite(delay) || delay < 0 || delay > 120) {
        throw new Error("Retry later using the Retry-After header");
      }
      await new Promise(resolve => setTimeout(resolve, delay * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
  }
}

const result = await getFeatures("USRC17607839");
// A successful response can be partial or unavailable.
console.log(result.data?.features?.bpm ?? null);
console.log(result.data?.features?.key ?? null);

// POST https://your-app.com/webhooks/melodata
{
  "event": "track.analyzed",
  "data": {
    "isrc": "USRC17607839",
    "features": {
      "bpm": 143.8,
      "tempo_confidence": 0.93,
      "key": "Bb",
      "energy": 0.72,
      "danceability": 0.39,
      "valence": 0.23,
      ...
    }
  }
}

const API_KEY = process.env.MELODATA_API_KEY;
const BASE = "https://melodata.voltenworks.com/api/v1";

async function getFeatures(isrc) {
  for (let attempt = 0; attempt < 4; attempt++) {
    const res = await fetch(`${BASE}/tracks/${isrc}/features`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
      signal: AbortSignal.timeout(20000),
    });
    if (res.status === 202) {
      if (attempt === 3) throw new Error("Analysis still pending");
      const delay = Number(res.headers.get("Retry-After") ?? 30);
      if (!Number.isFinite(delay) || delay < 0 || delay > 120) {
        throw new Error("Retry later using the Retry-After header");
      }
      await new Promise(resolve => setTimeout(resolve, delay * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
  }
}

const result = await getFeatures("USRC17607839");
// A successful response can be partial or unavailable.
console.log(result.data?.features?.bpm ?? null);
console.log(result.data?.features?.key ?? null);

import os, time, requests

BASE = "https://melodata.voltenworks.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['MELODATA_API_KEY']}"}

def get_features(isrc):
    for attempt in range(4):
        res = requests.get(
            f"{BASE}/tracks/{isrc}/features",
            headers=headers, timeout=20,
        )
        if res.status_code == 202:
            if attempt == 3:
                raise RuntimeError("Analysis still pending")
            delay = float(res.headers.get("Retry-After", 30))
            if not 0 <= delay <= 120:
                raise RuntimeError("Retry later using Retry-After")
            time.sleep(delay)
            continue
        res.raise_for_status()
        return res.json()

result = get_features("USRC17607839")
# A successful response can be partial or unavailable.
features = (result.get("data") or {}).get("features") or {}
print(features.get("bpm"))
print(features.get("key"))

# Get features for a single track
curl -s -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  https://melodata.voltenworks.com/api/v1/tracks/USRC17607839/features | jq .

# Search for tracks
curl -s -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  "https://melodata.voltenworks.com/api/v1/tracks/search?q=bohemian+rhapsody&limit=5" | jq .

# Batch feature lookup
curl -s -X POST \
  -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isrcs":["USRC17607839","GBAYE0601498"]}' \
  https://melodata.voltenworks.com/api/v1/tracks/batch/features | jq .

# Get recommendations from seed tracks
curl -s -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  "https://melodata.voltenworks.com/api/v1/recommendations?seed=USRC17607839&seed=GBAYE0601498&limit=10" | jq .

# Request batch analysis (a successful request counts as one lookup)
curl -s -X POST \
  -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isrcs":["USRC17607839","GBAYE0601498"]}' \
  https://melodata.voltenworks.com/api/v1/tracks/batch/analyze | jq .

// 401 Unauthorized
{
  "error": {
    "message": "Missing or invalid Authorization header",
    "status": 401
  },
  "meta": {
    "request_id": "req_f6a1b2c3d4e5"
  }
}

// 429 Rate Limited
{
  "error": {
    "message": "Rate limit exceeded",
    "status": 429
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6"
  }
}
// Headers: X-RateLimit-Reset: 1711234567

// 429 Quota Exceeded
{
  "error": {
    "message": "Monthly quota exceeded: you've used this month's 1,000 free lookups. Upgrade to Dev ($19/mo, 25,000 lookups) to keep going: https://melodata.voltenworks.com/dashboard/billing?plan=dev&from=quota_429",
    "status": 429,
    "code": "quota_exhausted",
    "upgrade_url": "https://melodata.voltenworks.com/dashboard/billing?plan=dev&from=quota_429"
  },
  "meta": {
    "request_id": "req_b2c3d4e5f6a1"
  }
}
// Headers: X-Quota-Used: 1000, X-Quota-Limit: 1000
// upgrade_url is null on Scale, which has no plan above it.