Building Energy & Facilities Intelligence API Documentation

Read supplied meter readings, bills, tariffs, equipment history, and occupancy to flag unusual usage and maintenance needs without inventing tariffs or savings. Payment is the exact USDC price on Base with x402.

{
  "meters": [
    {
      "id": "M-1",
      "buildingId": "B-1",
      "name": "Main electric",
      "utility": "electric",
      "unit": "kWh"
    }
  ],
  "readings": [
    {
      "id": "R-1",
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-11-01",
      "value": 1000,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "id": "R-2",
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-11-08",
      "value": 1140,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "id": "R-3",
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-11-15",
      "value": 1280,
      "unit": "kWh",
      "cumulative": true
    }
  ],
  "tariffs": [
    {
      "id": "T-1",
      "utility": "electric",
      "unit": "kWh",
      "rate": 0.12,
      "fixedCharge": 10,
      "asOf": "2026-11-01"
    }
  ]
}

{
  "checkedAt": "2026-11-04T21:00:00.000Z",
  "status": "analyzed",
  "items": [
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh",
      "intervalCount": 2,
      "totalQuantity": 280,
      "totalQuantitySupplied": true,
      "daySpan": 14,
      "daySpanSupplied": true,
      "averagePerDay": 20,
      "averagePerDaySupplied": true,
      "cost": 43.6,
      "costSupplied": true,
      "tariffId": "T-1",
      "tariffInvented": false,
      "periodStart": "2026-11-01",
      "periodEnd": "2026-11-15"
    }
  ],
  "billCount": 0,
  "tariffInvented": false,
  "performanceInvented": false,
  "savingsGuaranteed": false,
  "equipmentControlled": false,
  "findings": [],
  "limitations": [
    "Meter readings, bills, tariffs, equipment records, and occupancy rows are copied only from labeled fields supplied by the caller.",
    "Consumption and cost use supplied units and tariffs only. Missing tariffs are not invented.",
    "Unusual usage is compared against a baseline calculated from supplied readings for the same meter or utility.",
    "Buildings are compared only when measurement periods and units are compatible.",
    "Equipment performance and savings are never invented. HVAC and connected equipment are never controlled."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/building-energy/consumption-analyze" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "meters": [
    {
      "id": "M-1",
      "buildingId": "B-1",
      "name": "Main electric",
      "utility": "electric",
      "unit": "kWh"
    }
  ],
  "readings": [
    {
      "id": "R-1",
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-11-01",
      "value": 1000,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "id": "R-2",
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-11-08",
      "value": 1140,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "id": "R-3",
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-11-15",
      "value": 1280,
      "unit": "kWh",
      "cumulative": true
    }
  ],
  "tariffs": [
    {
      "id": "T-1",
      "utility": "electric",
      "unit": "kWh",
      "rate": 0.12,
      "fixedCharge": 10,
      "asOf": "2026-11-01"
    }
  ]
}
JSON

{
  "meters": [
    {
      "id": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh"
    }
  ],
  "readings": [
    {
      "meterId": "M-1",
      "at": "2026-10-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-08",
      "value": 70,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-15",
      "value": 140,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-22",
      "value": 210,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-29",
      "value": 420,
      "unit": "kWh",
      "cumulative": true
    }
  ]
}

