{"openapi":"3.0.3","info":{"title":"HPDE.tv Broadcast & Media REST API","version":"2.4.0","description":"The sovereign API protocol for HPDE.tv media streaming, TrackDayOS event operations, RaceDayOS race control flag dispatch, and HPDE.app Universal Driver Passport sync.","contact":{"name":"HPDE.tv Architecture & Engineering","url":"https://hpde.tv","email":"engineering@hpde.tv"}},"servers":[{"url":"http://localhost:3000/api/v1","description":"Local Development / Sandbox Server"},{"url":"https://hpde.tv/api/v1","description":"Production Edge Gateway"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Licensee operator API key scoped to host organization (e.g. hpde_live_sec_tdx_2026_987x)"}}},"paths":{"/broadcast/status":{"get":{"summary":"Get Live Broadcast & Stream Health Status","description":"Returns real-time broadcast status, active cameras, bitrates, flag state, and viewer counts for a specific track licensee.","tags":["Broadcast Operations"],"parameters":[{"name":"tenantId","in":"query","required":false,"schema":{"type":"string","default":"drivetdx"},"description":"Identifier for the track day organization / licensee."}],"responses":{"200":{"description":"Successful status response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"tenantId":{"type":"string"},"circuit":{"type":"string"},"event":{"type":"string"},"condition":{"type":"string"},"activeStint":{"type":"string"},"sessionTimeRemaining":{"type":"string"},"viewers":{"type":"object","properties":{"total":{"type":"number"},"paddockKiosks":{"type":"number"},"remoteWeb":{"type":"number"}}},"hotCamera":{"type":"string"},"cameras":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string"},"bitrate":{"type":"string"},"fps":{"type":"number"},"isHot":{"type":"boolean"}}}}}}}}}}}},"/broadcast/control":{"post":{"summary":"Operator Remote Broadcast Control (Single Pane of Glass)","description":"Allows TrackDayOS operator dashboards to remotely control the HPDE.tv broadcast without leaving the TrackDayOS interface.","tags":["Broadcast Operations"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"tenantId":{"type":"string","default":"drivetdx"},"action":{"type":"string","enum":["SET_HOT_CAMERA","TRIGGER_EMERGENCY_BLACKOUT","PUSH_TICKER_ALERT","RESET_DEFAULT"]},"hotCameraId":{"type":"string","example":"cam-2"},"tickerAlert":{"type":"string","example":"Debris cleared at Station 3. Track is full GREEN."},"blackoutActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Action acknowledged and applied across active players","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"tenantId":{"type":"string"},"action":{"type":"string"},"updatedAt":{"type":"string"}}}}}}}}},"/broadcast/flags":{"post":{"summary":"RaceDayOS Tower Flag Webhook","description":"Synchronous webhook triggered by RaceDayOS or TrackDayOS tower controllers to push live track conditions to consumer video players in under 50ms.","tags":["Race Control & Flags"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["condition"],"properties":{"tenantId":{"type":"string","default":"drivetdx"},"condition":{"type":"string","enum":["GREEN","YELLOW","RED","CHECKERED","BLACK","WHITE"]},"reason":{"type":"string","example":"Car #88 spin Turn 7 grass recovery"},"activeGroup":{"type":"string","example":"Group A Advanced Solo"},"nextGroup":{"type":"string","example":"Group B Solo"},"stintMinutesLeft":{"type":"number","example":14}}}}}},"responses":{"200":{"description":"Flag state accepted and broadcast HUD updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"condition":{"type":"string"},"syncedStreams":{"type":"number"},"broadcastLatencyMs":{"type":"number"}}}}}}}}},"/broadcast/waivers":{"post":{"summary":"TrackDayOS Gate Check-in Driver Media Waiver Compliance","description":"Called by TrackDayOS registration and gate check-in systems to record driver media consent, in-car camera broadcasting permissions, and telemetry privacy.","tags":["Compliance & Waivers"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["driverId"],"properties":{"tenantId":{"type":"string","default":"drivetdx"},"driverId":{"type":"string","example":"usr_gene_44"},"carNumber":{"type":"string","example":"44"},"driverName":{"type":"string","example":"Gene Salvatore"},"mediaConsent":{"type":"boolean","default":true},"cockpitStreamConsent":{"type":"boolean","default":true},"blurTelemetry":{"type":"boolean","default":false},"signedAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Waiver recorded and broadcast permission resolved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"driverId":{"type":"string"},"broadcastPermission":{"type":"string","enum":["FULL_ACCESS","EXTERIOR_ONLY","RESTRICTED_TELEMETRY_BLUR","REVOKED_BLACKOUT"]}}}}}}}}},"/driver/stints":{"get":{"summary":"HPDE.app Driver Passport Stints & 4K Replays","description":"Pulls recorded 4K stints, personal best lap times, and social clips directly for a driver’s HPDE.app Universal Driver Passport.","tags":["Driver Passport"],"parameters":[{"name":"driverId","in":"query","required":false,"schema":{"type":"string","default":"usr_gene_44"},"description":"Unique HPDE.app driver identifier."}],"responses":{"200":{"description":"Driver stints and media assets","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"driverId":{"type":"string"},"driverName":{"type":"string"},"carNumber":{"type":"string"},"vehicle":{"type":"string"},"totalHoursLogged":{"type":"number"},"stints":{"type":"array","items":{"type":"object","properties":{"stintId":{"type":"string"},"circuit":{"type":"string"},"event":{"type":"string"},"date":{"type":"string"},"duration":{"type":"string"},"bestLap":{"type":"string"},"topSpeed":{"type":"string"},"downloadUrl4K":{"type":"string"},"clip15sUrl":{"type":"string"}}}}}}}}}}}}}}