{"openapi":"3.1.0","info":{"title":"BuildingData External API","description":"Stable API for customer and integrator applications built on normalized BuildingData engineering data. The API exposes Customer Central resources without exposing Global Engineering, IAM administration, Node lifecycle, industrial protocols or internal persistence interfaces.","version":"0.1.0"},"servers":[{"url":"https://api.buildingdata.ru","description":"BuildingData External API"}],"paths":{"/health":{"get":{"tags":["system"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalHealth"}}}}}}},"/v1/sites":{"get":{"tags":["objects"],"summary":"List accessible Sites","operationId":"sites_v1_sites_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ExternalSite"},"type":"array","title":"Response Sites V1 Sites Get"}}}}},"security":[{"ExternalClientBearer":[]}]}},"/v1/equipment":{"get":{"tags":["objects"],"summary":"List normalized equipment","operationId":"equipment_v1_equipment_get","security":[{"ExternalClientBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Site Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"default":1000,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalEquipment"},"title":"Response Equipment V1 Equipment Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/points":{"get":{"tags":["objects"],"summary":"List normalized points","operationId":"points_v1_points_get","security":[{"ExternalClientBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Site Id"}},{"name":"equipment_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Equipment Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"default":2000,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalPoint"},"title":"Response Points V1 Points Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/current":{"get":{"tags":["telemetry"],"summary":"Get latest values","description":"Returns the latest stored value for normalized points within the client's Site scope. Each value carries timestamp, quality and engineering unit.","operationId":"current_values_v1_current_get","security":[{"ExternalClientBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Site Id"}},{"name":"equipment_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Equipment Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"default":2000,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalCurrentValue"},"title":"Response Current Values V1 Current Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/history/{point_id}":{"get":{"tags":["telemetry"],"summary":"Get point history","operationId":"history_v1_history__point_id__get","security":[{"ExternalClientBearer":[]}],"parameters":[{"name":"point_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Point Id"}},{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start"}},{"name":"end","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End"}},{"name":"bucket","in":"query","required":false,"schema":{"enum":["raw","1m","5m","15m","1h"],"type":"string","default":"5m","title":"Bucket"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"default":5000,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/anomalies":{"get":{"tags":["analytics"],"summary":"List active anomalies","operationId":"anomalies_v1_anomalies_get","security":[{"ExternalClientBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Site Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":200,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalAnomaly"},"title":"Response Anomalies V1 Anomalies Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/kpis/summary":{"get":{"tags":["analytics"],"summary":"Get Site health summary","operationId":"kpi_summary_v1_kpis_summary_get","security":[{"ExternalClientBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Site Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalSiteKpi"},"title":"Response Kpi Summary V1 Kpis Summary Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/semantic/sites/{site_id}":{"get":{"tags":["semantics"],"summary":"Get published Site semantic model","description":"Returns the currently published immutable semantic model for the Site. Draft authoring, mappings, Node configuration and Engineering controls are not exposed through this API.","operationId":"semantic_model_v1_semantic_sites__site_id__get","security":[{"ExternalClientBearer":[]}],"parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Site Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalSemanticModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/operational/incidents":{"get":{"tags":["operations"],"summary":"List incidents","operationId":"incidents_v1_operational_incidents_get","security":[{"ExternalClientBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Site Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":200,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalIncident"},"title":"Response Incidents V1 Operational Incidents Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/operational/work-orders":{"get":{"tags":["operations"],"summary":"List work orders","operationId":"work_orders_v1_operational_work_orders_get","security":[{"ExternalClientBearer":[]}],"parameters":[{"name":"site_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Site Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":200,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalWorkOrder"},"title":"Response Work Orders V1 Operational Work Orders Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ExternalAnomaly":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"site_id":{"type":"string","format":"uuid","title":"Site Id"},"equipment_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Equipment Id"},"point_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Point Id"},"code":{"type":"string","title":"Code"},"title":{"type":"string","title":"Title"},"description":{"type":"string","title":"Description"},"severity":{"type":"string","enum":["info","warning","critical"],"title":"Severity"},"status":{"type":"string","enum":["active","acknowledged","resolved"],"title":"Status"},"detected_at":{"type":"string","format":"date-time","title":"Detected At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"evidence":{"additionalProperties":true,"type":"object","title":"Evidence"}},"type":"object","required":["id","site_id","code","title","description","severity","status","detected_at","updated_at"],"title":"ExternalAnomaly"},"ExternalCurrentValue":{"properties":{"point_id":{"type":"string","format":"uuid","title":"Point Id"},"point_name":{"type":"string","title":"Point Name"},"equipment_id":{"type":"string","format":"uuid","title":"Equipment Id"},"equipment_name":{"type":"string","title":"Equipment Name"},"site_id":{"type":"string","format":"uuid","title":"Site Id"},"ts":{"type":"string","format":"date-time","title":"Ts"},"value_num":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value Num"},"value_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value Text"},"quality":{"type":"string","title":"Quality"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit"}},"type":"object","required":["point_id","point_name","equipment_id","equipment_name","site_id","ts","quality"],"title":"ExternalCurrentValue"},"ExternalEquipment":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"external_id":{"type":"string","title":"External Id"},"site_id":{"type":"string","format":"uuid","title":"Site Id"},"name":{"type":"string","title":"Name"},"equipment_type":{"type":"string","title":"Equipment Type"}},"type":"object","required":["id","external_id","site_id","name","equipment_type"],"title":"ExternalEquipment"},"ExternalHealth":{"properties":{"status":{"type":"string","enum":["ok","degraded"],"title":"Status"},"version":{"type":"string","title":"Version"},"release_id":{"type":"string","title":"Release Id"},"git_sha":{"type":"string","title":"Git Sha"},"schema_version":{"type":"string","title":"Schema Version"}},"type":"object","required":["status","version","release_id","git_sha","schema_version"],"title":"ExternalHealth"},"ExternalHistoryItem":{"properties":{"ts":{"type":"string","format":"date-time","title":"Ts"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"quality":{"type":"string","title":"Quality"}},"type":"object","required":["ts","quality"],"title":"ExternalHistoryItem"},"ExternalHistoryResponse":{"properties":{"point_id":{"type":"string","format":"uuid","title":"Point Id"},"point_external_id":{"type":"string","title":"Point External Id"},"point_name":{"type":"string","title":"Point Name"},"equipment_id":{"type":"string","format":"uuid","title":"Equipment Id"},"site_id":{"type":"string","format":"uuid","title":"Site Id"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit"},"bucket":{"type":"string","enum":["raw","1m","5m","15m","1h"],"title":"Bucket"},"start":{"type":"string","format":"date-time","title":"Start"},"end":{"type":"string","format":"date-time","title":"End"},"items":{"items":{"$ref":"#/components/schemas/ExternalHistoryItem"},"type":"array","title":"Items"}},"type":"object","required":["point_id","point_external_id","point_name","equipment_id","site_id","bucket","start","end","items"],"title":"ExternalHistoryResponse"},"ExternalIncident":{"properties":{"incident_id":{"type":"string","title":"Incident Id"},"site_id":{"type":"string","format":"uuid","title":"Site Id"},"site_external_id":{"type":"string","title":"Site External Id"},"system":{"type":"string","title":"System"},"equipment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Equipment"},"point_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Point Id"},"severity":{"type":"string","title":"Severity"},"workflow_status":{"type":"string","title":"Workflow Status"},"title":{"type":"string","title":"Title"},"source":{"type":"string","title":"Source"},"version":{"type":"integer","title":"Version"},"work_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Work Order Id"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["incident_id","site_id","site_external_id","system","severity","workflow_status","title","source","version","updated_at"],"title":"ExternalIncident"},"ExternalPoint":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"external_id":{"type":"string","title":"External Id"},"equipment_id":{"type":"string","format":"uuid","title":"Equipment Id"},"site_id":{"type":"string","format":"uuid","title":"Site Id"},"name":{"type":"string","title":"Name"},"point_type":{"type":"string","title":"Point Type"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit"}},"type":"object","required":["id","external_id","equipment_id","site_id","name","point_type"],"title":"ExternalPoint"},"ExternalSemanticModel":{"properties":{"site_id":{"type":"string","format":"uuid","title":"Site Id"},"site_external_id":{"type":"string","title":"Site External Id"},"site_name":{"type":"string","title":"Site Name"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"model_version":{"type":"string","title":"Model Version"},"schema_version":{"type":"string","title":"Schema Version"},"content_hash":{"type":"string","title":"Content Hash"},"published_at":{"type":"string","format":"date-time","title":"Published At"},"content":{"additionalProperties":true,"type":"object","title":"Content"}},"type":"object","required":["site_id","site_external_id","site_name","organization_id","model_version","schema_version","content_hash","published_at","content"],"title":"ExternalSemanticModel"},"ExternalSite":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"external_id":{"type":"string","title":"External Id"},"name":{"type":"string","title":"Name"},"timezone":{"type":"string","title":"Timezone"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"organization_name":{"type":"string","title":"Organization Name"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","external_id","name","timezone","organization_id","organization_name","created_at","updated_at"],"title":"ExternalSite"},"ExternalSiteKpi":{"properties":{"site_id":{"type":"string","format":"uuid","title":"Site Id"},"site_name":{"type":"string","title":"Site Name"},"equipment_count":{"type":"integer","title":"Equipment Count"},"point_count":{"type":"integer","title":"Point Count"},"fresh_points":{"type":"integer","title":"Fresh Points"},"stale_points":{"type":"integer","title":"Stale Points"},"active_anomalies":{"type":"integer","title":"Active Anomalies"},"critical_anomalies":{"type":"integer","title":"Critical Anomalies"},"warning_anomalies":{"type":"integer","title":"Warning Anomalies"},"health_score":{"type":"number","title":"Health Score"},"latest_sample_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Latest Sample At"}},"type":"object","required":["site_id","site_name","equipment_count","point_count","fresh_points","stale_points","active_anomalies","critical_anomalies","warning_anomalies","health_score"],"title":"ExternalSiteKpi"},"ExternalWorkOrder":{"properties":{"work_order_id":{"type":"string","title":"Work Order Id"},"incident_id":{"type":"string","title":"Incident Id"},"site_id":{"type":"string","format":"uuid","title":"Site Id"},"site_external_id":{"type":"string","title":"Site External Id"},"title":{"type":"string","title":"Title"},"system":{"type":"string","title":"System"},"equipment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Equipment"},"point_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Point Id"},"priority":{"type":"string","title":"Priority"},"assignee":{"type":"string","title":"Assignee"},"sla":{"type":"string","title":"Sla"},"status":{"type":"string","title":"Status"},"action":{"type":"string","title":"Action"},"acceptance_criterion":{"type":"string","title":"Acceptance Criterion"},"history":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"History"},"version":{"type":"integer","title":"Version"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["work_order_id","incident_id","site_id","site_external_id","title","system","priority","assignee","sla","status","action","acceptance_criterion","version","updated_at"],"title":"ExternalWorkOrder"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ExternalClientBearer":{"type":"http","description":"Use a BuildingData External API credential in the form <client_id>.<client_secret>.","scheme":"bearer"}}},"tags":[{"name":"objects","description":"Normalized Site, Equipment and Point catalog."},{"name":"telemetry","description":"Current values and time-series history from normalized points."},{"name":"semantics","description":"Published read-only semantic model for a Site."},{"name":"analytics","description":"Anomalies and deterministic Site health indicators."},{"name":"operations","description":"Read-only incidents and work orders from the operational contour."}]}