{
  "checkedAt": "2026-11-04T21:00:00.000Z",
  "status": "detected",
  "unusualCount": 1,
  "items": [
    {
      "id": "AN-1",
      "meterId": "M-1",
      "buildingId": "",
      "from": "2026-10-01",
      "to": "2026-10-08",
      "quantity": 70,
      "unit": "kWh",
      "dailyQuantity": 10,
      "baselineMean": 16.6667,
      "baselineMeanSupplied": true,
      "baselineMethod": "leave_one_out_mean_daily",
      "score": -0.5774,
      "scoreSupplied": true,
      "unusual": false,
      "explanation": "Daily usage 10 kWh is within 2 standard deviations of leave-one-out baseline mean 16.6667 (leave_one_out_mean_daily).",
      "tariffInvented": false,
      "savingsGuaranteed": false
    },
    {
      "id": "AN-2",
      "meterId": "M-1",
      "buildingId": "",
      "from": "2026-10-08",
      "to": "2026-10-15",
      "quantity": 70,
      "unit": "kWh",
      "dailyQuantity": 10,
      "baselineMean": 16.6667,
      "baselineMeanSupplied": true,
      "baselineMethod": "leave_one_out_mean_daily",
      "score": -0.5774,
      "scoreSupplied": true,
      "unusual": false,
      "explanation": "Daily usage 10 kWh is within 2 standard deviations of leave-one-out baseline mean 16.6667 (leave_one_out_mean_daily).",
      "tariffInvented": false,
      "savingsGuaranteed": false
    },
    {
      "id": "AN-3",
      "meterId": "M-1",
      "buildingId": "",
      "from": "2026-10-15",
      "to": "2026-10-22",
      "quantity": 70,
      "unit": "kWh",
      "dailyQuantity": 10,
      "baselineMean": 16.6667,
      "baselineMeanSupplied": true,
      "baselineMethod": "leave_one_out_mean_daily",
      "score": -0.5774,
      "scoreSupplied": true,
      "unusual": false,
      "explanation": "Daily usage 10 kWh is within 2 standard deviations of leave-one-out baseline mean 16.6667 (leave_one_out_mean_daily).",
      "tariffInvented": false,
      "savingsGuaranteed": false
    },
    {
      "id": "AN-4",
      "meterId": "M-1",
      "buildingId": "",
      "from": "2026-10-22",
      "to": "2026-10-29",
      "quantity": 210,
      "unit": "kWh",
      "dailyQuantity": 30,
      "baselineMean": 10,
      "baselineMeanSupplied": true,
      "baselineMethod": "leave_one_out_mean_daily",
      "score": 3,
      "scoreSupplied": true,
      "unusual": true,
      "explanation": "Daily usage 30 kWh is outside 50–150% of leave-one-out baseline mean 10 (leave_one_out_mean_daily; stdev unavailable).",
      "tariffInvented": false,
      "savingsGuaranteed": false
    }
  ],
  "tariffInvented": false,
  "performanceInvented": false,
  "savingsGuaranteed": false,
  "equipmentControlled": false,
  "findings": [
    {
      "kind": "observation",
      "code": "usage_anomaly",
      "subject": "M-1",
      "detail": "Daily usage 30 kWh is outside 50–150% of leave-one-out baseline mean 10 (leave_one_out_mean_daily; stdev unavailable)."
    }
  ],
  "limitations": [
    "Meter readings, bills, tariffs, equipment records, and occupancy rows are copied only from labeled fields supplied by the caller.",
    "Consumption and cost use supplied units and tariffs only. Missing tariffs are not invented.",
    "Unusual usage is compared against a baseline calculated from supplied readings for the same meter or utility.",
    "Buildings are compared only when measurement periods and units are compatible.",
    "Equipment performance and savings are never invented. HVAC and connected equipment are never controlled."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/building-energy/meter-reading-anomaly-detect" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "meters": [
    {
      "id": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh"
    }
  ],
  "readings": [
    {
      "meterId": "M-1",
      "at": "2026-10-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-08",
      "value": 70,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-15",
      "value": 140,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-22",
      "value": 210,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-29",
      "value": 420,
      "unit": "kWh",
      "cumulative": true
    }
  ]
}
JSON

{
  "equipment": [
    {
      "id": "EQ-1",
      "buildingId": "B-1",
      "name": "AHU-1",
      "type": "hvac",
      "efficiency": 2.8,
      "ratedEfficiency": 3.5,
      "supplyTemp": 14,
      "returnTemp": 14.5,
      "setpoint": 12,
      "runtimeHours": 9000
    },
    {
      "id": "EQ-2",
      "buildingId": "B-1",
      "name": "Chiller-1",
      "type": "chiller",
      "efficiency": 5.1,
      "ratedEfficiency": 5.2,
      "supplyTemp": 7,
      "returnTemp": 12,
      "setpoint": 7
    }
  ]
}

