Developer API

How it works

1. 01

   Create an API key

   Mint a key from the Developer console in your dashboard. Keys are shown once, stored as hashes, and revocable instantly.

2. 02

   Submit the track in two steps

   POST /v1/analyses with the file metadata and an Idempotency-Key. You get a 202 with the analysis id and a short-lived upload target; POST the raw bytes there.

3. 03

   Read the verdict

   Poll GET /v1/analyses/:id until status is complete, or subscribe to signed webhooks. Scores land first; the full Klaus diagnosis follows shortly after.

# 1. Create the analysis — returns the id + a short-lived upload target
curl -X POST https://trackscore.ai/api/v1/analyses \
  -H "Authorization: Bearer $TRACKSCORE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"file_name":"track.wav","mastering_status":"master"}'

# 2. Upload the audio bytes to the returned upload.url
#    ($UPLOAD_URL / $UPLOAD_TOKEN / $ANALYSIS_ID come from step 1's JSON:
#     .upload.url, .upload.token, .id)
curl -X POST "$UPLOAD_URL" \
  -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -F "file=@track.wav"

# 3. Poll until status is "complete"
curl https://trackscore.ai/api/v1/analyses/$ANALYSIS_ID \
  -H "Authorization: Bearer $TRACKSCORE_API_KEY"

A typical track completes in about a minute. During early access, keys are rolling out to Pro & Studio accounts via the Developer console.

What you get back

Every completed analysis returns one JSON object: the overall score and grade, six pillar scores, tempo and key detection, genre fit against 9 electronic-genre profiles, 7-band frequency balance with per-genre ideals, loudness and dynamics, stereo metrics, structure sections, and the Klaus™ diagnosis with prioritized feedback.

{
  "object": "analysis",
  "id": "9b2f6c1e-...",
  "status": "complete",
  "diagnosis_status": "ready",
  "score": 87,
  "grade": { "letter": "B+", "label": "Very Good" },
  "scores": { "hit_potential": 87, "danceability": 91, "mix_quality": 88, ... },
  "tempo": { "bpm": 124.0, "regularity": 0.94 },
  "genre": { "detected": "deep_house", "name": "Deep House", "confidence": 0.8 },
  "frequency": { "bands": { ... }, "ideal": { ... }, "score": 84 },
  "mix": { "loudness_lufs": -8.2, "dynamic_range_db": 7.9, "stereo_width": 0.42, ... },
  "diagnosis": { "status": "ready", "summary": "The low end is dialed in. ..." },
  "feedback": [ { "type": "warn", "category": "frequency", "text": "..." } ]
}

Webhooks

Register HTTPS endpoints from the Developer console and receive signed events instead of polling. Deliveries carry a TrackScore-Signature header: t=<timestamp>,v1=<hex>, where v1 is HMAC-SHA256 over <timestamp>.<raw body> (the timestamp, a period, then the exact bytes received — not the body alone), with a 5-minute tolerance. Deliveries retry with exponential backoff for about 3 days. Consumers dedupe on the event id.

Zero-storage privacy

Pricing

API access is included with Pro & Studio and uses your monthly credits: one analysis costs one credit, the same as the web app. Test mode is free and unlimited within fair-use rate limits.

Building at volume? Contact us for partner pricing.

Frequently asked questions