> ## 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. # Get action status > Retrieve the current state of any device action for polling. The action lifecycle progresses `scheduled` (deferred only) -> `acknowledged` -> `completed` | `failed`, with `cancelled` reachable from `scheduled`. The `deviceType` field discriminates the device family and the `command`/`parameters` shape. ## OpenAPI ````yaml /openapi.json get /actions/{actionId} 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: /actions/{actionId}: get: tags: - Actions summary: Get action status description: >- Retrieve the current state of any device action for polling. The action lifecycle progresses `scheduled` (deferred only) -> `acknowledged` -> `completed` | `failed`, with `cancelled` reachable from `scheduled`. The `deviceType` field discriminates the device family and the `command`/`parameters` shape. operationId: getAction parameters: - name: actionId required: true in: path description: The unique identifier for the action. schema: example: act_abc123 type: string responses: '200': description: Action status retrieved successfully. 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/ActionResponse' meta: $ref: '#/components/schemas/ResponseMeta' examples: batteryScheduled: summary: Battery — deferred action waiting for its fire time description: >- Created with `start` in the future. `state: scheduled` until the fire time, when the platform dispatches and transitions to `acknowledged`. value: success: true data: id: act_2026050709a1b2c3 deviceId: device_abc123 deviceType: battery command: charge parameters: target: value: 100 unit: percent state: scheduled result: null errorCode: null errorMessage: null createdAt: '2026-05-07T08:00:00.000Z' updatedAt: '2026-05-07T08:00:00.000Z' acknowledgedAt: null completedAt: null start: '2026-06-01T02:00:00.000Z' end: null endedAt: null links: self: /actions/act_2026050709a1b2c3 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryAcknowledgedAwaitingDevice: summary: Battery — dispatched, awaiting device confirmation description: >- `state: acknowledged` is the in-flight state for live device writes. `acknowledgedAt` is set; `completedAt` and `result` follow when the OEM confirms. value: success: true data: id: act_2026050710b3c4d5 deviceId: device_abc123 deviceType: battery command: auto.balance parameters: null state: acknowledged result: null errorCode: null errorMessage: null createdAt: '2026-05-07T10:00:00.000Z' updatedAt: '2026-05-07T10:00:00.500Z' acknowledgedAt: '2026-05-07T10:00:00.500Z' completedAt: null start: null end: null endedAt: null links: self: /actions/act_2026050710b3c4d5 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryCompleted: summary: Battery — completed auto.balance action value: success: true data: id: act_2026050615e6f7d8 deviceId: device_abc123 deviceType: battery command: auto.balance parameters: null state: completed result: success: true message: Mode applied errorCode: null errorMessage: null createdAt: '2026-05-06T15:30:00.000Z' updatedAt: '2026-05-06T15:30:04.000Z' acknowledgedAt: '2026-05-06T15:30:01.000Z' completedAt: '2026-05-06T15:30:04.000Z' start: null end: null endedAt: null links: self: /actions/act_2026050615e6f7d8 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryWindowedActive: summary: Battery — windowed action running between `start` and `end` description: >- Windowed actions carry both `start` and `end`. While `state: acknowledged` and the wall clock sits inside the window, the device is operating in the windowed mode. value: success: true data: id: act_2026050708e5f6g7 deviceId: device_abc123 deviceType: battery command: discharge parameters: power: value: 3 unit: kw state: acknowledged result: null errorCode: null errorMessage: null createdAt: '2026-05-07T07:30:00.000Z' updatedAt: '2026-05-07T17:00:01.000Z' acknowledgedAt: '2026-05-07T17:00:01.000Z' completedAt: null start: '2026-05-07T17:00:00.000Z' end: '2026-05-07T20:00:00.000Z' endedAt: null links: self: /actions/act_2026050708e5f6g7 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryWindowedCompleted: summary: Battery — windowed action whose window has closed description: >- `state: completed` means the command reached the device, which happens at the start of the window. `endedAt` is what says the window is over and the device is no longer held by it. Until it is set the window is still in force, even past the `end` it booked. value: success: true data: id: act_202605070ce7f9b8 deviceId: device_abc123 deviceType: battery command: charge parameters: target: value: 100 unit: percent state: completed result: success: true message: Window completed errorCode: null errorMessage: null createdAt: '2026-05-06T07:30:00.000Z' updatedAt: '2026-05-06T06:00:01.000Z' acknowledgedAt: '2026-05-06T02:00:01.000Z' completedAt: '2026-05-06T06:00:01.000Z' start: '2026-05-06T02:00:00.000Z' end: '2026-05-06T06:00:00.000Z' endedAt: '2026-05-06T06:00:03.000Z' links: self: /actions/act_202605070ce7f9b8 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryFailed: summary: Battery — the command reached the device but was rejected value: success: true data: id: act_20260505199aabbb deviceId: device_abc123 deviceType: battery command: charge parameters: target: value: 95 unit: percent state: failed result: null errorCode: SCHEDULER_ACTIVE errorMessage: >- A schedule is currently active on the device and must be cleared first. createdAt: '2026-05-05T19:10:00.000Z' updatedAt: '2026-05-05T19:10:32.000Z' acknowledgedAt: '2026-05-05T19:10:01.000Z' completedAt: '2026-05-05T19:10:32.000Z' start: null end: null endedAt: null links: self: /actions/act_20260505199aabbb meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryCancelledByUser: summary: Battery — scheduled action cancelled before firing description: >- Reachable from `scheduled` via `POST /actions/{actionId}/cancel`. `acknowledgedAt` stays null because the action never ran; `completedAt` is set to the moment the action was cancelled. value: success: true data: id: act_2026050709a1b2c3 deviceId: device_abc123 deviceType: battery command: charge parameters: target: value: 100 unit: percent state: cancelled result: null errorCode: null errorMessage: null createdAt: '2026-05-07T08:00:00.000Z' updatedAt: '2026-05-07T11:32:00.000Z' acknowledgedAt: null completedAt: '2026-05-07T11:32:00.000Z' start: '2026-06-01T02:00:00.000Z' end: null endedAt: null links: self: /actions/act_2026050709a1b2c3 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryQueuedBehind: summary: 'Battery — action queued via `onConflict: queue_after`' description: >- The action waits in `scheduled` state with no `start` until the conflicting predecessor reaches a terminal state. value: success: true data: id: act_2026050711h8j9k0 deviceId: device_abc123 deviceType: battery command: discharge parameters: null state: scheduled result: null errorCode: null errorMessage: null createdAt: '2026-05-07T11:00:00.000Z' updatedAt: '2026-05-07T11:00:00.000Z' acknowledgedAt: null completedAt: null start: null end: null endedAt: null links: self: /actions/act_2026050711h8j9k0 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 hvacSetOperationModeHeat: summary: HVAC — completed heat to a target temperature description: >- `heat`/`cool` carry a single `target`; `auto.maintain` carries `heatSetpoint`/`coolSetpoint`; `idle` and `auto.schedule` carry none. Parameters use the canonical `{ value, unit }` shape. value: success: true data: id: act_20260507093hvac04 deviceId: device_hvac_001 deviceType: hvac command: heat parameters: target: value: 21 unit: celsius state: completed result: success: true message: Mode applied errorCode: null errorMessage: null createdAt: '2026-05-07T09:30:00.000Z' updatedAt: '2026-05-07T09:30:02.000Z' acknowledgedAt: '2026-05-07T09:30:01.000Z' completedAt: '2026-05-07T09:30:02.000Z' start: null end: null endedAt: null links: self: /actions/act_20260507093hvac04 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 hvacScheduled: summary: HVAC — deferred action waiting for its fire time description: >- Created with `start` in the future. `state: scheduled` until the fire time, when the platform dispatches and transitions to `acknowledged`. HVAC supports deferred push just like battery. value: success: true data: id: act_20260507095hvac06 deviceId: device_hvac_001 deviceType: hvac command: heat parameters: target: value: 21 unit: celsius state: scheduled result: null errorCode: null errorMessage: null createdAt: '2026-05-07T09:00:00.000Z' updatedAt: '2026-05-07T09:00:00.000Z' acknowledgedAt: null completedAt: null start: '2026-06-01T02:00:00.000Z' end: null endedAt: null links: self: /actions/act_20260507095hvac06 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 hvacSetOperationModeAuto: summary: HVAC — acknowledged auto comfort band, awaiting confirmation value: success: true data: id: act_20260507094hvac05 deviceId: device_hvac_001 deviceType: hvac command: auto.maintain parameters: heatSetpoint: value: 20 unit: celsius coolSetpoint: value: 24 unit: celsius state: acknowledged result: null errorCode: null errorMessage: null createdAt: '2026-05-07T09:40:00.000Z' updatedAt: '2026-05-07T09:40:01.000Z' acknowledgedAt: '2026-05-07T09:40:01.000Z' completedAt: null start: null end: null endedAt: null links: self: /actions/act_20260507094hvac05 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 hvacFollowSchedule: summary: HVAC — handed control back to the device schedule 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: device_hvac_001 deviceType: hvac command: auto.schedule parameters: null state: completed result: success: true errorCode: null errorMessage: null createdAt: '2026-05-07T11:00:00.000Z' updatedAt: '2026-05-07T11:00:01.000Z' acknowledgedAt: '2026-05-07T11:00:00.500Z' completedAt: '2026-05-07T11:00:01.000Z' start: null end: null endedAt: null links: self: /actions/act_20260507110hvac02 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 hvacCompleted: summary: HVAC — completed cool to a target temperature value: success: true data: id: act_20260507120hvac03 deviceId: device_hvac_001 deviceType: hvac command: cool parameters: target: value: 22 unit: celsius state: completed result: success: true message: Mode applied errorCode: null errorMessage: null createdAt: '2026-05-07T12:00:00.000Z' updatedAt: '2026-05-07T12:00:02.000Z' acknowledgedAt: '2026-05-07T12:00:01.000Z' completedAt: '2026-05-07T12:00:02.000Z' start: null end: null endedAt: null links: self: /actions/act_20260507120hvac03 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 evChargerSetOperationModeCharge: summary: EV charger — completed charge value: success: true data: id: act_2026050711300ev01 deviceId: device_ev_001 deviceType: ev_charger command: charge parameters: null state: completed result: success: true message: EV charger started charging errorCode: null errorMessage: null createdAt: '2026-05-07T11:30:00.000Z' updatedAt: '2026-05-07T11:30:01.000Z' acknowledgedAt: '2026-05-07T11:30:00.500Z' completedAt: '2026-05-07T11:30:01.000Z' start: null end: null endedAt: null links: self: /actions/act_2026050711300ev01 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 evChargerScheduled: summary: EV charger — deferred charge waiting for its fire time description: >- Created with `start` in the future. `state: scheduled` until the fire time, when the platform dispatches and transitions to `acknowledged`. EV chargers support deferred push just like battery. value: success: true data: id: act_2026050712100ev04 deviceId: device_ev_001 deviceType: ev_charger command: charge parameters: null state: scheduled result: null errorCode: null errorMessage: null createdAt: '2026-05-07T11:00:00.000Z' updatedAt: '2026-05-07T11:00:00.000Z' acknowledgedAt: null completedAt: null start: '2026-06-01T02:00:00.000Z' end: null endedAt: null links: self: /actions/act_2026050712100ev04 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 evChargerSetOperationModeAcknowledged: summary: EV charger — charge dispatched, awaiting confirmation value: success: true data: id: act_2026050712000ev02 deviceId: device_ev_001 deviceType: ev_charger command: charge parameters: null state: acknowledged result: null errorCode: null errorMessage: null createdAt: '2026-05-07T12:00:00.000Z' updatedAt: '2026-05-07T12:00:01.000Z' acknowledgedAt: '2026-05-07T12:00:01.000Z' completedAt: null start: null end: null endedAt: null links: self: /actions/act_2026050712000ev02 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 evChargerCompleted: summary: EV charger — set to idle completed value: success: true data: id: act_2026050713000ev03 deviceId: device_ev_001 deviceType: ev_charger command: idle parameters: null state: completed result: success: true message: EV charger set to idle errorCode: null errorMessage: null createdAt: '2026-05-07T13:00:00.000Z' updatedAt: '2026-05-07T13:00:01.000Z' acknowledgedAt: '2026-05-07T13:00:00.500Z' completedAt: '2026-05-07T13:00:01.000Z' start: null end: null endedAt: null links: self: /actions/act_2026050713000ev03 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 '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: /actions/act_2026050709a1b2c3 latencyMs: 2 '404': description: Action not found or access denied. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: actionNotFound: summary: No action matches the ID for this customer value: success: false error: code: ACTION_NOT_FOUND message: The requested action was not found. details: description: Action not found or access denied meta: requestId: req_5pH1cQbY timestamp: '2026-04-29T12:00:00.000Z' path: /actions/act_unknown_999 latencyMs: 4 security: - api-key: [] x-codeSamples: - lang: curl label: curl source: |- curl --request GET \ --url 'https://api.amps.ai/actions/act_abc123' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' - lang: javascript label: Node source: >- const response = await fetch('https://api.amps.ai/actions/act_abc123', { method: 'GET', headers: { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', }, }); const data = await response.json(); - lang: python label: Python source: |- import requests url = 'https://api.amps.ai/actions/act_abc123' headers = { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', } response = requests.get(url, headers=headers) data = response.json() components: schemas: ActionResponse: oneOf: - type: object properties: deviceType: type: string const: battery description: Battery device family. command: type: string enum: - charge - discharge - idle - auto.balance - auto.reserve - auto.export description: >- The canonical command issued: `charge`, `idle`, or an `auto.*` mode. Mirrors the verb sent on dispatch. parameters: anyOf: - type: object properties: target: $ref: '#/components/schemas/Quantity' description: >- State-of-charge limit the command was bounded by. Present only for `charge`/`discharge`. power: $ref: '#/components/schemas/Quantity' description: >- Rate cap the command was issued with. Present only for `charge`/`discharge`. reserve: $ref: '#/components/schemas/Quantity' description: >- Reserve floor preserved while the command is active. Present only for `charge`/`discharge`. description: >- Constraints the command was issued with. `charge`/`discharge` may carry `target`, `power`, and `reserve`; `idle` and the `auto.*` modes carry none. - type: 'null' description: >- Constraints the command was issued with (`target`/`power`/`reserve`). Null for `idle` and the `auto.*` modes. id: type: string description: Unique action identifier. deviceId: type: string description: Device the action targets. state: type: string enum: - acknowledged - completed - failed - scheduled - cancelled description: >- Current state of the action. `scheduled` indicates a deferred action awaiting its fire time. The terminal states are `completed`, `failed`, and `cancelled`. result: anyOf: - oneOf: - type: object properties: success: type: boolean const: true message: type: string required: - success additionalProperties: false - type: object properties: success: type: boolean const: false 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 message: type: string required: - code - message additionalProperties: false required: - success - error additionalProperties: false - type: 'null' description: >- Result captured when the action reaches a terminal state. Null while pending or scheduled. errorCode: anyOf: - 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 - type: 'null' description: >- Machine-readable error code when `state` is `failed`. Null otherwise. errorMessage: anyOf: - type: string - type: 'null' description: >- Human-readable error message when `state` is `failed`. Null otherwise. createdAt: type: string format: date-time description: ISO 8601 timestamp when the action was created. updatedAt: type: string format: date-time description: ISO 8601 timestamp of the most recent state transition. acknowledgedAt: anyOf: - type: string format: date-time - type: 'null' description: >- ISO 8601 timestamp when the action was accepted. Null until acknowledged. completedAt: anyOf: - type: string format: date-time - type: 'null' description: >- ISO 8601 timestamp when the action reached a terminal state. Null until terminal. start: anyOf: - type: string format: date-time - type: 'null' description: >- Absolute firing instant for deferred actions, as an ISO 8601 timestamp. Null for immediate actions. end: anyOf: - type: string format: date-time - type: 'null' description: >- Absolute end instant for windowed actions (e.g. `charge`/`discharge` with both `start` and `end`), as an ISO 8601 timestamp. Null for immediate or open-ended actions. endedAt: anyOf: - type: string format: date-time - type: 'null' description: >- When the window actually closed and the device stopped being held by this command, as an ISO 8601 timestamp. `end` is the time the window was booked for; this is the time it was taken back. It is earlier than `end` when another command replaced this one and took the device over. Null while the window is still in force, including after `end` has passed but before the stop has landed. Null for good on an action that never booked a window. 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. required: - deviceType - command - parameters - id - deviceId - state - result - errorCode - errorMessage - createdAt - updatedAt - acknowledgedAt - completedAt - start - end - endedAt - links - type: object properties: deviceType: type: string const: hvac description: HVAC device family. 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' description: >- Target temperature the command was issued with. Present only for `heat`/`cool`. heatSetpoint: $ref: '#/components/schemas/Quantity' description: Lower comfort bound. Present only for `auto.maintain`. coolSetpoint: $ref: '#/components/schemas/Quantity' description: Upper comfort bound. Present only for `auto.maintain`. description: >- Constraints the command was issued with. `heat`/`cool` carry `target`; `auto.maintain` carries `heatSetpoint`/`coolSetpoint`; `idle` and `auto.schedule` carry none. - 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). id: type: string description: Unique action identifier. deviceId: type: string description: Device the action targets. state: type: string enum: - acknowledged - completed - failed - scheduled - cancelled description: >- Current state of the action. `scheduled` indicates a deferred action awaiting its fire time. The terminal states are `completed`, `failed`, and `cancelled`. result: anyOf: - oneOf: - type: object properties: success: type: boolean const: true message: type: string required: - success additionalProperties: false - type: object properties: success: type: boolean const: false 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 message: type: string required: - code - message additionalProperties: false required: - success - error additionalProperties: false - type: 'null' description: >- Result captured when the action reaches a terminal state. Null while pending or scheduled. errorCode: anyOf: - 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 - type: 'null' description: >- Machine-readable error code when `state` is `failed`. Null otherwise. errorMessage: anyOf: - type: string - type: 'null' description: >- Human-readable error message when `state` is `failed`. Null otherwise. createdAt: type: string format: date-time description: ISO 8601 timestamp when the action was created. updatedAt: type: string format: date-time description: ISO 8601 timestamp of the most recent state transition. acknowledgedAt: anyOf: - type: string format: date-time - type: 'null' description: >- ISO 8601 timestamp when the action was accepted. Null until acknowledged. completedAt: anyOf: - type: string format: date-time - type: 'null' description: >- ISO 8601 timestamp when the action reached a terminal state. Null until terminal. start: anyOf: - type: string format: date-time - type: 'null' description: >- Absolute firing instant for deferred actions, as an ISO 8601 timestamp. Null for immediate actions. end: anyOf: - type: string format: date-time - type: 'null' description: >- Absolute end instant for windowed actions (e.g. `charge`/`discharge` with both `start` and `end`), as an ISO 8601 timestamp. Null for immediate or open-ended actions. endedAt: anyOf: - type: string format: date-time - type: 'null' description: >- When the window actually closed and the device stopped being held by this command, as an ISO 8601 timestamp. `end` is the time the window was booked for; this is the time it was taken back. It is earlier than `end` when another command replaced this one and took the device over. Null while the window is still in force, including after `end` has passed but before the stop has landed. Null for good on an action that never booked a window. 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. required: - deviceType - command - parameters - id - deviceId - state - result - errorCode - errorMessage - createdAt - updatedAt - acknowledgedAt - completedAt - start - end - endedAt - links - type: object properties: deviceType: type: string const: ev_charger description: EV charger device family. command: type: string enum: - charge - idle - auto.charge_tariff - auto.charge_surplus_only - auto.charge_surplus_first description: >- The canonical command issued: `charge`, `idle`, or an `auto.*` mode. Mirrors the verb sent on dispatch. parameters: anyOf: - type: object properties: power: $ref: '#/components/schemas/Quantity' description: Rate cap in kilowatts the command was issued with. current: $ref: '#/components/schemas/Quantity' description: Rate cap in amperes the command was issued with. target: $ref: '#/components/schemas/Quantity' description: >- State of charge the session was told to stop at. Only chargers that can read the car's level accept it. energy: $ref: '#/components/schemas/Quantity' description: Energy the session was told to stop after delivering. description: >- Constraints the command was issued with: the rate caps (`power`/`current`) and the stop conditions (`target`/`energy`). `idle` carries none. - type: 'null' description: >- Constraints the command was issued with (`power`/`current`/`energy`). Null for `idle`, for the `auto.*` modes, and for any command sent without constraints. id: type: string description: Unique action identifier. deviceId: type: string description: Device the action targets. state: type: string enum: - acknowledged - completed - failed - scheduled - cancelled description: >- Current state of the action. `scheduled` indicates a deferred action awaiting its fire time. The terminal states are `completed`, `failed`, and `cancelled`. result: anyOf: - oneOf: - type: object properties: success: type: boolean const: true message: type: string required: - success additionalProperties: false - type: object properties: success: type: boolean const: false 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 message: type: string required: - code - message additionalProperties: false required: - success - error additionalProperties: false - type: 'null' description: >- Result captured when the action reaches a terminal state. Null while pending or scheduled. errorCode: anyOf: - 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 - type: 'null' description: >- Machine-readable error code when `state` is `failed`. Null otherwise. errorMessage: anyOf: - type: string - type: 'null' description: >- Human-readable error message when `state` is `failed`. Null otherwise. createdAt: type: string format: date-time description: ISO 8601 timestamp when the action was created. updatedAt: type: string format: date-time description: ISO 8601 timestamp of the most recent state transition. acknowledgedAt: anyOf: - type: string format: date-time - type: 'null' description: >- ISO 8601 timestamp when the action was accepted. Null until acknowledged. completedAt: anyOf: - type: string format: date-time - type: 'null' description: >- ISO 8601 timestamp when the action reached a terminal state. Null until terminal. start: anyOf: - type: string format: date-time - type: 'null' description: >- Absolute firing instant for deferred actions, as an ISO 8601 timestamp. Null for immediate actions. end: anyOf: - type: string format: date-time - type: 'null' description: >- Absolute end instant for windowed actions (e.g. `charge`/`discharge` with both `start` and `end`), as an ISO 8601 timestamp. Null for immediate or open-ended actions. endedAt: anyOf: - type: string format: date-time - type: 'null' description: >- When the window actually closed and the device stopped being held by this command, as an ISO 8601 timestamp. `end` is the time the window was booked for; this is the time it was taken back. It is earlier than `end` when another command replaced this one and took the device over. Null while the window is still in force, including after `end` has passed but before the stop has landed. Null for good on an action that never booked a window. 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. required: - deviceType - command - parameters - id - deviceId - state - result - errorCode - errorMessage - createdAt - updatedAt - acknowledgedAt - completedAt - start - end - endedAt - links title: Action Response description: >- Persistent state of a device action across its lifecycle. Mirrors the dispatch: `command` is the canonical verb, `parameters` the constraints, `deviceType` the device family (which discriminates the shape). Lifecycle states, timestamps, the `result` envelope, and `links` are universal. 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. 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. securitySchemes: api-key: type: apiKey in: header name: x-api-key ````