{
  "checkedAt": "2026-11-04T21:00:00.000Z",
  "status": "analyzed",
  "flagCount": 1,
  "items": [
    {
      "id": "EQ-1",
      "buildingId": "B-1",
      "name": "AHU-1",
      "type": "hvac",
      "ratedCapacity": 0,
      "ratedCapacitySupplied": false,
      "capacityUnit": "",
      "efficiency": 2.8,
      "efficiencySupplied": true,
      "ratedEfficiency": 3.5,
      "ratedEfficiencySupplied": true,
      "efficiencyRatio": 0.8,
      "efficiencyRatioSupplied": true,
      "supplyTemp": 14,
      "supplyTempSupplied": true,
      "returnTemp": 14.5,
      "returnTempSupplied": true,
      "setpoint": 12,
      "setpointSupplied": true,
      "tempDelta": 0.5,
      "tempDeltaSupplied": true,
      "setpointGap": 2,
      "setpointGapSupplied": true,
      "runtimeHours": 9000,
      "runtimeHoursSupplied": true,
      "flags": [
        "below_rated_efficiency",
        "low_temp_delta"
      ],
      "performanceInvented": false,
      "equipmentControlled": false,
      "savingsGuaranteed": false
    },
    {
      "id": "EQ-2",
      "buildingId": "B-1",
      "name": "Chiller-1",
      "type": "chiller",
      "ratedCapacity": 0,
      "ratedCapacitySupplied": false,
      "capacityUnit": "",
      "efficiency": 5.1,
      "efficiencySupplied": true,
      "ratedEfficiency": 5.2,
      "ratedEfficiencySupplied": true,
      "efficiencyRatio": 0.9808,
      "efficiencyRatioSupplied": true,
      "supplyTemp": 7,
      "supplyTempSupplied": true,
      "returnTemp": 12,
      "returnTempSupplied": true,
      "setpoint": 7,
      "setpointSupplied": true,
      "tempDelta": 5,
      "tempDeltaSupplied": true,
      "setpointGap": 0,
      "setpointGapSupplied": true,
      "runtimeHours": 0,
      "runtimeHoursSupplied": false,
      "flags": [],
      "performanceInvented": false,
      "equipmentControlled": false,
      "savingsGuaranteed": false
    }
  ],
  "tariffInvented": false,
  "performanceInvented": false,
  "savingsGuaranteed": false,
  "equipmentControlled": false,
  "findings": [],
  "limitations": [
    "Meter readings, bills, tariffs, equipment records, and occupancy rows are copied only from labeled fields supplied by the caller.",
    "Consumption and cost use supplied units and tariffs only. Missing tariffs are not invented.",
    "Unusual usage is compared against a baseline calculated from supplied readings for the same meter or utility.",
    "Buildings are compared only when measurement periods and units are compatible.",
    "Equipment performance and savings are never invented. HVAC and connected equipment are never controlled."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/building-energy/hvac-performance-analyze" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "equipment": [
    {
      "id": "EQ-1",
      "buildingId": "B-1",
      "name": "AHU-1",
      "type": "hvac",
      "efficiency": 2.8,
      "ratedEfficiency": 3.5,
      "supplyTemp": 14,
      "returnTemp": 14.5,
      "setpoint": 12,
      "runtimeHours": 9000
    },
    {
      "id": "EQ-2",
      "buildingId": "B-1",
      "name": "Chiller-1",
      "type": "chiller",
      "efficiency": 5.1,
      "ratedEfficiency": 5.2,
      "supplyTemp": 7,
      "returnTemp": 12,
      "setpoint": 7
    }
  ]
}
JSON

{
  "meters": [
    {
      "id": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh"
    }
  ],
  "readings": [
    {
      "meterId": "M-1",
      "at": "2026-10-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-08",
      "value": 70,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-15",
      "value": 140,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-22",
      "value": 210,
      "unit": "kWh",
      "cumulative": true
    }
  ]
}

{
  "checkedAt": "2026-11-04T21:00:00.000Z",
  "status": "calculated",
  "items": [
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh",
      "sampleCount": 3,
      "baselineMean": 10,
      "baselineMeanSupplied": true,
      "baselineStdev": 0,
      "baselineStdevSupplied": true,
      "baselineMethod": "mean_daily_interval",
      "comparisonUnit": "kWh",
      "tariffInvented": false,
      "performanceInvented": false,
      "savingsGuaranteed": false
    }
  ],
  "tariffInvented": false,
  "performanceInvented": false,
  "savingsGuaranteed": false,
  "equipmentControlled": false,
  "findings": [],
  "limitations": [
    "Meter readings, bills, tariffs, equipment records, and occupancy rows are copied only from labeled fields supplied by the caller.",
    "Consumption and cost use supplied units and tariffs only. Missing tariffs are not invented.",
    "Unusual usage is compared against a baseline calculated from supplied readings for the same meter or utility.",
    "Buildings are compared only when measurement periods and units are compatible.",
    "Equipment performance and savings are never invented. HVAC and connected equipment are never controlled."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/building-energy/baseline-calculate" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "meters": [
    {
      "id": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh"
    }
  ],
  "readings": [
    {
      "meterId": "M-1",
      "at": "2026-10-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-08",
      "value": 70,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-15",
      "value": 140,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "at": "2026-10-22",
      "value": 210,
      "unit": "kWh",
      "cumulative": true
    }
  ]
}
JSON

{
  "tariffs": [
    {
      "id": "T-1",
      "utility": "electric",
      "unit": "kWh",
      "rate": 0.1,
      "fixedCharge": 20,
      "asOf": "2026-11-01"
    }
  ],
  "bills": [
    {
      "id": "BILL-1",
      "buildingId": "B-1",
      "utility": "electric",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-31",
      "quantity": 1000,
      "unit": "kWh",
      "cost": 150
    },
    {
      "id": "BILL-2",
      "buildingId": "B-1",
      "utility": "electric",
      "periodStart": "2026-09-01",
      "periodEnd": "2026-09-30",
      "quantity": 900,
      "unit": "kWh",
      "cost": 110
    }
  ]
}

