{"openapi":"3.1.0","info":{"title":"RadioMetrika Core API","description":"FM audience measurement and reporting engine conforming to RadioMetrika TZ v1.1","version":"1.0.0"},"paths":{"/health":{"get":{"summary":"Health Check","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/storage/status":{"get":{"summary":"Get Storage Status","description":"Returns high-level status of the dual-database architecture:\n- PostgreSQL 16 (Relational Metadata & RBAC Hub)\n- ClickHouse (High-Throughput Telemetry & Analytics Engine)","operationId":"get_storage_status_v1_storage_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/metrics/realtime-rollup":{"get":{"summary":"Get Realtime Rollup","description":"Returns sub-millisecond 15-minute analytical rollups (Reach via uniqHLL12, AQH, match scores)\ncomputed directly by ClickHouse AggregatingMergeTree.","operationId":"get_realtime_rollup_v1_metrics_realtime_rollup_get","parameters":[{"name":"station_id","in":"query","required":true,"schema":{"type":"string","description":"Target station ID","title":"Station Id"},"description":"Target station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","description":"Analysis window in hours","default":2,"title":"Hours"},"description":"Analysis window in hours"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stations":{"get":{"summary":"Get Stations","description":"List registered broadcast stations with authorized frequencies.","operationId":"get_stations_v1_stations_get","parameters":[{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by market ID","title":"Market Id"},"description":"Filter by market ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StationMetadata"},"title":"Response Get Stations V1 Stations Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/fm-observations/batch":{"post":{"summary":"Ingest Batch","description":"Ingest observation batch from mobile edge panel or simulator.\nApplies schema validation, quarantine rules, and FM qualification.","operationId":"ingest_batch_v1_fm_observations_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FMObservationBatch"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/audience":{"get":{"summary":"Get Audience Metrics","description":"Returns statistical audience summary (reach, n_eff, 95% CI) for a station.\nSuppresses results below threshold to ensure privacy.","operationId":"get_audience_metrics_v1_metrics_audience_get","parameters":[{"name":"station_id","in":"query","required":true,"schema":{"type":"string","description":"Target station ID","title":"Station Id"},"description":"Target station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","description":"Analysis time window in hours","default":1,"title":"Hours"},"description":"Analysis time window in hours"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StationAudienceSummary"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/dynamics":{"get":{"summary":"Get Station Dynamics","description":"Returns real-time high-fidelity minute-by-minute dynamics synchronized with\nmarket local time, active dayparts, broadcast clocks, live on-air tracks,\nand selected analysis horizon (60m, morning, daytime, evening).","operationId":"get_station_dynamics_v1_metrics_dynamics_get","parameters":[{"name":"station_id","in":"query","required":true,"schema":{"type":"string","description":"Target station ID","title":"Station Id"},"description":"Target station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Analysis scope: 60m, morning, daytime, evening","default":"60m","title":"Scope"},"description":"Analysis scope: 60m, morning, daytime, evening"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/music":{"get":{"summary":"Get Music Metrics","description":"Returns music audit metrics: T-Index, Skip Rate, weekly burnout curve,\nrotation scoreboard and programmed recommendations.","operationId":"get_music_metrics_v1_metrics_music_get","parameters":[{"name":"station_id","in":"query","required":false,"schema":{"type":"string","description":"Station ID","default":"dorozhnoe-ufa","title":"Station Id"},"description":"Station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"},{"name":"track_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Inspect specific track ID","title":"Track Id"},"description":"Inspect specific track ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/talk":{"get":{"summary":"Get Talk Metrics","description":"Returns content & talk audit metrics: Host Score, morning show structure,\nsegment retention, News Valley drop-off rates, and editorial insights.","operationId":"get_talk_metrics_v1_metrics_talk_get","parameters":[{"name":"station_id","in":"query","required":false,"schema":{"type":"string","description":"Station ID","default":"dorozhnoe-ufa","title":"Station Id"},"description":"Station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"},{"name":"slot","in":"query","required":false,"schema":{"type":"string","description":"Time slot to inspect","default":"08:00-09:00","title":"Slot"},"description":"Time slot to inspect"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/benchmarking":{"get":{"summary":"Get Benchmarking Metrics","description":"Returns cross-station audience overlap and commercial break migration flows.","operationId":"get_benchmarking_metrics_v1_metrics_benchmarking_get","parameters":[{"name":"station_id","in":"query","required":false,"schema":{"type":"string","description":"Target station ID","default":"dorozhnoe-ufa","title":"Station Id"},"description":"Target station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/historical":{"get":{"summary":"Get Historical Endpoint","description":"Returns historical audience metrics and Mediascope Radio Index calibration.","operationId":"get_historical_endpoint_v1_metrics_historical_get","parameters":[{"name":"station_id","in":"query","required":false,"schema":{"type":"string","description":"Station ID","default":"dorozhnoe-ufa","title":"Station Id"},"description":"Station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"},{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Time period: today, yesterday, last_7d, month_wave","default":"today","title":"Period"},"description":"Time period: today, yesterday, last_7d, month_wave"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/geo":{"get":{"summary":"Get Geo Endpoint","description":"Returns spatial arterial analytics and k-anonymity privacy protected road clusters.","operationId":"get_geo_endpoint_v1_metrics_geo_get","parameters":[{"name":"station_id","in":"query","required":false,"schema":{"type":"string","description":"Station ID","default":"dorozhnoe-ufa","title":"Station Id"},"description":"Station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/reports":{"get":{"summary":"Get Reports","description":"List available analytical report templates.","operationId":"get_reports_v1_reports_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/reports/export":{"get":{"summary":"Export Report","description":"Exports structured analytical report.\nFor format=csv: returns downloadable Excel-compatible CSV file with UTF-8 BOM and Russian headers.\nFor format=json: returns raw structured dataset.","operationId":"export_report_v1_reports_export_get","parameters":[{"name":"report_type","in":"query","required":false,"schema":{"type":"string","description":"Report template ID","default":"ad_retention_audit","title":"Report Type"},"description":"Report template ID"},{"name":"station_id","in":"query","required":false,"schema":{"type":"string","description":"Station ID","default":"dorozhnoe-ufa","title":"Station Id"},"description":"Station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"Export format: csv or json","default":"csv","title":"Format"},"description":"Export format: csv or json"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/data-quality":{"get":{"summary":"Get Data Quality Stats","description":"Returns ingestion health counters and recent quarantine issues from DB and memory.","operationId":"get_data_quality_stats_v1_data_quality_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/methodologies":{"get":{"summary":"Get Methodology Registry","description":"Returns official methodology metadata, version invariants, and data status.","operationId":"get_methodology_registry_v1_methodologies_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/simulator/generate":{"post":{"summary":"Run Simulation","description":"Triggers simulator to generate realistic synthetic FM traffic with positive,\nnegative, road noise, and streaming-discrimination scenarios.\nReturns both Observed metrics and Ground Truth reality for statistical validation.","operationId":"run_simulation_v1_simulator_generate_post","parameters":[{"name":"batch_size","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":10,"default":60,"title":"Batch Size"}},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional target market","title":"Market Id"},"description":"Optional target market"},{"name":"seed","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Deterministic seed for reproducible generation","default":42,"title":"Seed"},"description":"Deterministic seed for reproducible generation"},{"name":"scenario","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Simulation scenario: baseline, morning_peak, ad_migration, traffic_jam, highway_noise, stream_quarantine","default":"baseline","title":"Scenario"},"description":"Simulation scenario: baseline, morning_peak, ad_migration, traffic_jam, highway_noise, stream_quarantine"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/simulator/yandex-pipeline-spec":{"get":{"summary":"Get Yandex Pipeline Spec","description":"Returns formal architecture and privacy specification for Yandex Navigator integration.","operationId":"get_yandex_pipeline_spec_v1_simulator_yandex_pipeline_spec_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/roles":{"get":{"summary":"Get Rbac Roles","description":"Returns available user roles with access permissions and UI tab mappings.","operationId":"get_rbac_roles_v1_auth_roles_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/tenants":{"get":{"summary":"Get Rbac Tenants","description":"Returns media holdings and agency tenants.","operationId":"get_rbac_tenants_v1_auth_tenants_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/session":{"get":{"summary":"Get Session Context","description":"Returns user session context, permissions, and allowed navigation tabs.","operationId":"get_session_context_v1_auth_session_get","parameters":[{"name":"role_id","in":"query","required":false,"schema":{"type":"string","description":"Selected role ID","default":"holding_executive","title":"Role Id"},"description":"Selected role ID"},{"name":"tenant_id","in":"query","required":false,"schema":{"type":"string","description":"Selected tenant ID","default":"emg","title":"Tenant Id"},"description":"Selected tenant ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/proof/campaigns":{"get":{"summary":"List Advertiser Campaigns","description":"Returns registered advertising campaigns for commercial proof generation.","operationId":"list_advertiser_campaigns_v1_proof_campaigns_get","parameters":[{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional market filter","title":"Market Id"},"description":"Optional market filter"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/proof/certificate":{"get":{"summary":"Generate Commercial Proof","description":"Generates a cryptographically sealed Proof of Performance certificate for an ad spot,\nverifying exact broadcast time, spot retention, and in-car audience reach.","operationId":"generate_commercial_proof_v1_proof_certificate_get","parameters":[{"name":"campaign_id","in":"query","required":false,"schema":{"type":"string","description":"Campaign identifier","default":"ural_realty","title":"Campaign Id"},"description":"Campaign identifier"},{"name":"station_id","in":"query","required":false,"schema":{"type":"string","description":"Broadcast station ID","default":"dorozhnoe-ufa","title":"Station Id"},"description":"Broadcast station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"},{"name":"slot_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Airplay time slot, e.g. 14:18","title":"Slot Time"},"description":"Airplay time slot, e.g. 14:18"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stream/telemetry":{"get":{"summary":"Get Stream Telemetry","description":"Returns live stream telemetry comparing FM over-the-air latency (0.2s)\nagainst buffered digital internet streams (18-35s) for audio origin discrimination.","operationId":"get_stream_telemetry_v1_stream_telemetry_get","parameters":[{"name":"station_id","in":"query","required":false,"schema":{"type":"string","description":"Station ID","default":"dorozhnoe-ufa","title":"Station Id"},"description":"Station ID"},{"name":"market_id","in":"query","required":false,"schema":{"type":"string","description":"Market ID","default":"ufa","title":"Market Id"},"description":"Market ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BatchStatus":{"type":"string","enum":["DEMO","provisional","final"],"title":"BatchStatus"},"DataOrigin":{"type":"string","enum":["synthetic","real"],"title":"DataOrigin"},"FMObservationBatch":{"properties":{"schema_version":{"type":"string","const":"1.0","title":"Schema Version","default":"1.0"},"batch_id":{"type":"string","title":"Batch Id","description":"Unique batch UUID"},"data_origin":{"$ref":"#/components/schemas/DataOrigin","description":"synthetic or real"},"status":{"$ref":"#/components/schemas/BatchStatus","description":"DEMO, provisional, or final"},"generated_at":{"type":"string","format":"date-time","title":"Generated At","description":"Batch creation timestamp UTC"},"events":{"items":{"$ref":"#/components/schemas/FMObservationEvent"},"type":"array","title":"Events"}},"type":"object","required":["batch_id","data_origin","status","generated_at"],"title":"FMObservationBatch","description":"Batch contract for observation ingestion.\nSection 7.2 and Acceptance Cases M00-03, M00-04, M00-05."},"FMObservationEvent":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Unique event identifier (UUID)"},"observed_at":{"type":"string","format":"date-time","title":"Observed At","description":"Observation timestamp in UTC"},"panel_device_key":{"type":"string","title":"Panel Device Key","description":"Random non-personal pseudonymized test key"},"market_id":{"type":"string","title":"Market Id","description":"Market identifier (e.g. msk, spb, ufa)"},"station_id":{"type":"string","title":"Station Id","description":"Target radio station ID"},"frequency_mhz":{"type":"number","maximum":108.0,"minimum":64.0,"title":"Frequency Mhz","description":"Broadcast frequency in MHz"},"match_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Match Score","description":"Landmark fingerprint similarity score"},"reference_version":{"type":"string","title":"Reference Version","description":"Reference fingerprint database version"},"fm_origin_evidence":{"type":"string","title":"Fm Origin Evidence","description":"Evidence type establishing FM over streaming"},"fm_origin_confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Fm Origin Confidence","description":"Confidence in FM delivery origin"},"scenario_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scenario Id","description":"Test scenario key (e.g. clean-signal, car-noise)"},"consent_basis":{"type":"string","title":"Consent Basis","description":"User consent basis reference","default":"synthetic-not-applicable"}},"type":"object","required":["event_id","observed_at","panel_device_key","market_id","station_id","frequency_mhz","match_score","reference_version","fm_origin_evidence","fm_origin_confidence"],"title":"FMObservationEvent","description":"Individual observation event from an edge device (or simulator).\nSection 7.2 of TZ."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"StationAudienceSummary":{"properties":{"station_id":{"type":"string","title":"Station Id"},"market_id":{"type":"string","title":"Market Id"},"methodology_version":{"type":"string","title":"Methodology Version"},"status":{"type":"string","title":"Status"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"unweighted_n":{"type":"integer","title":"Unweighted N"},"n_eff":{"type":"number","title":"N Eff"},"design_effect":{"type":"number","title":"Design Effect"},"reach_estimate":{"type":"integer","title":"Reach Estimate"},"confidence_interval_95":{"items":{"type":"integer"},"type":"array","title":"Confidence Interval 95"},"is_suppressed":{"type":"boolean","title":"Is Suppressed","default":false},"suppression_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suppression Reason"}},"type":"object","required":["station_id","market_id","methodology_version","status","period_start","period_end","unweighted_n","n_eff","design_effect","reach_estimate","confidence_interval_95"],"title":"StationAudienceSummary"},"StationMetadata":{"properties":{"station_id":{"type":"string","title":"Station Id"},"name":{"type":"string","title":"Name"},"market_id":{"type":"string","title":"Market Id"},"frequency_mhz":{"type":"number","title":"Frequency Mhz"},"format_genre":{"type":"string","title":"Format Genre"},"target_demographic":{"type":"string","title":"Target Demographic"},"bitrate_kbps":{"type":"integer","title":"Bitrate Kbps","default":128},"daily_reach_benchmark":{"type":"integer","title":"Daily Reach Benchmark","default":100000},"aqh_share_pct":{"type":"number","title":"Aqh Share Pct","default":15.0},"live_listeners_benchmark":{"type":"integer","title":"Live Listeners Benchmark","default":25000},"average_tsl_minutes":{"type":"number","title":"Average Tsl Minutes","default":38.0},"ad_drop_pct":{"type":"number","title":"Ad Drop Pct","default":21.0}},"type":"object","required":["station_id","name","market_id","frequency_mhz","format_genre","target_demographic"],"title":"StationMetadata"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}