> ## 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. # List actions > Returns a paginated list of the actions the API key can access, across every device type, newest first. Each item is the same polymorphic action shape as `GET /actions/{actionId}`; the `deviceType` field discriminates the device family. Filter by `deviceId`, lifecycle `state`, device `type`, or end-user `userId`. Useful for finding scheduled actions to cancel or completed actions to inspect across a whole fleet. ## OpenAPI ````yaml /openapi.json get /actions 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: get: tags: - Actions summary: List actions description: >- Returns a paginated list of the actions the API key can access, across every device type, newest first. Each item is the same polymorphic action shape as `GET /actions/{actionId}`; the `deviceType` field discriminates the device family. Filter by `deviceId`, lifecycle `state`, device `type`, or end-user `userId`. Useful for finding scheduled actions to cancel or completed actions to inspect across a whole fleet. operationId: listActions parameters: - name: offset required: false in: query description: 'Number of actions to skip (default: 0).' schema: example: 0 type: number - name: limit required: false in: query description: 'Maximum number of actions to return (1-50, default: 10).' schema: example: 10 type: number - name: userId required: false in: query description: Filter by the end-user (`userId`) the device is linked to. schema: example: user_abc123 type: string - name: type required: false in: query description: Filter by device type. schema: enum: - battery - hvac - ev_charger - solar_inverter - vehicle type: string - name: state required: false in: query description: Filter by action lifecycle state. schema: enum: - acknowledged - completed - failed - scheduled - cancelled type: string - name: deviceId required: false in: query description: >- Filter to a single device. A `deviceId` the customer does not own returns an empty page. schema: example: device_abc123 type: string responses: '200': description: Actions 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/PaginatedActionResponse' meta: $ref: '#/components/schemas/ResponseMeta' examples: acrossDeviceTypes: summary: Recent actions across multiple device types description: >- The list spans every device type the customer owns. Here a battery `charge` and an HVAC `follow_schedule` come back in the same page, newest first. The `deviceType` field discriminates the family and the `command`/`parameters` shape. value: success: true data: items: - id: act_20260507110hvac02 deviceId: device_hvac_001 deviceType: hvac command: follow_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 links: self: /actions/act_20260507110hvac02 - 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 links: self: /actions/act_2026050709a1b2c3 - id: act_2026050615e6f7d8 deviceId: device_abc123 deviceType: battery command: auto.balanced 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 links: self: /actions/act_2026050615e6f7d8 pagination: limit: 10 offset: 0 total: 3 hasMore: false meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 filteredByDevice: summary: Actions for one device via `?deviceId=` description: >- Still customer-scoped: a `deviceId` the customer does not own returns an empty page rather than another tenant’s actions. value: success: true data: items: - id: act_2026050709a1b2c3 deviceId: device_abc123 deviceType: battery command: discharge parameters: target: value: 30 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-05-08T17:00:00.000Z' end: null links: self: /actions/act_2026050709a1b2c3 pagination: limit: 10 offset: 0 total: 1 hasMore: false meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 filteredByState: summary: Actions filtered by `state=scheduled` description: >- Apply `?state=scheduled` to find pending deferred actions across the fleet, e.g. before issuing a `cancel_and_replace` push. value: success: true data: items: - 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 links: self: /actions/act_2026050712100ev04 pagination: limit: 10 offset: 0 total: 1 hasMore: false meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 noActions: summary: No actions match the given filter value: success: true data: items: [] pagination: limit: 10 offset: 0 total: 0 hasMore: false meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 '400': description: >- Invalid query parameters (e.g. unrecognised `state` or `type`, `limit` outside 1-50, negative `offset`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidState: summary: Unknown lifecycle `state` value: success: false error: code: VALIDATION_ERROR message: Request validation failed. details: fields: state: - >- Invalid enum value. Expected 'acknowledged' | 'completed' | 'failed' | 'scheduled' | 'cancelled', received 'queued' description: Invalid query parameters meta: requestId: req_3kL9mNrZ timestamp: '2026-04-29T12:00:00.000Z' path: /actions?state=queued latencyMs: 3 invalidType: summary: Unknown device `type` value: success: false error: code: VALIDATION_ERROR message: Request validation failed. details: fields: type: - >- Invalid enum value. Expected 'battery' | 'hvac' | 'ev_charger' | 'solar_inverter' | 'vehicle', received 'thermostat' description: Invalid query parameters meta: requestId: req_4mK0nOsA timestamp: '2026-04-29T12:00:00.000Z' path: /actions?type=thermostat 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: /actions latencyMs: 2 security: - api-key: [] x-codeSamples: - lang: curl label: curl source: |- curl --request GET \ --url 'https://api.amps.ai/actions' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' - lang: javascript label: Node source: |- const response = await fetch('https://api.amps.ai/actions', { 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' headers = { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', } response = requests.get(url, headers=headers) data = response.json() components: schemas: PaginatedActionResponse: type: object properties: items: type: array items: oneOf: - type: object properties: deviceType: type: string const: battery description: Battery device family. command: type: string enum: - charge - discharge - idle - auto.balanced - auto.reserve - auto.export description: >- The canonical command issued: `charge`, `discharge`, `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 - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - 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_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 - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - SETTING_OUT_OF_RANGE - 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 - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - 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_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 - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - SETTING_OUT_OF_RANGE - 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. 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 - links - type: object properties: deviceType: type: string const: hvac description: HVAC device family. command: type: string enum: - heat - cool - idle - auto - follow_schedule description: >- The canonical command issued: `heat`, `cool`, `idle`, `auto`, or `follow_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`. coolSetpoint: $ref: '#/components/schemas/Quantity' description: Upper comfort bound. Present only for `auto`. description: >- Constraints the command was issued with. `heat`/`cool` carry `target`; `auto` carries `heatSetpoint`/`coolSetpoint`; `idle` and `follow_schedule` carry none. - type: 'null' description: >- Constraints the command was issued with. `heat`/`cool` carry `target`; `auto` carries `heatSetpoint`/`coolSetpoint`; `idle` and `follow_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 - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - 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_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 - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - SETTING_OUT_OF_RANGE - 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 - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - 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_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 - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - SETTING_OUT_OF_RANGE - 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. 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 - links - type: object properties: deviceType: type: string const: ev_charger description: EV charger device family. command: type: string enum: - charge - idle description: >- The canonical command issued: `charge` or `idle`. Mirrors the verb sent on dispatch. parameters: type: 'null' description: EV charger commands carry no constraints (always 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 - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - 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_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 - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - SETTING_OUT_OF_RANGE - 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 - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - 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_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 - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - SETTING_OUT_OF_RANGE - 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. 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 - links pagination: type: object properties: limit: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Maximum number of items returned. offset: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Number of items skipped. total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total number of items matching the query. hasMore: type: boolean description: '`true` if more items exist beyond the current page.' required: - limit - offset - total - hasMore required: - items - pagination title: Paginated Action Response description: Paginated list of actions for a device, ordered most recent first. 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 - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - 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_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 - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - SETTING_OUT_OF_RANGE - 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 ````