{
  "checkedAt": "2026-11-04T21:00:00.000Z",
  "status": "detected",
  "varianceCount": 1,
  "items": [
    {
      "billId": "BILL-1",
      "buildingId": "B-1",
      "utility": "electric",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-31",
      "quantity": 1000,
      "quantitySupplied": true,
      "unit": "kWh",
      "actualCost": 150,
      "actualCostSupplied": true,
      "expectedCost": 120,
      "expectedCostSupplied": true,
      "variance": 30,
      "varianceSupplied": true,
      "variancePct": 0.25,
      "variancePctSupplied": true,
      "tariffId": "T-1",
      "tariffRate": 0.1,
      "tariffRateSupplied": true,
      "tariffInvented": false,
      "savingsGuaranteed": false
    },
    {
      "billId": "BILL-2",
      "buildingId": "B-1",
      "utility": "electric",
      "periodStart": "2026-09-01",
      "periodEnd": "2026-09-30",
      "quantity": 900,
      "quantitySupplied": true,
      "unit": "kWh",
      "actualCost": 110,
      "actualCostSupplied": true,
      "expectedCost": 110,
      "expectedCostSupplied": true,
      "variance": 0,
      "varianceSupplied": true,
      "variancePct": 0,
      "variancePctSupplied": true,
      "tariffId": "T-1",
      "tariffRate": 0.1,
      "tariffRateSupplied": true,
      "tariffInvented": false,
      "savingsGuaranteed": false
    }
  ],
  "tariffInvented": false,
  "performanceInvented": false,
  "savingsGuaranteed": false,
  "equipmentControlled": false,
  "findings": [
    {
      "kind": "observation",
      "code": "cost_variance",
      "subject": "BILL-1",
      "detail": "Billed cost differs from tariff-based expected cost by 25%."
    }
  ],
  "limitations": [
    "Meter readings, bills, tariffs, equipment records, and occupancy rows are copied only from labeled fields supplied by the caller.",
    "Consumption and cost use supplied units and tariffs only. Missing tariffs are not invented.",
    "Unusual usage is compared against a baseline calculated from supplied readings for the same meter or utility.",
    "Buildings are compared only when measurement periods and units are compatible.",
    "Equipment performance and savings are never invented. HVAC and connected equipment are never controlled."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/building-energy/cost-variance-detect" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "tariffs": [
    {
      "id": "T-1",
      "utility": "electric",
      "unit": "kWh",
      "rate": 0.1,
      "fixedCharge": 20,
      "asOf": "2026-11-01"
    }
  ],
  "bills": [
    {
      "id": "BILL-1",
      "buildingId": "B-1",
      "utility": "electric",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-31",
      "quantity": 1000,
      "unit": "kWh",
      "cost": 150
    },
    {
      "id": "BILL-2",
      "buildingId": "B-1",
      "utility": "electric",
      "periodStart": "2026-09-01",
      "periodEnd": "2026-09-30",
      "quantity": 900,
      "unit": "kWh",
      "cost": 110
    }
  ]
}
JSON

{
  "asOf": "2026-11-10",
  "equipment": [
    {
      "id": "EQ-1",
      "buildingId": "B-1",
      "name": "AHU-1",
      "type": "hvac",
      "lastServiceAt": "2025-01-01",
      "nextServiceDue": "2026-10-01",
      "faultCount": 4,
      "efficiency": 2.5,
      "ratedEfficiency": 3.5,
      "runtimeHours": 9500
    },
    {
      "id": "EQ-2",
      "buildingId": "B-1",
      "name": "Pump-1",
      "type": "pump",
      "lastServiceAt": "2026-09-01",
      "nextServiceDue": "2027-01-01",
      "faultCount": 0,
      "runtimeHours": 1000
    }
  ]
}

