{"openapi":"3.0.3","info":{"title":"BioSitia API","version":"1.0.0","description":"Conservation-risk assessment for renewable-energy site planning. Helps\nbalance wind / solar / transmission development with wildlife protection.\n\nCurrent focus: raptor sensitivity (Steller's Sea Eagle and other Japanese\nhigh-conservation-value species). Combines protected-area boundaries,\nspecies range data, and seasonal breeding windows to produce a\npoint-or-area risk score that planners can use before site walks.\n","contact":{"name":"BioSitia Support","email":"support@biositia.org"},"license":{"name":"MIT License","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://api.biositia.org","description":"Production server"},{"url":"http://localhost:8787","description":"Local development"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/health":{"get":{"summary":"Health check","operationId":"healthCheck","tags":["System"],"security":[],"responses":{"200":{"description":"Service healthy"}}}},"/internal/health":{"get":{"summary":"Detailed internal health (DB, cache, dependencies).","description":"Internal-tier health endpoint with per-dependency status (D1, KV,\nupstream species data, protected-area dataset). Use for monitoring\ndashboards, not as a load-balancer probe.\n","operationId":"getInternalHealth","tags":["System"],"security":[],"responses":{"200":{"description":"Internal health snapshot"},"503":{"description":"One or more dependencies unhealthy"}}}},"/v1/metadata/enums":{"get":{"summary":"List every enum used by the BioSitia API.","description":"Returns the directory of enums (species IDs, sensitivity tiers,\nprotected-area types, recommendation categories) with localised\nlabels. Use when building UIs that mirror the API's vocabulary.\n","operationId":"listEnums","tags":["Metadata"],"security":[],"responses":{"200":{"description":"Enum metadata"}}}},"/v1/metadata/enums/{name}":{"get":{"summary":"Get one BioSitia enum (species_id, sensitivity_tier, etc.) by name.","operationId":"getEnum","description":"Returns localised values for one enum. See `listEnums` for the\ndirectory of available enum names.\n","tags":["Metadata"],"security":[],"parameters":[{"name":"name","in":"path","required":true,"description":"Enum identifier (e.g. `species_id`, `sensitivity_tier`).","example":"species_id","schema":{"type":"string"}}],"responses":{"200":{"description":"Enum values"}}}},"/v1/biositing/risk":{"get":{"summary":"Assess conservation risk at a single (lat, lon) point.","description":"Returns the conservation-risk score for a development site at the\ngiven coordinate. Combines per-species sensitivity, protected-area\nproximity, and seasonal breeding windows. Coverage: Japan only;\nreturns \"outside_coverage\" outside Japan.\n\nFor polygon (area) risk, use `assessAreaRisk` (POST). For multi-site\nprioritisation, use `listPrioritySites`.\n","operationId":"assessPointRisk","tags":["Risk Assessment"],"security":[],"parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude in decimal degrees, WGS84.","example":43.39,"schema":{"type":"number","format":"double","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":true,"description":"Longitude in decimal degrees, WGS84.","example":144.85,"schema":{"type":"number","format":"double","minimum":-180,"maximum":180}}],"responses":{"200":{"description":"Risk score and contributing factors"},"400":{"description":"Validation error (lat/lon out of range or missing)"}}}},"/v1/biositing/risk/area":{"post":{"summary":"Assess conservation risk over a polygon (multi-point area).","description":"Computes the worst-case and average risk over a polygon, sampled at\na grid resolution. Use for evaluating an entire candidate site\n(vs `assessPointRisk` which only checks one coordinate).\n\nPolygon must be a closed GeoJSON Polygon with WGS84 coordinates.\n","operationId":"assessAreaRisk","tags":["Risk Assessment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["polygon"],"properties":{"polygon":{"type":"object","description":"GeoJSON Polygon (rings of [lon, lat] pairs)."},"grid_step_km":{"type":"number","description":"Sampling interval inside the polygon, in km.","default":1}}}}}},"responses":{"200":{"description":"Aggregated area-risk results"},"400":{"description":"Polygon invalid or malformed"}}}},"/v1/sites/priority":{"get":{"summary":"List candidate sites pre-ranked by composite risk score.","description":"Returns the curated list of candidate development sites ranked by\nBioSitia's composite risk score (lower = safer). Useful for\nidentifying low-conflict sites without running ad-hoc assessments\nacross many points.\n\nFilterable by region and by species of concern.\n","operationId":"listPrioritySites","tags":["Conservation"],"security":[],"parameters":[{"name":"prefecture","in":"query","required":false,"description":"Filter to one Japanese prefecture (e.g. `北海道`).","schema":{"type":"string"}},{"name":"species","in":"query","required":false,"description":"Restrict scoring to a single species ID.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"Ranked priority sites"}}}},"/v1/sites/priority/summary":{"get":{"summary":"Aggregate priority-sites statistics by region or species.","description":"Returns summary statistics over the priority-sites list — counts by\nrisk tier, by prefecture, by species. Use for dashboards and SLO\nreporting; for individual site records use `listPrioritySites`.\n","operationId":"getPrioritySitesSummary","tags":["Conservation"],"security":[],"responses":{"200":{"description":"Aggregated statistics"}}}},"/v1/observable/":{"get":{"summary":"Get observable-pattern status for the API (data freshness).","description":"Returns the observable-pattern snapshot for BioSitia's data\npipeline — last refresh time per upstream source, current backlog,\nany active anomalies. Use as a freshness signal for downstream\ndashboards.\n","operationId":"getObservablePattern","tags":["System"],"security":[],"responses":{"200":{"description":"Observable-pattern snapshot"}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication. Obtain from the PPN Hub developer portal."}}},"tags":[{"name":"System","description":"Health and observable-pattern endpoints."},{"name":"Risk Assessment","description":"Point and area conservation-risk scoring."},{"name":"Conservation","description":"Pre-ranked priority sites for renewable-energy planning."},{"name":"Metadata","description":"Localised enum lookups."}]}