REST API

One API for every HVAC, BMS, and smart-home device you operate.

Normalized read + control endpoints across 60+ brands. Auth, sites, devices, telemetry, faults, schedules, webhooks. Unlock the full spec with one email.

Browse endpoints →

Endpoints

REST API reference

Bearer-token auth, normalized JSON, brand-agnostic. Same shape whether the device is a Daikin VRV, a Trane RTU, or a Mitsubishi mini-split. Search by method, path, or capability — drop your email to unlock parameters and curl examples.

Base URL: https://api.hvacapi.com · 20 endpoints across 9 groups

POST /v1/auth/token Auth

Exchange a static API key for a short-lived access token
GET /v1/sites Sites

List all sites your token has access to
GET /v1/sites/{id} Sites

Get one site by id, including building metadata
GET /v1/devices Devices

List devices across sites you can access
GET /v1/devices/{id} Devices

Get a device with its capabilities
GET /v1/devices/{id}/state Devices

Current state — temperature, setpoint, mode, fan, runtime flags
POST /v1/devices/{id}/setpoint Control

Set the target temperature
POST /v1/devices/{id}/mode Control

Switch operating mode (heat | cool | auto | off | fan)
POST /v1/devices/{id}/schedule Control

Apply or override a weekly schedule
GET /v1/devices/{id}/telemetry Telemetry

Stream historical telemetry for a device
GET /v1/sites/{id}/energy Telemetry

Site-level energy roll-up (kWh, kW, demand)
GET /v1/faults Faults

List active faults across your scope
POST /v1/faults/{id}/acknowledge Faults

Acknowledge a fault and stop re-alarming
GET /v1/faults/explain Faults

Explain a brand-specific fault code
GET /v1/brands Brands

List supported brands and their protocols
GET /v1/brands/{slug} Brands

Get capabilities for one brand
GET /v1/schedules Schedules

List schedules (templates) configured on your account
POST /v1/schedules Schedules

Create a new schedule template
POST /v1/webhooks Webhooks

Register a webhook for fault, control, or telemetry events
GET /v1/webhooks Webhooks

List configured webhooks

Full specifications

Drop your email to unlock request bodies, response shapes, scopes, error codes, and copy-paste curl examples for every endpoint above. One email unlocks every brand and the MCP tools too.

POST /v1/auth/token

Trades a long-lived API key (issued at signup) for a 1-hour bearer token. Required for every other endpoint. Rate-limited to 60 requests / hour / key.

Scopes: public

Parameters

apiKey · body · string · required Your account API key.
scopes · body · string[] Subset of granted scopes to request; defaults to all.

Response shape

{ token: string; expiresAt: ISO8601; scopes: string[] }

curl

curl -X POST https://api.hvacapi.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"$HVACAPI_KEY"}'

GET /v1/sites

Paginated. Each site rolls up a building or location. Used as the parent scope for device, telemetry, and fault queries.

Scopes: sites:read

Parameters

limit · query · int Page size, default 50, max 250.
cursor · query · string Opaque pagination cursor from the previous response.

Response shape

{ sites: Site[]; nextCursor?: string }

curl

curl https://api.hvacapi.com/v1/sites \
  -H "Authorization: Bearer $TOKEN"

GET /v1/sites/{id}

Returns the site's metadata (address, square footage, HVAC totals) plus a count of devices and active faults.

Scopes: sites:read

Parameters

id · path · string · required Site identifier.

Response shape

{ id; name; address; deviceCount; activeFaultCount; … }

GET /v1/devices

Filter by site, brand, category, status. Useful to enumerate equipment for an integration job.

Scopes: devices:read

Parameters

siteId · query · string Restrict to one site.
brand · query · string Restrict to one brand slug (carrier, daikin, …).
category · query · enum HVAC | HomeAutomation | BMS.

Response shape

{ devices: Device[]; nextCursor?: string }

GET /v1/devices/{id}

Returns the canonical device record: brand, model, supported points, current online status. Capability set tells you which Control endpoints will succeed.

Scopes: devices:read

Parameters

id · path · string · required Device identifier.

Response shape

{ id; brand; model; capabilities[]; online; … }

GET /v1/devices/{id}/state

Normalized across brands. A Daikin VRV, a Trane RTU, and a Mitsubishi mini-split all return the same JSON shape. Latency typically <250ms.

Scopes: devices:read

Parameters

id · path · string · required Device identifier.

Response shape

{ temperature; humidity; setpoint; mode; fanSpeed; status; readAt }

curl

curl https://api.hvacapi.com/v1/devices/{id}/state \
  -H "Authorization: Bearer $TOKEN"

POST /v1/devices/{id}/setpoint

Write-back is opt-in per device per scope. Every call is audit-logged with caller, before/after, and outcome. Subject to your site's safety interlocks.

Scopes: devices:write