{
  "checkedAt": "2026-11-04T21:00:00.000Z",
  "status": "prioritized",
  "highCount": 1,
  "items": [
    {
      "id": "EQ-1",
      "buildingId": "B-1",
      "name": "AHU-1",
      "type": "hvac",
      "lastServiceAt": "2025-01-01",
      "nextServiceDue": "2026-10-01",
      "overdueDays": 40,
      "overdueDaysSupplied": true,
      "daysSinceService": 678,
      "daysSinceServiceSupplied": true,
      "faultCount": 4,
      "faultCountSupplied": true,
      "runtimeHours": 9500,
      "runtimeHoursSupplied": true,
      "score": 90,
      "priority": "high",
      "reasons": [
        "service overdue by 40 days against supplied due date",
        "4 supplied fault count",
        "measured efficiency below 90% of rated efficiency",
        "runtime hours at or above 8000"
      ],
      "performanceInvented": false,
      "equipmentControlled": false,
      "savingsGuaranteed": false,
      "rank": 1
    },
    {
      "id": "EQ-2",
      "buildingId": "B-1",
      "name": "Pump-1",
      "type": "pump",
      "lastServiceAt": "2026-09-01",
      "nextServiceDue": "2027-01-01",
      "overdueDays": 0,
      "overdueDaysSupplied": false,
      "daysSinceService": 70,
      "daysSinceServiceSupplied": true,
      "faultCount": 0,
      "faultCountSupplied": true,
      "runtimeHours": 1000,
      "runtimeHoursSupplied": true,
      "score": 0,
      "priority": "low",
      "reasons": [],
      "performanceInvented": false,
      "equipmentControlled": false,
      "savingsGuaranteed": false,
      "rank": 2
    }
  ],
  "tariffInvented": false,
  "performanceInvented": false,
  "savingsGuaranteed": false,
  "equipmentControlled": false,
  "findings": [
    {
      "kind": "observation",
      "code": "no_priority_signal",
      "subject": "EQ-2",
      "detail": "No overdue service, faults, efficiency drop, or high runtime was present in supplied fields."
    }
  ],
  "limitations": [
    "Meter readings, bills, tariffs, equipment records, and occupancy rows are copied only from labeled fields supplied by the caller.",
    "Consumption and cost use supplied units and tariffs only. Missing tariffs are not invented.",
    "Unusual usage is compared against a baseline calculated from supplied readings for the same meter or utility.",
    "Buildings are compared only when measurement periods and units are compatible.",
    "Equipment performance and savings are never invented. HVAC and connected equipment are never controlled."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/building-energy/equipment-maintenance-priority" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "asOf": "2026-11-10",
  "equipment": [
    {
      "id": "EQ-1",
      "buildingId": "B-1",
      "name": "AHU-1",
      "type": "hvac",
      "lastServiceAt": "2025-01-01",
      "nextServiceDue": "2026-10-01",
      "faultCount": 4,
      "efficiency": 2.5,
      "ratedEfficiency": 3.5,
      "runtimeHours": 9500
    },
    {
      "id": "EQ-2",
      "buildingId": "B-1",
      "name": "Pump-1",
      "type": "pump",
      "lastServiceAt": "2026-09-01",
      "nextServiceDue": "2027-01-01",
      "faultCount": 0,
      "runtimeHours": 1000
    }
  ]
}
JSON

{
  "buildings": [
    {
      "id": "B-1",
      "name": "Tower A"
    },
    {
      "id": "B-2",
      "name": "Tower B"
    }
  ],
  "meters": [
    {
      "id": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh"
    },
    {
      "id": "M-2",
      "buildingId": "B-2",
      "utility": "electric",
      "unit": "kWh"
    }
  ],
  "readings": [
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-11-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-11-08",
      "value": 200,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-2",
      "buildingId": "B-2",
      "at": "2026-11-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-2",
      "buildingId": "B-2",
      "at": "2026-11-08",
      "value": 120,
      "unit": "kWh",
      "cumulative": true
    }
  ],
  "occupancy": [
    {
      "buildingId": "B-1",
      "periodStart": "2026-11-01",
      "periodEnd": "2026-11-08",
      "occupants": 100
    },
    {
      "buildingId": "B-2",
      "periodStart": "2026-11-01",
      "periodEnd": "2026-11-08",
      "occupants": 80
    }
  ]
}

{
  "checkedAt": "2026-11-04T21:00:00.000Z",
  "status": "compared",
  "compatibleCount": 1,
  "items": [
    {
      "leftBuildingId": "B-1",
      "rightBuildingId": "B-2",
      "periodStart": "2026-11-01",
      "periodEnd": "2026-11-08",
      "unit": "kWh",
      "leftQuantity": 200,
      "rightQuantity": 120,
      "leftOccupants": 100,
      "rightOccupants": 80,
      "leftPerOccupant": 2,
      "rightPerOccupant": 1.5,
      "leftPerOccupantSupplied": true,
      "rightPerOccupantSupplied": true,
      "compatible": true,
      "reason": "Compared because overlapping/matching periods and compatible energy units were supplied.",
      "savingsGuaranteed": false,
      "tariffInvented": false
    }
  ],
  "tariffInvented": false,
  "performanceInvented": false,
  "savingsGuaranteed": false,
  "equipmentControlled": false,
  "findings": [
    {
      "kind": "missing",
      "code": "tariff",
      "subject": "M-1",
      "detail": "No supplied tariff matched this meter utility/unit, so cost was not calculated."
    },
    {
      "kind": "missing",
      "code": "tariff",
      "subject": "M-2",
      "detail": "No supplied tariff matched this meter utility/unit, so cost was not calculated."
    }
  ],
  "limitations": [
    "Meter readings, bills, tariffs, equipment records, and occupancy rows are copied only from labeled fields supplied by the caller.",
    "Consumption and cost use supplied units and tariffs only. Missing tariffs are not invented.",
    "Unusual usage is compared against a baseline calculated from supplied readings for the same meter or utility.",
    "Buildings are compared only when measurement periods and units are compatible.",
    "Equipment performance and savings are never invented. HVAC and connected equipment are never controlled."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/building-energy/occupancy-compare" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "buildings": [
    {
      "id": "B-1",
      "name": "Tower A"
    },
    {
      "id": "B-2",
      "name": "Tower B"
    }
  ],
  "meters": [
    {
      "id": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh"
    },
    {
      "id": "M-2",
      "buildingId": "B-2",
      "utility": "electric",
      "unit": "kWh"
    }
  ],
  "readings": [
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-11-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-11-08",
      "value": 200,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-2",
      "buildingId": "B-2",
      "at": "2026-11-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-2",
      "buildingId": "B-2",
      "at": "2026-11-08",
      "value": 120,
      "unit": "kWh",
      "cumulative": true
    }
  ],
  "occupancy": [
    {
      "buildingId": "B-1",
      "periodStart": "2026-11-01",
      "periodEnd": "2026-11-08",
      "occupants": 100
    },
    {
      "buildingId": "B-2",
      "periodStart": "2026-11-01",
      "periodEnd": "2026-11-08",
      "occupants": 80
    }
  ]
}
JSON

