{"openapi":"3.0.3","info":{"title":"Lebanon War Tracker API","description":"Public REST API for accessing conflict data, airstrikes, alerts, news aggregation, government decrees, and territorial progression data related to the Lebanon conflict.","version":"1.0.0","contact":{"name":"Lebanon War Tracker"}},"servers":[{"url":"/api/v1","description":"v1 API"}],"paths":{"/strikes":{"get":{"summary":"List airstrikes","description":"Returns paginated airstrike records with optional filtering by region, type, date range, casualty counts, and full-text search.","tags":["Strikes"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Results per page (max 100)"},{"name":"region","in":"query","schema":{"type":"string"},"description":"Filter by region (comma-separated for multiple)"},{"name":"strike_type","in":"query","schema":{"type":"string","enum":["airstrike","shelling","drone","naval","bridge","shrapnel_fallout"]},"description":"Filter by strike type (comma-separated for multiple)"},{"name":"verified","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Filter by verification status"},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"},"description":"Start date (ISO 8601)"},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"},"description":"End date (ISO 8601)"},{"name":"min_killed","in":"query","schema":{"type":"integer"},"description":"Minimum killed count"},{"name":"max_killed","in":"query","schema":{"type":"integer"},"description":"Maximum killed count"},{"name":"min_wounded","in":"query","schema":{"type":"integer"},"description":"Minimum wounded count"},{"name":"max_wounded","in":"query","schema":{"type":"integer"},"description":"Maximum wounded count"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Full-text search across location, region, and damage description"},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["timestamp","killed","wounded","location_name"],"default":"timestamp"},"description":"Sort field"},{"name":"sort_order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction"}],"responses":{"200":{"description":"Paginated list of strikes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrikeListResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/alerts":{"get":{"summary":"List alerts","description":"Returns alert records with optional filtering by active status and region.","tags":["Alerts"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Results per page"},{"name":"active","in":"query","schema":{"type":"string","enum":["true"]},"description":"Filter to active alerts only"},{"name":"region","in":"query","schema":{"type":"string"},"description":"Filter by region"}],"responses":{"200":{"description":"Paginated list of alerts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertListResponse"}}}},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/news":{"get":{"summary":"List news articles and clusters","description":"Returns news clusters (grouped stories) and standalone articles with filtering.","tags":["News"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20},"description":"Results per page"},{"name":"outlet","in":"query","schema":{"type":"string"},"description":"Filter by news outlet name"},{"name":"topic","in":"query","schema":{"type":"string"},"description":"Filter by topic tag"},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"},"description":"Start date"},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"},"description":"End date"}],"responses":{"200":{"description":"News clusters and solo articles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsResponse"}}}},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/decrees":{"get":{"summary":"List government decrees","description":"Returns paginated government decrees and official statements.","tags":["Decrees"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20},"description":"Results per page"},{"name":"issuing_body","in":"query","schema":{"type":"string"},"description":"Filter by issuing body"},{"name":"decree_type","in":"query","schema":{"type":"string","enum":["military","evacuation","ceasefire","sanctions","statement"]},"description":"Filter by decree type"},{"name":"country","in":"query","schema":{"type":"string"},"description":"Filter by country"},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"},"description":"Start date"},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"},"description":"End date"}],"responses":{"200":{"description":"Paginated list of decrees","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecreeListResponse"}}}},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/stats":{"get":{"summary":"Dashboard statistics","description":"Returns aggregate statistics: total strikes, casualties, active alerts, and articles today.","tags":["Stats"],"responses":{"200":{"description":"Dashboard statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}},"/progression":{"get":{"summary":"Territorial progression data","description":"Returns GeoJSON territorial progression data. Use `dates_only=true` to list available dates.","tags":["Progression"],"parameters":[{"name":"date","in":"query","schema":{"type":"string","format":"date"},"description":"Retrieve data for a specific date"},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"},"description":"Start date for range query"},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"},"description":"End date for range query"},{"name":"dates_only","in":"query","schema":{"type":"string","enum":["true"]},"description":"Return only a list of available dates"}],"responses":{"200":{"description":"GeoJSON FeatureCollection or list of dates"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"ApiEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"description":"Response payload"},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","data","timestamp"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time"}}},"Strike":{"type":"object","properties":{"id":{"type":"string"},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true},"location_name":{"type":"string"},"region":{"type":"string"},"strike_type":{"type":"string","enum":["airstrike","shelling","drone","naval","bridge","shrapnel_fallout"]},"timestamp":{"type":"string","format":"date-time"},"killed":{"type":"integer"},"wounded":{"type":"integer"},"missing":{"type":"integer"},"damage_desc":{"type":"string","nullable":true},"verified":{"type":"boolean"},"source_url":{"type":"string","nullable":true},"source_name":{"type":"string","nullable":true},"photos":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"is_manual":{"type":"boolean"},"radius":{"type":"number","nullable":true},"radius_unit":{"type":"string","enum":["meters","kilometers"],"nullable":true},"area_geojson":{"type":"object","nullable":true,"description":"GeoJSON Feature containing Polygon or MultiPolygon geometry for the affected area."},"area_label":{"type":"string","nullable":true},"area_level":{"type":"string","enum":["city","block","street","region","custom"],"nullable":true},"area_source":{"type":"string","enum":["mapbox","manual","geojson"],"nullable":true},"area_external_id":{"type":"string","nullable":true}}},"StrikeListResponse":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Strike"}}}}]},"Alert":{"type":"object","properties":{"id":{"type":"string"},"region":{"type":"string"},"alert_type":{"type":"string","enum":["missile","drone","ground"]},"issued_at":{"type":"string","format":"date-time"},"lifted_at":{"type":"string","format":"date-time","nullable":true},"is_active":{"type":"boolean"},"source":{"type":"string","nullable":true},"source_name":{"type":"string","nullable":true},"source_url":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"AlertListResponse":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}}}}]},"NewsArticle":{"type":"object","properties":{"id":{"type":"string"},"outlet":{"type":"string"},"headline":{"type":"string"},"url":{"type":"string"},"published_at":{"type":"string","format":"date-time"},"summary":{"type":"string","nullable":true},"topic_tags":{"type":"array","items":{"type":"string"}},"cluster_id":{"type":"string","nullable":true},"scraped_at":{"type":"string","format":"date-time"}}},"NewsCluster":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string"},"event_date":{"type":"string","format":"date-time"},"articles":{"type":"array","items":{"$ref":"#/components/schemas/NewsArticle"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"NewsResponse":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"clusters":{"type":"array","items":{"$ref":"#/components/schemas/NewsCluster"}},"soloArticles":{"type":"array","items":{"$ref":"#/components/schemas/NewsArticle"}},"freshness":{"$ref":"#/components/schemas/NewsFreshness"}}}}}]},"NewsFreshness":{"type":"object","properties":{"last_scrape_at":{"type":"string","format":"date-time","nullable":true},"stale":{"type":"boolean"},"stale_after_ms":{"type":"integer"},"configured_source_count":{"type":"integer"},"active_source_count":{"type":"integer"},"failing_source_count":{"type":"integer"},"needs_bootstrap":{"type":"boolean"},"source_mode":{"type":"string","enum":["database","empty"]}}},"Decree":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"issuing_body":{"type":"string"},"country":{"type":"string"},"decree_type":{"type":"string","enum":["military","evacuation","ceasefire","sanctions","statement"]},"issued_at":{"type":"string","format":"date-time"},"summary":{"type":"string"},"full_text":{"type":"string","nullable":true},"source_url":{"type":"string","nullable":true},"is_manual":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"DecreeListResponse":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Decree"}}}}]},"DashboardStats":{"type":"object","properties":{"total_strikes":{"type":"integer"},"total_killed":{"type":"integer"},"total_wounded":{"type":"integer"},"active_alerts":{"type":"integer"},"articles_today":{"type":"integer"},"last_strike_at":{"type":"string","format":"date-time","nullable":true}}},"StatsResponse":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardStats"}}}]}}}}