{"openapi":"3.1.0","info":{"title":"LangBeat API","version":"1.0.0","description":"Measured music analysis. LangBeat detects tempo, musical key and Camelot code from the audio of a recording, separates it into six stems, and logs daily and weekly charts for 139 markets. This API exposes the public catalogue and the chart log.\n\nOnly recordings explicitly marked public are returned. An API key identifies and rate-limits a caller; it never widens what may be read.","contact":{"url":"https://langbeat.live/developers"},"termsOfService":"https://langbeat.live/terms"},"servers":[{"url":"https://langbeat.live"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A LangBeat API key, created at /developers. Send as `Authorization: Bearer lb_live_...`."}},"schemas":{"Track":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"artist":{"type":"string","nullable":true},"album":{"type":"string","nullable":true},"release_year":{"type":"integer","nullable":true},"genre":{"type":"string","nullable":true},"duration_seconds":{"type":"number","nullable":true},"analysis":{"type":"object","description":"Measured from the audio, not read from metadata.","properties":{"bpm":{"type":"number","nullable":true,"description":"Tempo in beats per minute."},"musical_key":{"type":"string","nullable":true,"example":"F# minor"},"camelot_key":{"type":"string","nullable":true,"example":"11A","description":"Harmonic mixing code."}}},"url":{"type":"string","format":"uri"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on `message`.","enum":["unauthorized","rate_limited","not_found","invalid_id","invalid_region","unknown_chart","invalid_camelot","invalid_query","invalid_slug","analysis_unavailable","internal_error"]},"message":{"type":"string"}}}}}}},"paths":{"/api/v1/tracks":{"get":{"summary":"Search the public catalogue","description":"Filter by what was measured. `bpm_min`/`bpm_max` with `camelot` is the query this catalogue exists to answer: records in a tempo range that will mix harmonically.","operationId":"searchTracks","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"description":"Title or artist text match."},{"name":"bpm_min","in":"query","schema":{"type":"number"}},{"name":"bpm_max","in":"query","schema":{"type":"number"}},{"name":"key","in":"query","schema":{"type":"string"},"example":"A minor"},{"name":"camelot","in":"query","schema":{"type":"string","pattern":"^(1[0-2]|[1-9])[ABab]$"},"example":"8A"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Matching recordings.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Track"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer","nullable":true},"has_more":{"type":"boolean"}}}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tracks/{id}":{"get":{"summary":"One recording","operationId":"getTrack","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The recording.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Track"}}}}}},"404":{"description":"No public recording with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tracks/{id}/analysis":{"get":{"summary":"Per-bar energy for each separated stem","description":"The energy curve derived from stem separation: one normalised 0-1 value per bar for each of vocals, drums, bass, guitar, piano, melody and fx, plus the combined total. `grid.seconds_per_bar` converts an index into a timestamp.\n\nThis returns MEASUREMENTS, never audio. The separated stems themselves are not served.","operationId":"getTrackAnalysis","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The energy analysis."},"404":{"description":"No public recording with that id, or no analysis for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artists/{slug}":{"get":{"summary":"An artist and their public catalogue","operationId":"getArtist","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"The artist."},"404":{"description":"No artist with that slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/charts/{region}":{"get":{"summary":"A market's current chart","description":"Returns the most recent chart logged for the market, with position movement. Apple's feed publishes only an ordered list, so movement there is derived against the market's previous edition; Billboard publishes last week, peak and weeks on chart and those are returned as published. `track` is populated only where LangBeat holds the recording publicly.","operationId":"getChart","parameters":[{"name":"region","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"example":"US","description":"ISO 3166-1 alpha-2."},{"name":"source","in":"query","schema":{"type":"string","enum":["apple-most-played","billboard-hot-100"],"default":"apple-most-played"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"The chart.","content":{"application/json":{"schema":{"type":"object","properties":{"region":{"type":"string"},"source":{"type":"string"},"date":{"type":"string","format":"date","nullable":true},"data":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"title":{"type":"string"},"artist":{"type":"string","nullable":true},"previous_rank":{"type":"integer","nullable":true},"movement":{"type":"integer","nullable":true,"description":"Positive is a climb."},"is_new":{"type":"boolean","nullable":true,"description":"Null when there is no previous edition to compare against."},"peak_position":{"type":"integer","nullable":true},"weeks_on_chart":{"type":"integer","nullable":true},"track":{"type":"object","nullable":true}}}}}}}}},"400":{"description":"Bad region or unknown chart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}