{
  "asOf": "2026-11-10",
  "buildings": [
    {
      "id": "B-1",
      "name": "Tower A"
    },
    {
      "id": "B-2",
      "name": "Tower B"
    }
  ],
  "meters": [
    {
      "id": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh"
    },
    {
      "id": "M-2",
      "buildingId": "B-2",
      "utility": "electric",
      "unit": "kWh"
    }
  ],
  "readings": [
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-10-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-10-08",
      "value": 70,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-10-15",
      "value": 140,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-10-22",
      "value": 210,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-10-29",
      "value": 420,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-2",
      "buildingId": "B-2",
      "at": "2026-10-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-2",
      "buildingId": "B-2",
      "at": "2026-10-08",
      "value": 50,
      "unit": "kWh",
      "cumulative": true
    }
  ],
  "tariffs": [
    {
      "id": "T-1",
      "utility": "electric",
      "unit": "kWh",
      "rate": 0.1,
      "fixedCharge": 20
    }
  ],
  "bills": [
    {
      "id": "BILL-1",
      "buildingId": "B-1",
      "utility": "electric",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-31",
      "quantity": 1000,
      "unit": "kWh",
      "cost": 150
    }
  ],
  "equipment": [
    {
      "id": "EQ-1",
      "buildingId": "B-1",
      "name": "AHU-1",
      "type": "hvac",
      "nextServiceDue": "2026-10-01",
      "faultCount": 3,
      "efficiency": 2.5,
      "ratedEfficiency": 3.5,
      "supplyTemp": 14,
      "returnTemp": 14.2,
      "setpoint": 12,
      "runtimeHours": 9000
    }
  ],
  "occupancy": [
    {
      "buildingId": "B-1",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-08",
      "occupants": 100
    },
    {
      "buildingId": "B-2",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-08",
      "occupants": 80
    }
  ]
}