Parameters

id · path · string · required Device identifier.
value · body · number · required Target temperature in the device's native unit (°C or °F per site config).
reason · body · string Audit reason; freeform.

Response shape

{ ok: true; before; after; appliedAt; auditId }

POST /v1/devices/{id}/mode

Mode set is bounded by the device's capabilities — sending "cool" to a heat-only unit returns 422 with allowed values.

Scopes: devices:write

Parameters

id · path · string · required Device identifier.
mode · body · enum · required heat | cool | auto | off | fan | dry.

Response shape

{ ok; before; after; appliedAt; auditId }

POST /v1/devices/{id}/schedule

Pushes a 7-day schedule with up to 8 segments per day. Setpoints during unoccupied segments respect the global setback policy unless overridden per-segment.

Scopes: devices:write

Parameters

id · path · string · required Device identifier.
schedule · body · Schedule · required A WeeklySchedule object — see /v1/schedules.

Response shape

{ ok; scheduleId; effectiveFrom }

GET /v1/devices/{id}/telemetry

Returns sampled values for the requested points over a time window. Default sampling is 1-minute; downsamples for windows >24h.

Scopes: telemetry:read

Parameters

id · path · string · required Device identifier.
points · query · string[] Comma-separated point names (temperature, setpoint, …).
from · query · ISO8601 Start of window. Default: 24h ago.
to · query · ISO8601 End of window. Default: now.
resolution · query · enum 1m | 5m | 1h | 1d.

Response shape

{ points: { name; samples: [t, v][] }[] }

GET /v1/sites/{id}/energy

Aggregates per-device runtime and amperage into a single site energy series. Used by the M&V / IPMVP report templates.

Scopes: telemetry:read

Parameters

id · path · string · required Site identifier.
from · query · ISO8601 Start of window.
to · query · ISO8601 End of window.

Response shape

{ kWh; peakKW; demandKW; samples: [t, kW][] }

GET /v1/faults

Filter by site, brand, severity. The same data that drives /technician-copilot escalations.

Scopes: faults:read

Parameters

severity · query · enum info | warning | critical.
siteId · query · string Restrict to one site.

Response shape

{ faults: Fault[]; nextCursor? }

POST /v1/faults/{id}/acknowledge

Sets the fault state to acknowledged and silences further notifications for the configured cooldown.

Scopes: faults:write

Parameters

id · path · string · required Fault identifier.
note · body · string Acknowledgement note; goes into the audit log.

Response shape

{ ok; acknowledgedAt; by }

GET /v1/faults/explain

Returns the human-readable meaning, severity, and suggested first-checks for a given brand + code. Same data that powers the /brands/<slug> fault-code tables.

Scopes: public

Parameters

brand · query · string · required Brand slug.
code · query · string · required Fault code (e.g. U4, E6).

Response shape

{ brand; code; category; meaning; severity; suggestedAction }

GET /v1/brands

Public — same data as the /coverage page. Returns the live catalog so integrations can adapt as new brands ship.

Scopes: public

Response shape

{ brands: { slug; name; category; protocols; status }[] }

GET /v1/brands/{slug}

Returns the brand's device families, supported points, protocol matrix, and code snippets. Used to gate UI before showing an integration step.

Scopes: public

Parameters

slug · path · string · required Brand slug.

Response shape

{ brand; deviceFamilies; capabilities; protocols }

GET /v1/schedules

Schedules are reusable WeeklySchedule objects you can attach to many devices. Lifts schedule management out of the per-device control flow.

Scopes: schedules:read

Response shape

{ schedules: Schedule[]; nextCursor? }

POST /v1/schedules

7 days, up to 8 segments per day, per-segment setpoint or setback offset.

Scopes: schedules:write

Response shape

{ id; name; createdAt }

POST /v1/webhooks

POST a URL + an event-type filter. We sign every delivery with HMAC-SHA256 and retry with exponential backoff for 24 hours.

Scopes: webhooks:write

Parameters

url · body · string · required HTTPS endpoint.
events · body · string[] · required fault.opened | fault.acknowledged | device.write | telemetry.threshold | …

Response shape

{ id; secret; createdAt }

GET /v1/webhooks

Includes lastDeliveryAt and lastDeliveryStatus so you can spot broken consumers quickly.

Scopes: webhooks:read

Response shape

{ webhooks: Webhook[] }

How it stays out of your way

Secure

Sealed data plane. Per-site auth. Audit log on every setpoint touch.

Runs on the edge

Deploys at the building edge — your data doesn't leave the site to be useful.

BYO LLM

Works with Claude, ChatGPT, and any MCP-compatible client. You pick the brain.

One API for every HVAC, BMS, and smart-home device you operate.

REST API reference

Full specifications

Ask about the API — auth, scopes, rate limits.

Send us the question

Secure

Runs on the edge

BYO LLM