> ## Documentation Index > Fetch the complete documentation index at: https://docs.amps.ai/llms.txt > Use this file to discover all available pages before exploring further. # Push HVAC action > Send a command to an HVAC device. The action is processed asynchronously and a webhook is sent on completion. ## OpenAPI ````yaml /openapi.json post /hvac/{deviceId} openapi: 3.1.0 info: title: Amps.ai API description: >- Energy device management API for batteries, EV chargers, solar inverters, and HVAC systems version: '1.0' contact: {} servers: - url: https://api.amps.ai description: Amps API security: [] tags: [] paths: /hvac/{deviceId}: post: tags: - HVAC summary: Push HVAC action description: >- Send a command to an HVAC device. The action is processed asynchronously and a webhook is sent on completion. operationId: pushHvac parameters: - name: deviceId required: true in: path description: The unique identifier for the HVAC device schema: example: device_abc123 type: string requestBody: required: true description: The action to perform on the HVAC device content: application/json: schema: $ref: '#/components/schemas/HvacPushRequest' examples: heat: summary: Heat to a target temperature description: >- `command: heat` with a single `target` to hold, in Celsius. Parameters use the canonical `{ value, unit }` shape. value: action: command: heat parameters: target: value: 21 unit: celsius cool: summary: Cool to a target temperature description: '`command: cool` with a single `target` to hold, in Celsius.' value: action: command: cool parameters: target: value: 22 unit: celsius auto.maintain: summary: Maintain a comfort band (auto.maintain) description: >- `command: auto.maintain` defines a comfort band: the device heats below `heatSetpoint` and cools above `coolSetpoint`. value: action: command: auto.maintain parameters: heatSetpoint: value: 20 unit: celsius coolSetpoint: value: 24 unit: celsius idle: summary: Pause heating and cooling description: '`command: idle` pauses all activity. No parameters.' value: action: command: idle heatScheduled: summary: Heat starting at a future time (deferred) description: >- `start` alone schedules the action to fire at the given instant. Returns 202 with `state: scheduled`. Accepts ISO 8601 with timezone or a relative duration (`30m`, `1.5h`). value: action: command: heat parameters: target: value: 21 unit: celsius start: '2026-06-01T18:00:00Z' heatWindowed: summary: Heat during a window (start + end) description: >- `start` + `end` together describe a windowed action. Available on `heat`/`cool`, whose execution set includes `windowed`. The action fires at `start`; `end` is recorded for the window contract. value: action: command: heat parameters: target: value: 21 unit: celsius start: '2026-06-01T18:00:00Z' end: '2026-06-01T22:00:00Z' followSchedule: summary: Resume the automatic HVAC schedule description: >- Releases any active override and hands control back to the device's native schedule. value: action: command: auto.schedule autoWithConflictStrategy: summary: Auto with a conflict-resolution strategy description: >- `onConflict: cancel_and_replace` replaces a scheduled or windowed conflict that has not been dispatched yet. A command already sent to the manufacturer cannot be recalled, so it returns 409 `CONFLICT_IN_EXECUTION`. value: action: command: auto.maintain parameters: heatSetpoint: value: 19 unit: celsius coolSetpoint: value: 23 unit: celsius onConflict: cancel_and_replace sandboxFail: summary: Simulate a failure in sandbox description: >- Sandbox-only. Use `sandbox.result: "failed"` plus an `errorCode` to test client error handling without touching a real device. value: action: command: heat parameters: target: value: 22 unit: celsius sandbox: result: failed errorCode: COMMAND_NOT_SUPPORTED responses: '202': description: Action acknowledged and queued for processing content: application/json: schema: type: object required: - success - data - meta properties: success: type: boolean const: true description: Always `true` for success responses. data: $ref: '#/components/schemas/HvacPushResponse' meta: $ref: '#/components/schemas/ResponseMeta' examples: setOperationModeAcknowledged: summary: Operation mode dispatched description: >- The response mirrors the dispatch: `command` + `parameters` + `deviceType`. Track the action at `links.self`. value: success: true data: id: act_20260507100hvac01 deviceId: dev_hv4c9d2e deviceType: hvac command: heat parameters: target: value: 21 unit: celsius state: acknowledged createdAt: '2026-05-07T10:00:00.000Z' start: null links: self: /actions/act_20260507100hvac01 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 deferredScheduled: summary: Deferred action scheduled to fire at `start` description: >- `state: scheduled` and `start` carries the absolute fire time. The action fires when the scheduled instant arrives. Cancel via `POST /actions/{actionId}/cancel` before then. value: success: true data: id: act_20260507080hvac03 deviceId: dev_hv4c9d2e deviceType: hvac command: cool parameters: target: value: 22 unit: celsius state: scheduled createdAt: '2026-05-07T08:00:00.000Z' start: '2026-06-01T18:00:00.000Z' links: self: /actions/act_20260507080hvac03 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 followScheduleCompleted: summary: Follow schedule completed synchronously description: >- `auto.schedule` is a command like any other; it carries no constraints, so `parameters` is null. value: success: true data: id: act_20260507110hvac02 deviceId: dev_hv4c9d2e deviceType: hvac command: auto.schedule parameters: null state: completed createdAt: '2026-05-07T11:00:00.000Z' links: self: /actions/act_20260507110hvac02 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 '400': description: >- Invalid request body. The device manufacturer can also refuse a well-formed request with this status (`COMMAND_FAILED`, `INVALID_PARAMETERS`, `UNSUPPORTED_CREDENTIAL_TYPE`). Every code at this status: `COMMAND_FAILED`, `INVALID_PARAMETERS`, `INVALID_REQUEST_BODY`, `UNSUPPORTED_CREDENTIAL_TYPE`, `VALIDATION_ERROR`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingAction: summary: '`action` field missing from the body' value: success: false error: code: INVALID_REQUEST_BODY message: The request body is invalid. details: fields: action: - Required description: Invalid request body meta: requestId: req_1bA0eFgC timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_hvac_001 latencyMs: 3 missingCommand: summary: >- `action` is present but carries no `command`. A command the platform does not recognise (`follow_schedule`) is NOT a 400 — it is a 422 `UNSUPPORTED_MODE` naming the modes this device accepts, exactly like a canonical command from another device family such as `charge`. value: success: false error: code: INVALID_REQUEST_BODY message: The request body is invalid. details: fields: action.command: - >- Unsupported command. This device supports: `heat`, `cool`, `idle`, `auto.maintain`, `auto.schedule`. description: Invalid request body meta: requestId: req_6mE3jKlW timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_hvac_001 latencyMs: 3 '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: No `x-api-key` header present value: success: false error: code: UNAUTHORIZED message: Authentication is required. details: description: API key is required meta: requestId: req_8sW2dRtX timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_hvac_001 latencyMs: 2 '403': description: >- Error codes: `FORBIDDEN`, `INVALID_MFA_CODE`, `MFA_REQUIRED`, `ACCOUNT_LOCKED`, `DEVICE_UNAUTHORIZED`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Device not found or access denied content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: deviceNotFound: summary: No device matches the ID for this customer value: success: false error: code: DEVICE_NOT_FOUND message: No matching device was found for the supplied details. details: description: Device not found or access denied meta: requestId: req_5pH1cQbY timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_unknown_999 latencyMs: 5 '409': description: >- A conflicting action is already in progress Every code at this status: `CONFLICT`, `CONFLICT_IN_EXECUTION`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflictInFlight: summary: Previous hold action still acknowledged value: success: false error: code: CONFLICT_IN_EXECUTION message: A conflicting action is already being executed. details: reason: conflicting_action_in_progress conflictingActionIds: - act_20260507100hvac01 description: >- A conflicting action is already in progress for this device. Wait for it to complete. meta: requestId: req_3dC6hOsT timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_hvac_001 latencyMs: 14 '410': description: 'Error codes: `DEVICE_OFFLINE`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: 'Error codes: `PAYLOAD_TOO_LARGE`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '415': description: 'Error codes: `UNSUPPORTED_MEDIA_TYPE`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- The request is well-formed but violates a device or canonical constraint. Common codes: `COMMAND_NOT_SUPPORTED` (the unit does not implement this command), `UNSUPPORTED_MODE`, `UNSUPPORTED_PARAMETER`, `PARAMETER_OUT_OF_RANGE`, `STRATEGY_NOT_SUPPORTED` (the requested `onConflict` strategy is not declared by the device). The error `details` carries the offending values and the device capability subset. A route that is built but not switched on for live yet answers `503 NOT_YET_AVAILABLE` instead, never this status. Every code at this status: `COMMAND_NOT_SUPPORTED`, `DIRECT_ACTION_UNSUPPORTED`, `EXECUTION_NOT_SUPPORTED`, `INVALID_TIMEZONE`, `INVALID_TIME_WINDOW`, `PARAMETER_OUT_OF_RANGE`, `SETTING_OUT_OF_RANGE`, `START_INVALID_FORMAT`, `START_IN_PAST`, `START_NONEXISTENT_WALL_CLOCK`, `START_OFFSET_NOT_ACCEPTED`, `START_OUT_OF_RANGE`, `STRATEGY_NOT_SUPPORTED`, `TIMEZONE_UNRESOLVED`, `UNSUPPORTED_ACTION`, `UNSUPPORTED_MODE`, `UNSUPPORTED_PARAMETER`, `UNSUPPORTED_PARAMETER_COMBINATION`, `UNSUPPORTED_UNIT`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: directActionUnsupported: summary: This device does not support direct push commands value: success: false error: code: DIRECT_ACTION_UNSUPPORTED message: This device does not support imperative push commands. meta: requestId: req_3dC6hOsT timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_hvac_001 latencyMs: 2 unsupportedMode: summary: >- Heat-only device does not support cooling. The body is well-formed, so it is a recoverable 422 with the supported modes, not a 400. value: success: false error: code: UNSUPPORTED_MODE message: The requested mode is not supported by this device. details: deviceCapabilities: supportedModes: - heat - idle - auto.maintain - auto.schedule description: Mode `cool` is not supported by this device. meta: requestId: req_4eD7iPuU timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_hvac_001 latencyMs: 9 unsupportedParameter: summary: >- `target` is a `heat`/`cool` parameter, not an `auto.maintain` parameter. Supplying it on `auto.maintain` is a recoverable 422 naming the offender and the supported set. value: success: false error: code: UNSUPPORTED_PARAMETER message: One or more parameters are not supported by this device. details: unsupportedParameters: - target deviceCapabilities: supportedParameters: - heatSetpoint - coolSetpoint description: >- Parameter(s) not supported for mode `auto.maintain`: target. meta: requestId: req_8iH1mTyY timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_hvac_001 latencyMs: 8 setpointOutOfRange: summary: >- Target temperature exceeds the canonical max of 35°C. `details` carries the bounds so the caller can correct without a second GET. value: success: false error: code: PARAMETER_OUT_OF_RANGE message: One or more parameters are outside the supported range. details: parameter: target value: 99 min: 10 max: 35 unit: celsius description: Parameter `target` value 99 exceeds the maximum 35. meta: requestId: req_5fE8jQvV timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_hvac_001 latencyMs: 7 executionNotSupported: summary: >- Caller requested `windowed` (start + end) on a mode that only supports `immediate` and `scheduled` value: success: false error: code: EXECUTION_NOT_SUPPORTED message: >- The requested execution mode is not supported for this device. details: requestedExecution: windowed supportedExecution: - immediate - scheduled description: >- Mode 'idle' does not support windowed execution on this device. Supported shapes: immediate, scheduled. meta: requestId: req_7hG0lSxX timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_hvac_001 latencyMs: 6 strategyNotSupported: summary: >- `onConflict: queue_after` requested but this device declares only `cancel_and_replace` value: success: false error: code: STRATEGY_NOT_SUPPORTED message: >- The requested conflict strategy is not supported by this device. details: requestedStrategy: queue_after supportedStrategies: - cancel_and_replace description: >- Conflict strategy 'queue_after' is not supported by this device. Supported strategies: cancel_and_replace. meta: requestId: req_6gF9kRwW timestamp: '2026-04-29T12:00:00.000Z' path: /hvac/device_hvac_001 latencyMs: 6 '429': description: 'Error codes: `RATE_LIMITED`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 'Error codes: `INTERNAL_ERROR`, `UNKNOWN_ERROR`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': description: 'Error codes: `NETWORK_ERROR`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Error codes: `SERVICE_UNAVAILABLE`, `NOT_YET_AVAILABLE`, `SIMULATED_FAILURE`, `OEM_CIRCUIT_OPEN`, `SETTINGS_STORE_UNAVAILABLE`. `SERVICE_UNAVAILABLE` is temporary: retry with exponential backoff. `NOT_YET_AVAILABLE` is not: Amps has not switched this route on yet, so retrying returns the same answer until it does. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '504': description: 'Error codes: `TIMEOUT`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - api-key: [] x-codeSamples: - lang: curl label: curl source: |- curl --request POST \ --url 'https://api.amps.ai/hvac/device_abc123' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' \ --header 'content-type: application/json' \ --data '{ "action": { "command": "heat", "parameters": { "target": { "value": 21, "unit": "celsius" } } } }' - lang: javascript label: Node source: >- const response = await fetch('https://api.amps.ai/hvac/device_abc123', { method: 'POST', headers: { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', 'content-type': 'application/json', }, body: JSON.stringify({ "action": { "command": "heat", "parameters": { "target": { "value": 21, "unit": "celsius" } } } }), }); const data = await response.json(); - lang: python label: Python source: |- import requests url = 'https://api.amps.ai/hvac/device_abc123' headers = { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', 'content-type': 'application/json', } payload = { "action": { "command": "heat", "parameters": { "target": { "value": 21, "unit": "celsius", }, }, }, } response = requests.post(url, headers=headers, json=payload) data = response.json() components: schemas: HvacPushRequest: type: object properties: action: $ref: '#/components/schemas/HvacAction' onConflict: $ref: '#/components/schemas/HvacOnConflict' sandbox: $ref: '#/components/schemas/HvacSandboxConfig' required: - action description: >- A single HVAC action plus optional `onConflict` strategy and `sandbox` controls. Action variants describe what the API accepts. Per-device support varies; the `commands` map on `GET /hvac/{deviceId}` shows which actions a specific device handles. examples: - action: command: heat parameters: target: value: 21 unit: celsius - action: command: auto.maintain parameters: heatSetpoint: value: 20 unit: celsius coolSetpoint: value: 24 unit: celsius onConflict: cancel_and_replace - action: command: auto.schedule title: Hvac Push HvacPushResponse: type: object properties: id: type: string description: Unique identifier for the action. deviceId: type: string description: Device the action targets. deviceType: type: string const: hvac description: The device family the action targets. command: type: string enum: - heat - cool - idle - auto.maintain - auto.schedule description: >- The canonical command issued (`heat`, `cool`, `idle`, `auto.maintain`, or `auto.schedule`). Mirrors the verb sent on dispatch. parameters: anyOf: - type: object properties: target: $ref: '#/components/schemas/Quantity' heatSetpoint: $ref: '#/components/schemas/Quantity' coolSetpoint: $ref: '#/components/schemas/Quantity' - type: 'null' description: >- Constraints the command was issued with. `heat`/`cool` carry `target`; `auto.maintain` carries `heatSetpoint`/`coolSetpoint`; `idle` and `auto.schedule` carry none (null). state: type: string enum: - acknowledged - completed - failed - scheduled - cancelled description: >- Current state of the action. `scheduled` indicates a deferred action awaiting its fire time. `cancelled` is a terminal state reachable from `scheduled` via POST /actions/{actionId}/cancel. createdAt: type: string format: date-time description: Timestamp when the action was created. start: description: >- Absolute firing instant for deferred actions, as an ISO 8601 timestamp. Null or absent for immediate actions. anyOf: - type: string format: date-time - type: 'null' end: description: >- Absolute end instant for windowed actions, as an ISO 8601 timestamp. Present whenever `end` was requested, including a window sent without a `start`, which runs from now until this instant. Null or absent when no `end` was requested. anyOf: - type: string format: date-time - type: 'null' links: type: object properties: self: type: string description: >- Canonical path to this action: `GET /actions/{actionId}`. Poll it to follow the action to a terminal state. required: - self description: Hypermedia links for this action. warnings: description: >- Conditions observed at submission that delay the command taking effect. The command is accepted; each entry names what must clear first. Advisory and best-effort: absence means nothing to report, not a guarantee that nothing is blocking. Never sent for deferred pushes (the state now does not describe the fire time). type: array items: $ref: '#/components/schemas/PushWarning' required: - id - deviceId - deviceType - command - parameters - state - createdAt - links title: Hvac Push Response description: >- Result of a push. Mirrors the dispatch (`command` + `parameters` + `deviceType`) and carries `links.self` to track the action. For immediate actions, `state` reflects the dispatch outcome. For deferred actions, `state` is `scheduled`, `start` carries the fire time, and `end` the window close when a window was requested. ResponseMeta: type: object title: Response Meta description: >- Metadata attached to every response: the request identifier, the serving environment, the build timestamp, and the server-side latency. required: - environment - timestamp - latencyMs properties: requestId: description: >- Unique request identifier. Echoes the `x-request-id` header when present; otherwise generated server-side. type: string environment: type: string description: The environment that served the request (`sandbox` or `live`). timestamp: type: string format: date-time description: ISO 8601 timestamp when the response was built. latencyMs: type: integer description: Server-side processing time in milliseconds. ErrorResponse: type: object properties: success: type: boolean description: Always `false` for error responses. error: type: object properties: code: type: string enum: - INVALID_CREDENTIALS - INVALID_API_KEY - INVALID_MFA_CODE - MFA_REQUIRED - ACCOUNT_LOCKED - UNSUPPORTED_CREDENTIAL_TYPE - DEVICE_NOT_FOUND - DEVICE_OFFLINE - DEVICE_UNAUTHORIZED - NO_DEVICES_FOUND - COMMAND_FAILED - COMMAND_NOT_SUPPORTED - EXECUTION_NOT_SUPPORTED - MODE_OVERRIDDEN - VPP_LOCKED - INVALID_PARAMETERS - INVALID_OEM_PARAMETERS - INVALID_TIME_WINDOW - BIND_NOT_SUPPORTED - SCHEDULER_ACTIVE - SCHEDULER_FULL - UNSUPPORTED_AUTH_PATH - SETTING_OUT_OF_RANGE - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - VEHICLE_NOT_CONNECTED - SESSIONS_NOT_SUPPORTED - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - INVALID_OEM_RESPONSE - COMMAND_NOT_APPLIED - STALE_ACTION - DEFERRED_SCHEDULE_FAILED - UNROUTABLE_ACTION_TYPE - UNAUTHORIZED - EXPIRED_TOKEN - FORBIDDEN - INSUFFICIENT_PERMISSIONS - LIVE_ACCESS_DISABLED - VALIDATION_ERROR - INVALID_INPUT - INVALID_REQUEST_BODY - EMPTY_SETTINGS - PAYLOAD_TOO_LARGE - UNSUPPORTED_MEDIA_TYPE - NOT_FOUND - METHOD_NOT_ALLOWED - CONFLICT - CONFLICT_IN_EXECUTION - GONE - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - NOT_IMPLEMENTED - BAD_GATEWAY - GATEWAY_TIMEOUT - DEVICE_TYPE_MISMATCH - CONSENT_REVOKED - DEVICE_OVERAGE - SETTINGS_STORE_UNAVAILABLE - ACTION_NOT_FOUND - DIRECT_ACTION_UNSUPPORTED - UNSUPPORTED_ACTION - UNSUPPORTED_MODE - UNSUPPORTED_PARAMETER - UNSUPPORTED_PARAMETER_COMBINATION - UNSUPPORTED_UNIT - PARAMETER_OUT_OF_RANGE - START_IN_PAST - START_OUT_OF_RANGE - START_OFFSET_NOT_ACCEPTED - START_INVALID_FORMAT - START_NONEXISTENT_WALL_CLOCK - TIMEZONE_UNRESOLVED - INVALID_TIMEZONE - ACTION_NOT_CANCELLABLE - STRATEGY_NOT_SUPPORTED - UNSUPPORTED_SETTING - UNSUPPORTED_SETTING_COMBINATION - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - NO_OP - NO_OVERRIDE - AVAILABILITY_ENV_UNSUPPORTED - UNSUPPORTED_COMBINATION description: >- Machine-readable error code (e.g. `VALIDATION_ERROR`, `CONFLICT`, `UNSUPPORTED_MODE`). Stable across releases; safe to switch on. message: type: string description: Human-readable error message. details: description: >- Structured context for the error: which fields were invalid, which actions conflicted, which capabilities the device declares. Shape varies by error code. type: object properties: {} additionalProperties: {} required: - code - message description: Error envelope. meta: type: object properties: requestId: description: >- Unique request identifier. Echoes the `x-request-id` header when present; otherwise generated server-side. type: string timestamp: type: string description: ISO 8601 timestamp when the error response was built. path: type: string description: Request path that produced the error. latencyMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Server-side processing time in milliseconds. required: - timestamp - path - latencyMs description: Request metadata. required: - success - error - meta title: Error Response description: >- Uniform error response. The `error.code` identifies the failure, `error.message` carries a human-readable explanation, and `error.details` carries structured context (failed fields, conflicting action IDs, supported capabilities) where relevant. HvacAction: type: object properties: command: type: string enum: - heat - cool - idle - auto.maintain - auto.schedule description: >- The HVAC command. Device support varies; an unavailable HVAC command is rejected at runtime with `422 UNSUPPORTED_MODE` carrying the supported modes. A token outside the canonical vocabulary altogether is answered the same way, as long as the rest of the body is well-formed; `400` is for a body that is malformed for some other reason. parameters: $ref: '#/components/schemas/HvacCommandParameters' start: description: >- Start time. Plant-local wall-clock ISO 8601 without timezone offset (e.g. `2026-06-01T22:00:00`), or a relative duration (e.g. `30m`, `1.5h`). The platform interprets the wall-clock in the device's plant timezone. Omit for immediate execution. type: string end: description: >- End time for windowed execution. Plant-local wall-clock ISO 8601 without timezone offset (e.g. `2026-06-01T06:00:00`). Supplied without `start`, the window opens now: the command is sent on this request and confirmed in the response, which reports `state: acknowledged`, no `start`, and this `end`. The platform takes the command back when `end` arrives. type: string required: - command additionalProperties: false title: HVAC Action description: >- A canonical HVAC command. `heat`/`cool` hold a `target` temperature; `auto.maintain` maintains a comfort band between `heatSetpoint` and `coolSetpoint`; `idle` pauses; `auto.schedule` resumes the device’s native program. examples: - command: heat parameters: target: value: 21 unit: celsius - command: auto.maintain parameters: heatSetpoint: value: 20 unit: celsius coolSetpoint: value: 24 unit: celsius - command: auto.schedule HvacOnConflict: type: string enum: - cancel_and_replace - queue_after description: >- `cancel_and_replace` cancels the active action before running this one; `queue_after` defers this one until the active action completes. Omit to receive 409 on conflict. title: Hvac On Conflict HvacSandboxConfig: type: object properties: result: description: Outcome to simulate. Defaults to `success`. type: string enum: - success - failed errorCode: description: >- Error code to emit when `result` is `failed`. Defaults to `SIMULATED_FAILURE`. Constrained to the HVAC canonical error codes. type: string enum: - INVALID_CREDENTIALS - INVALID_API_KEY - INVALID_MFA_CODE - MFA_REQUIRED - ACCOUNT_LOCKED - UNSUPPORTED_CREDENTIAL_TYPE - DEVICE_NOT_FOUND - DEVICE_OFFLINE - DEVICE_UNAUTHORIZED - NO_DEVICES_FOUND - COMMAND_FAILED - COMMAND_NOT_SUPPORTED - INVALID_PARAMETERS - SETTING_OUT_OF_RANGE - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR oemError: description: >- Inject a raw device-manufacturer error (message, optional code and HTTP status) and receive back the canonical error code the platform classifies it to, exactly as a live failure would surface. Takes precedence over `errorCode` when `result` is `failed`. type: object properties: message: type: string minLength: 1 maxLength: 4096 oemCode: anyOf: - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 httpStatus: type: integer minimum: 100 maximum: 599 required: - message additionalProperties: false description: Sandbox controls for testing error paths. Ignored in live environments. title: Hvac Sandbox Config Quantity: type: object properties: value: type: number description: Numeric magnitude. unit: type: string enum: - percent - kw - watts - kwh - amps - volts - hours - minutes - celsius - fahrenheit description: >- Unit of measure. Closed set so consumers can switch exhaustively at the type layer. required: - value - unit title: Quantity description: >- Self-describing numeric value with its unit. `value` is the magnitude, `unit` names one of the canonical units. PushWarning: type: object properties: code: type: string enum: - vehicle_not_connected - awaiting_authorization description: >- Stable identifier for the observed condition. `vehicle_not_connected`: no vehicle is plugged in. `awaiting_authorization`: the charge waits for approval in the manufacturer app. message: type: string description: Human-readable description of the condition. observedAt: type: string format: date-time description: >- When the reading behind this warning was taken, as an ISO 8601 timestamp. A stale reading may no longer describe the device. required: - code - message - observedAt description: >- A condition observed at submission that delays the command taking effect. The command is accepted and armed; the warning names what must clear first. Never a refusal. title: Push Warning HvacCommandParameters: type: object properties: target: $ref: '#/components/schemas/Quantity' description: >- Target temperature to hold. Accepted by `heat` and `cool`. (unit: `celsius`, min: 10, max: 35) heatSetpoint: $ref: '#/components/schemas/Quantity' description: >- Lower comfort bound for `auto.maintain`; the device heats when the temperature falls below this. (unit: `celsius`, min: 10, max: 35) coolSetpoint: $ref: '#/components/schemas/Quantity' description: >- Upper comfort bound for `auto.maintain`; the device cools when the temperature rises above this. (unit: `celsius`, min: 10, max: 35) additionalProperties: {} description: >- Command parameters. `heat`/`cool` accept `target`; `auto.maintain` accepts `heatSetpoint`/`coolSetpoint`; `idle`/`auto.schedule` accept none. A parameter the command does not accept is rejected at runtime with `422 UNSUPPORTED_PARAMETER`. title: Hvac Command Parameters securitySchemes: api-key: type: apiKey in: header name: x-api-key ````