{
  "checkedAt": "2026-11-04T21:00:00.000Z",
  "status": "reported",
  "asOf": "2026-11-10",
  "meterCount": 2,
  "readingCount": 7,
  "unusualCount": 1,
  "hvacFlagCount": 1,
  "costVarianceCount": 1,
  "highMaintenanceCount": 1,
  "compatibleCompareCount": 1,
  "consumption": [
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh",
      "intervalCount": 4,
      "totalQuantity": 420,
      "totalQuantitySupplied": true,
      "daySpan": 28,
      "daySpanSupplied": true,
      "averagePerDay": 15,
      "averagePerDaySupplied": true,
      "cost": 62,
      "costSupplied": true,
      "tariffId": "T-1",
      "tariffInvented": false,
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-29"
    },
    {
      "meterId": "M-2",
      "buildingId": "B-2",
      "utility": "electric",
      "unit": "kWh",
      "intervalCount": 1,
      "totalQuantity": 50,
      "totalQuantitySupplied": true,
      "daySpan": 7,
      "daySpanSupplied": true,
      "averagePerDay": 7.1429,
      "averagePerDaySupplied": true,
      "cost": 25,
      "costSupplied": true,
      "tariffId": "T-1",
      "tariffInvented": false,
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-08"
    }
  ],
  "anomalies": [
    {
      "id": "AN-1",
      "meterId": "M-1",
      "buildingId": "B-1",
      "from": "2026-10-01",
      "to": "2026-10-08",
      "quantity": 70,
      "unit": "kWh",
      "dailyQuantity": 10,
      "baselineMean": 16.6667,
      "baselineMeanSupplied": true,
      "baselineMethod": "leave_one_out_mean_daily",
      "score": -0.5774,
      "scoreSupplied": true,
      "unusual": false,
      "explanation": "Daily usage 10 kWh is within 2 standard deviations of leave-one-out baseline mean 16.6667 (leave_one_out_mean_daily).",
      "tariffInvented": false,
      "savingsGuaranteed": false
    },
    {
      "id": "AN-2",
      "meterId": "M-1",
      "buildingId": "B-1",
      "from": "2026-10-08",
      "to": "2026-10-15",
      "quantity": 70,
      "unit": "kWh",
      "dailyQuantity": 10,
      "baselineMean": 16.6667,
      "baselineMeanSupplied": true,
      "baselineMethod": "leave_one_out_mean_daily",
      "score": -0.5774,
      "scoreSupplied": true,
      "unusual": false,
      "explanation": "Daily usage 10 kWh is within 2 standard deviations of leave-one-out baseline mean 16.6667 (leave_one_out_mean_daily).",
      "tariffInvented": false,
      "savingsGuaranteed": false
    },
    {
      "id": "AN-3",
      "meterId": "M-1",
      "buildingId": "B-1",
      "from": "2026-10-15",
      "to": "2026-10-22",
      "quantity": 70,
      "unit": "kWh",
      "dailyQuantity": 10,
      "baselineMean": 16.6667,
      "baselineMeanSupplied": true,
      "baselineMethod": "leave_one_out_mean_daily",
      "score": -0.5774,
      "scoreSupplied": true,
      "unusual": false,
      "explanation": "Daily usage 10 kWh is within 2 standard deviations of leave-one-out baseline mean 16.6667 (leave_one_out_mean_daily).",
      "tariffInvented": false,
      "savingsGuaranteed": false
    },
    {
      "id": "AN-4",
      "meterId": "M-1",
      "buildingId": "B-1",
      "from": "2026-10-22",
      "to": "2026-10-29",
      "quantity": 210,
      "unit": "kWh",
      "dailyQuantity": 30,
      "baselineMean": 10,
      "baselineMeanSupplied": true,
      "baselineMethod": "leave_one_out_mean_daily",
      "score": 3,
      "scoreSupplied": true,
      "unusual": true,
      "explanation": "Daily usage 30 kWh is outside 50–150% of leave-one-out baseline mean 10 (leave_one_out_mean_daily; stdev unavailable).",
      "tariffInvented": false,
      "savingsGuaranteed": false
    },
    {
      "id": "AN-5",
      "meterId": "M-2",
      "buildingId": "B-2",
      "from": "2026-10-01",
      "to": "2026-10-08",
      "quantity": 50,
      "unit": "kWh",
      "dailyQuantity": 7.1429,
      "baselineMean": 0,
      "baselineMeanSupplied": false,
      "baselineMethod": "none",
      "score": 0,
      "scoreSupplied": false,
      "unusual": false,
      "explanation": "No baseline was available for comparison.",
      "tariffInvented": false,
      "savingsGuaranteed": false
    }
  ],
  "hvac": [
    {
      "id": "EQ-1",
      "buildingId": "B-1",
      "name": "AHU-1",
      "type": "hvac",
      "ratedCapacity": 0,
      "ratedCapacitySupplied": false,
      "capacityUnit": "",
      "efficiency": 2.5,
      "efficiencySupplied": true,
      "ratedEfficiency": 3.5,
      "ratedEfficiencySupplied": true,
      "efficiencyRatio": 0.7143,
      "efficiencyRatioSupplied": true,
      "supplyTemp": 14,
      "supplyTempSupplied": true,
      "returnTemp": 14.2,
      "returnTempSupplied": true,
      "setpoint": 12,
      "setpointSupplied": true,
      "tempDelta": 0.2,
      "tempDeltaSupplied": true,
      "setpointGap": 2,
      "setpointGapSupplied": true,
      "runtimeHours": 9000,
      "runtimeHoursSupplied": true,
      "flags": [
        "below_rated_efficiency",
        "low_temp_delta"
      ],
      "performanceInvented": false,
      "equipmentControlled": false,
      "savingsGuaranteed": false
    }
  ],
  "baselines": [
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh",
      "sampleCount": 4,
      "baselineMean": 15,
      "baselineMeanSupplied": true,
      "baselineStdev": 10,
      "baselineStdevSupplied": true,
      "baselineMethod": "mean_daily_interval",
      "comparisonUnit": "kWh",
      "tariffInvented": false,
      "performanceInvented": false,
      "savingsGuaranteed": false
    },
    {
      "meterId": "M-2",
      "buildingId": "B-2",
      "utility": "electric",
      "unit": "kWh",
      "sampleCount": 1,
      "baselineMean": 7.1429,
      "baselineMeanSupplied": true,
      "baselineStdev": 0,
      "baselineStdevSupplied": false,
      "baselineMethod": "single_interval",
      "comparisonUnit": "kWh",
      "tariffInvented": false,
      "performanceInvented": false,
      "savingsGuaranteed": false
    }
  ],
  "costVariance": [
    {
      "billId": "BILL-1",
      "buildingId": "B-1",
      "utility": "electric",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-31",
      "quantity": 1000,
      "quantitySupplied": true,
      "unit": "kWh",
      "actualCost": 150,
      "actualCostSupplied": true,
      "expectedCost": 120,
      "expectedCostSupplied": true,
      "variance": 30,
      "varianceSupplied": true,
      "variancePct": 0.25,
      "variancePctSupplied": true,
      "tariffId": "T-1",
      "tariffRate": 0.1,
      "tariffRateSupplied": true,
      "tariffInvented": false,
      "savingsGuaranteed": false
    }
  ],
  "maintenance": [
    {
      "id": "EQ-1",
      "buildingId": "B-1",
      "name": "AHU-1",
      "type": "hvac",
      "lastServiceAt": "",
      "nextServiceDue": "2026-10-01",
      "overdueDays": 40,
      "overdueDaysSupplied": true,
      "daysSinceService": 0,
      "daysSinceServiceSupplied": false,
      "faultCount": 3,
      "faultCountSupplied": true,
      "runtimeHours": 9000,
      "runtimeHoursSupplied": true,
      "score": 85,
      "priority": "high",
      "reasons": [
        "service overdue by 40 days against supplied due date",
        "3 supplied fault count",
        "measured efficiency below 90% of rated efficiency",
        "runtime hours at or above 8000"
      ],
      "performanceInvented": false,
      "equipmentControlled": false,
      "savingsGuaranteed": false,
      "rank": 1
    }
  ],
  "occupancyCompare": [
    {
      "leftBuildingId": "B-1",
      "rightBuildingId": "B-2",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-29",
      "unit": "kWh",
      "leftQuantity": 420,
      "rightQuantity": 50,
      "leftOccupants": 100,
      "rightOccupants": 80,
      "leftPerOccupant": 4.2,
      "rightPerOccupant": 0.625,
      "leftPerOccupantSupplied": true,
      "rightPerOccupantSupplied": true,
      "compatible": true,
      "reason": "Compared because overlapping/matching periods and compatible energy units were supplied.",
      "savingsGuaranteed": false,
      "tariffInvented": false
    }
  ],
  "tariffInvented": false,
  "performanceInvented": false,
  "savingsGuaranteed": false,
  "equipmentControlled": false,
  "findings": [
    {
      "kind": "observation",
      "code": "usage_anomaly",
      "subject": "M-1",
      "detail": "Daily usage 30 kWh is outside 50–150% of leave-one-out baseline mean 10 (leave_one_out_mean_daily; stdev unavailable)."
    },
    {
      "kind": "missing",
      "code": "baseline",
      "subject": "M-2",
      "detail": "An interval has no peer baseline for anomaly comparison."
    },
    {
      "kind": "observation",
      "code": "thin_baseline",
      "subject": "M-2",
      "detail": "Fewer than two intervals were available. Baseline mean is labeled but variance is incomplete."
    },
    {
      "kind": "observation",
      "code": "cost_variance",
      "subject": "BILL-1",
      "detail": "Billed cost differs from tariff-based expected cost by 25%."
    }
  ],
  "limitations": [
    "Meter readings, bills, tariffs, equipment records, and occupancy rows are copied only from labeled fields supplied by the caller.",
    "Consumption and cost use supplied units and tariffs only. Missing tariffs are not invented.",
    "Unusual usage is compared against a baseline calculated from supplied readings for the same meter or utility.",
    "Buildings are compared only when measurement periods and units are compatible.",
    "Equipment performance and savings are never invented. HVAC and connected equipment are never controlled."
  ]
}

