Connect Your Edge AI to EnergyStackHub

Why Integrate with EnergyStackHub?

EnergyStackHub sits at the intersection of energy cost intelligence and building operations for commercial real estate. Our platform tracks utility costs, demand charges, and energy benchmarking data for thousands of commercial buildings.

When your edge AI or IoT platform connects via this API, your equipment health signals combine with our energy cost data to create something neither platform can offer alone: a complete picture of building efficiency that maps equipment degradation directly to energy waste and dollar cost.

Authentication

All API requests must include your partner API key in the Authorization header using Bearer token format. API keys are scoped to your partner organization and carry access to all buildings that have granted your integration permission.

# Include in every request
Authorization: Bearer esh_partner_sk_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Partner-ID: your-partner-slug

curl -X POST https://energystackhub.com/api/integrations/equipment-data \
  -H "Authorization: Bearer esh_partner_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -H "X-Partner-ID: your-partner-slug" \
  -d '{ "equipment_id": "chiller-01", "building_id": "bld_abc123", ... }'

Base URL & Versioning

All API endpoints are served from:

https://energystackhub.com/api/integrations/v1

The API uses URL versioning. The current stable version is v1. We maintain backward compatibility within a major version and announce breaking changes with 90 days notice.

Error Responses

All errors return a standard JSON body with an HTTP status code ≥ 400.

{
  "success": false,
  "error": {
    "code": "INVALID_BUILDING_ID",
    "message": "Building bld_xyz not found or partner access not granted",
    "status": 404
  }
}

Equipment Data Object

The core data object shared between your platform and EnergyStackHub. Flexible enough to support any equipment type while providing consistent fields for the unified dashboard.

maintenance_prediction Object

Alert Types

Sensor Types

Use the most specific sensor type available. ESH uses sensor_type to map readings to energy cost impact calculations.

POST /equipment-data

Ingest sensor readings from your IoT platform into EnergyStackHub. Supports single readings or batch arrays of up to 500 readings per request.

{
  "equipment_id": "chiller-north-01",
  "building_id": "bld_abc123def456",
  "sensor_type": "COP",
  "reading_value": 3.8,
  "reading_unit": "ratio",
  "timestamp": "2026-04-12T07:00:00Z",
  "equipment_name": "North Tower Chiller",
  "equipment_type": "chiller",
  "health_score": 84,
  "alert_type": null,
  "maintenance_prediction": {
    "failure_probability": 0.12,
    "days_to_failure": null,
    "recommended_action": "Monitor COP — trending below baseline by 15%",
    "confidence": "MEDIUM"
  }
}

{
  "readings": [
    {
      "equipment_id": "chiller-north-01",
      "building_id": "bld_abc123def456",
      "sensor_type": "POWER_CONSUMPTION",
      "reading_value": 245.7,
      "reading_unit": "kW",
      "timestamp": "2026-04-12T07:00:00Z"
    },
    {
      "equipment_id": "ahu-floor-3",
      "building_id": "bld_abc123def456",
      "sensor_type": "TEMPERATURE",
      "reading_value": 58.4,
      "reading_unit": "°F",
      "timestamp": "2026-04-12T07:00:00Z"
    }
  ]
}

{
  "success": true,
  "readings_accepted": 2,
  "readings_rejected": 0,
  "alert_triggered": false,
  "correlation_id": "corr_7f8a9b0c1d2e3f4"
}

POST /maintenance-alert

Send a high-priority maintenance alert to EnergyStackHub. Unlike sensor data ingest, alerts are immediately surfaced to building operators via dashboard notification, email, and optionally SMS. Use this for actionable events requiring human response.

{
  "equipment_id": "chiller-north-01",
  "building_id": "bld_abc123def456",
  "alert_type": "PREDICTIVE_FAILURE",
  "severity": "CRITICAL",
  "title": "Chiller Compressor Bearing Failure Predicted",
  "message": "Vibration signature indicates bearing wear. 94% probability of failure within 18 days.",
  "recommended_action": "Schedule emergency bearing inspection within 5 days",
  "days_to_failure": 18,
  "failure_probability": 0.94,
  "component": "compressor_bearing",
  "estimated_repair_cost_usd": 8500,
  "energy_impact_kwh_per_day": 187,
  "timestamp": "2026-04-12T07:15:00Z"
}

GET /building-profile/:id

Retrieve building context from EnergyStackHub to enrich your AI models. Includes utility rate schedules, energy consumption baselines, peak demand history, and building metadata. Makes your predictive models smarter — a motor running inefficiently means more in a building with $0.18/kWh rates than $0.09/kWh.

{
  "success": true,
  "building": {
    "building_id": "bld_abc123def456",
    "name": "Midtown Office Tower",
    "address": "123 Main St, New York, NY 10001",
    "square_footage": 380000,
    "building_type": "office",
    "utility": {
      "name": "Con Edison",
      "rate_schedule": "SC-9",
      "avg_rate_kwh": 0.182,
      "demand_charge_kw": 18.50,
      "peak_hours": "08:00-22:00 M-F"
    },
    "energy_baseline": {
      "monthly_kwh": 892000,
      "peak_demand_kw": 1840,
      "eui_kbtu_sqft": 67.3
    },
    "climate_zone": "4A"
  }
}

Webhook Events

EnergyStackHub can push events to your platform when building operators take action on alerts you've submitted, or when energy anomalies correlate with equipment readings.

{
  "event": "alert.acknowledged",
  "timestamp": "2026-04-12T10:22:00Z",
  "partner_id": "your-partner-slug",
  "data": {
    "alert_id": "alrt_9x8y7z",
    "equipment_id": "chiller-north-01",
    "building_id": "bld_abc123def456",
    "acknowledged_by": "facilities_manager@company.com",
    "action_taken": "work_order_created"
  },
  "signature": "sha256=abc123..."
}

Webhook Security

All webhooks are signed with HMAC-SHA256 using your partner webhook secret. Verify the signature before processing any webhook payload.

const crypto = require('crypto');

function verifyESHWebhook(rawBody, signature, secret) {
  const expected = `sha256=` +
    crypto.createHmac('sha256', secret)
      .update(rawBody)
      .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Partner Program

Integration partners get more than API access. We actively drive customer referrals to your platform and provide co-marketing opportunities across our commercial real estate audience.

Apply to Become an Integration Partner

API access is invite-only during the beta period. We review applications from edge AI, IoT, and predictive maintenance platforms serving commercial buildings.