curl -i -X POST "https://brainiac.software/api/v1/building-energy/efficiency-report" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "asOf": "2026-11-10",
  "buildings": [
    {
      "id": "B-1",
      "name": "Tower A"
    },
    {
      "id": "B-2",
      "name": "Tower B"
    }
  ],
  "meters": [
    {
      "id": "M-1",
      "buildingId": "B-1",
      "utility": "electric",
      "unit": "kWh"
    },
    {
      "id": "M-2",
      "buildingId": "B-2",
      "utility": "electric",
      "unit": "kWh"
    }
  ],
  "readings": [
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-10-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-10-08",
      "value": 70,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-10-15",
      "value": 140,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-10-22",
      "value": 210,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-1",
      "buildingId": "B-1",
      "at": "2026-10-29",
      "value": 420,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-2",
      "buildingId": "B-2",
      "at": "2026-10-01",
      "value": 0,
      "unit": "kWh",
      "cumulative": true
    },
    {
      "meterId": "M-2",
      "buildingId": "B-2",
      "at": "2026-10-08",
      "value": 50,
      "unit": "kWh",
      "cumulative": true
    }
  ],
  "tariffs": [
    {
      "id": "T-1",
      "utility": "electric",
      "unit": "kWh",
      "rate": 0.1,
      "fixedCharge": 20
    }
  ],
  "bills": [
    {
      "id": "BILL-1",
      "buildingId": "B-1",
      "utility": "electric",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-31",
      "quantity": 1000,
      "unit": "kWh",
      "cost": 150
    }
  ],
  "equipment": [
    {
      "id": "EQ-1",
      "buildingId": "B-1",
      "name": "AHU-1",
      "type": "hvac",
      "nextServiceDue": "2026-10-01",
      "faultCount": 3,
      "efficiency": 2.5,
      "ratedEfficiency": 3.5,
      "supplyTemp": 14,
      "returnTemp": 14.2,
      "setpoint": 12,
      "runtimeHours": 9000
    }
  ],
  "occupancy": [
    {
      "buildingId": "B-1",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-08",
      "occupants": 100
    },
    {
      "buildingId": "B-2",
      "periodStart": "2026-10-01",
      "periodEnd": "2026-10-08",
      "occupants": 80
    }
  ]
}
JSON