> ## 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 EV Charger state > Retrieve the current state of an EV Charger device including charging status, power, and connection state ## OpenAPI ````yaml /openapi.json get /ev-charger/{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: /ev-charger/{deviceId}: get: tags: - EV Charger summary: Get EV Charger state description: >- Retrieve the current state of an EV Charger device including charging status, power, and connection state operationId: getEvCharger parameters: - name: expedite required: false in: query description: Use expedite cache with 1 minute TTL instead of normal 15 minute TTL schema: example: false type: boolean - name: deviceId required: true in: path description: The unique identifier for the EV Charger device schema: example: device_abc123 type: string responses: '200': description: EV Charger state 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/EvChargerResponse' meta: $ref: '#/components/schemas/ResponseMeta' examples: chargerCharging: summary: Charger actively charging a connected vehicle description: >- `status: charging`, vehicle plugged in, `currentPower` reflects live draw. `commands` advertises the canonical control surface this charger implements — the rate mode (`charge`), the stop (`idle`), and the smart-charging modes (`auto.charge_tariff`, `auto.charge_surplus_only`, `auto.charge_surplus_first`) — each with the parameter bounds and execution shapes it accepts. `settings` carries the writable constraints. value: success: true data: id: device_ev_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: Wallbox 7kW source: live state: status: charging isConnected: true isCharging: true currentPower: 7 maxCurrent: 32 powerRateLimit: 7.4 sessionEnergy: 12.6 phases: 1 voltage: 230 commands: charge: parameters: power: unit: kw min: 1.4 max: 22 step: 0.1 current: unit: amps min: 6 max: 32 step: 1 energy: unit: kwh min: 1 max: 100 execution: - immediate - scheduled - windowed idle: parameters: {} execution: - immediate - scheduled auto.charge_tariff: parameters: {} execution: - immediate - scheduled auto.charge_surplus_only: parameters: {} execution: - immediate - scheduled auto.charge_surplus_first: parameters: {} execution: - immediate - scheduled conflictStrategies: - cancel_and_replace - queue_after sessions: true settings: max_charge_rate: value: 11 unit: kw min: 0 max: 50 step: 0.1 max_charge_current: value: 32 unit: amps min: 6 max: 32 step: 1 cable_lock: value: true lastAction: id: action_ev_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_ev_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 chargerDischarging: summary: Charger exporting from the vehicle back to the home or grid description: >- `status: discharging` with a negative `currentPower`: energy is moving out of the vehicle, not into it. `isCharging` stays `false` because it means "delivering power TO the vehicle", so a caller reading it alone never mistakes an export for a charge. value: success: true data: id: device_ev_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T18:04:12.000Z' metadata: model: Wallbox 7kW source: live state: status: discharging isConnected: true isCharging: false currentPower: -3.6 maxCurrent: 32 powerRateLimit: 7.4 phases: 1 voltage: 230 commands: charge: parameters: power: unit: kw min: 1.4 max: 22 step: 0.1 current: unit: amps min: 6 max: 32 step: 1 energy: unit: kwh min: 1 max: 100 execution: - immediate - scheduled - windowed idle: parameters: {} execution: - immediate - scheduled auto.charge_tariff: parameters: {} execution: - immediate - scheduled auto.charge_surplus_only: parameters: {} execution: - immediate - scheduled auto.charge_surplus_first: parameters: {} execution: - immediate - scheduled conflictStrategies: - cancel_and_replace - queue_after sessions: true settings: max_charge_rate: value: 11 unit: kw min: 0 max: 50 step: 0.1 max_charge_current: value: 32 unit: amps min: 6 max: 32 step: 1 cable_lock: value: true lastAction: id: action_ev_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_ev_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 chargerIdle: summary: Charger plugged in but not delivering power description: >- Vehicle connected and nothing flowing. `notChargingReason` says why, so a client can tell "the car is full" from "the charger is waiting for an RFID card". It is absent while charging, while nothing is plugged in, and on chargers that do not report a reason. value: success: true data: id: device_ev_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: Wallbox 7kW source: cache state: status: available isConnected: true isCharging: false currentPower: 0 maxCurrent: 32 powerRateLimit: 7.4 sessionEnergy: 31.2 phases: 1 voltage: 230 notChargingReason: vehicle conflictStrategies: - cancel_and_replace - queue_after sessions: true lastAction: id: action_ev_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_ev_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 chargerUnderTariffControl: summary: >- Charger handed to its own tariff optimiser, waiting for a cheap hour description: >- `activeControlMode` is what tells this apart from a charger a customer paused: both report `isCharging: false` with a vehicle plugged in. It names the control regime the charger says it is under, and it is absent on a charger that does not report one. value: success: true data: id: device_ev_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T23:10:02.000Z' metadata: model: Wallbox 7kW source: live state: status: scheduled isConnected: true isCharging: false currentPower: 0 maxCurrent: 32 powerRateLimit: 7.4 notChargingReason: schedule activeControlMode: auto.charge_tariff conflictStrategies: - cancel_and_replace - queue_after sessions: true lastAction: id: action_ev_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_ev_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 chargerAvailable: summary: Charger ready, no vehicle connected value: success: true data: id: device_ev_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: Wallbox 7kW source: cache state: status: available isConnected: false isCharging: false currentPower: 0 maxCurrent: 32 powerRateLimit: 7.4 conflictStrategies: - cancel_and_replace - queue_after sessions: true lastAction: id: action_ev_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_ev_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 chargerWithSchedule: summary: Charger waiting for a scheduled charging session description: >- `status: scheduled` indicates the OEM has a pending schedule. The platform itself uses immediate dispatch; this state reflects an OEM-side schedule (e.g. set in the OEM app). value: success: true data: id: device_ev_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: Wallbox 7kW source: live state: status: scheduled isConnected: true isCharging: false currentPower: 0 maxCurrent: 32 powerRateLimit: 7.4 conflictStrategies: - cancel_and_replace - queue_after sessions: true lastAction: id: action_ev_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_ev_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 chargerOffline: summary: Charger unreachable description: >- `status: offline` and `sync.available: false`. The last successful pull is in `sync.lastPulledAt`. value: success: true data: id: device_ev_001 vendor: example_vendor_a sync: available: false lastPulledAt: '2026-05-06T22:14:10.000Z' metadata: model: Wallbox 7kW source: fallback state: status: offline isConnected: false isCharging: false currentPower: 0 maxCurrent: 32 powerRateLimit: 7.4 conflictStrategies: - cancel_and_replace - queue_after sessions: true lastAction: id: action_ev_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_ev_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 chargerError: summary: Charger reporting a hardware error description: >- `status: error` indicates the device is reachable but in a fault state. Resolve via the OEM app or a power cycle before pushing. value: success: true data: id: device_ev_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: Wallbox 7kW source: live state: status: error isConnected: true isCharging: false currentPower: 0 maxCurrent: 32 powerRateLimit: 7.4 conflictStrategies: - cancel_and_replace - queue_after sessions: true lastAction: id: action_ev_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_ev_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 '400': description: >- The device manufacturer rejected the pull request (`INVALID_PARAMETERS` or `COMMAND_FAILED`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '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: /ev-charger/device_ev_001 latencyMs: 2 '403': description: >- Live access is disabled, consent is revoked, the device allowance is exceeded, or the manufacturer denied access to the device (`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: /ev-charger/device_unknown_999 latencyMs: 5 '410': description: >- The device is offline at the manufacturer (`DEVICE_OFFLINE`). See the [device error codes](/reference/error-codes) reference. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: deviceOffline: summary: >- The manufacturer reports the device as offline. Use the cached state from the previous pull, or retry once the device is back online. value: success: false error: code: DEVICE_OFFLINE message: The device is currently offline at the manufacturer. meta: requestId: req_FnP7tAhH timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_abc123 latencyMs: 142 '503': description: >- The device manufacturer service is temporarily unavailable (`SERVICE_UNAVAILABLE`). Retryable with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: >- The manufacturer cloud is down or refusing requests. Retry with backoff. value: success: false error: code: SERVICE_UNAVAILABLE message: >- The device manufacturer service is temporarily unavailable. meta: requestId: req_GoQ8uBiI timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_abc123 latencyMs: 1873 security: - api-key: [] x-codeSamples: - lang: curl label: curl source: |- curl --request GET \ --url 'https://api.amps.ai/ev-charger/device_abc123' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' - lang: javascript label: Node source: >- const response = await fetch('https://api.amps.ai/ev-charger/device_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/ev-charger/device_abc123' headers = { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', } response = requests.get(url, headers=headers) data = response.json() components: schemas: EvChargerResponse: type: object properties: id: type: string description: Unique identifier for the EV charger device. vendor: type: string description: OEM display name (e.g. `tesla`, `chargepoint`). sync: type: object properties: available: type: boolean lastPulledAt: anyOf: - type: string - type: 'null' required: - available - lastPulledAt metadata: type: object properties: model: type: string cacheType: type: string enum: - expedite - normal source: type: string enum: - cache - live - fallback - projection description: >- How this device-state reading was obtained. `live`: read from the device just now. `cache`: a recent reading served from cache. `fallback`: the most recent stored reading, returned when the device could not be reached. `projection`: simulated sandbox state — sandbox devices are not physical hardware, so their reported state reflects the commands you have sent. degraded: description: >- Present and `true` when this reading was served from stored state because the platform is temporarily not contacting this device’s manufacturer (a protective circuit is open). The data is the most recent known reading, not a live one. Absent on a normal reading. type: boolean required: - model - source state: type: object properties: status: type: string enum: - available - charging - discharging - scheduled - error - offline description: >- What the charger is doing. `charging` and `discharging` are distinct: a vehicle-to-home or vehicle-to-grid export reports `discharging` (with a negative `currentPower`), never `charging`. isConnected: type: boolean description: Whether a vehicle is currently plugged in. isCharging: type: boolean description: >- Whether the charger is actively delivering power TO the vehicle right now. `false` during a vehicle-to-home or vehicle-to-grid export, which moves energy the other way. currentPower: description: >- Current power in kW, signed: positive while charging the vehicle, negative while discharging it back to the home or the grid. Absent when the charger does not report power at all; a charger sitting idle reports `0`. type: number maxCurrent: description: >- Maximum current the charger can deliver in amps. Absent when the charger does not report its applied ceiling. type: number minimum: 0 powerRateLimit: description: >- Configured maximum charging power in kW. Absent when the charger does not report it. type: number minimum: 0 sessionEnergy: description: >- Energy delivered so far in the current charging session, in kWh. Absent when the charger does not report it, or when no session is open. type: number minimum: 0 phases: description: >- Number of supply phases the charger is drawing on (1-3). Absent when the charger does not report it. type: integer minimum: 1 maximum: 3 voltage: description: >- Supply voltage in volts. Absent when the charger does not report it. type: number exclusiveMinimum: 0 notChargingReason: description: >- Why a plugged-in vehicle is not charging: `vehicle` (the car declined the charge or is not ready), `target_reached` (the car reached its charge target and stopped — full or its own limit, a finished charge rather than a declined one), `charger` (the charger is limiting or curtailing), `load_management` (a site-level power share is holding the charge — normal operation, the caller waits rather than investigates), `authorization` (waiting for an RFID card or app approval), `schedule` (the charger's own schedule vetoes charging right now), or `unknown` (the charger is paused but will not say why). Absent while charging, while nothing is plugged in, or when the charger reports nothing at all — which is not the same as `unknown`, where the charger reports a pause whose cause it does not name. type: string enum: - vehicle - target_reached - charger - load_management - authorization - schedule - unknown activeControlMode: description: >- The canonical mode the charger reports it is operating under. `isCharging` says whether energy is flowing; this says which control regime put it that way, so a charger paused by `auto.charge_tariff` because the price is high can be told from one a customer stopped. Absent when the charger does not report its regime. type: string enum: - charge - idle - auto.charge_tariff - auto.charge_surplus_only - auto.charge_surplus_first required: - status - isConnected - isCharging commands: description: >- Per-command capability surface for this device. An open record keyed by the canonical command name. Each entry exposes its parameter bounds and the execution shapes the device accepts, so this map is what you read to discover what a given charger can be asked to do — a command it does not declare here is rejected if used. Absent when the device declares no commands. type: object propertyNames: type: string additionalProperties: type: object properties: parameters: type: object propertyNames: type: string additionalProperties: type: object properties: unit: description: Unit of measure (e.g. `percent`, `kw`, `celsius`). type: string min: description: Lower bound for the parameter value. type: number max: description: Upper bound for the parameter value. type: number step: description: >- Increment the value must land on, counted from `min` (or from 0 when no `min` is declared). A value off the grid is rejected. Absent when the device accepts any value within the bounds. type: number execution: type: array items: type: string enum: - immediate - scheduled - windowed required: - parameters - execution conflictStrategies: type: array items: type: string enum: - cancel_and_replace - queue_after description: >- Conflict-resolution strategies this device accepts on `onConflict`. Empty when the device declares none. settings: description: >- Per-setting current value and bounds for this device. Open record keyed by the canonical setting name (`max_charge_rate`, `max_charge_current`, `cable_lock`). Presence-based: a key appears only when the device exposes that setting. Absent when the device declares no settings. type: object propertyNames: type: string additionalProperties: type: object properties: value: anyOf: - anyOf: - type: number - type: boolean - type: string - type: 'null' description: >- Current setting value. `null` if the device has not yet synced this setting. unit: description: Unit of measure for numeric settings. type: string min: description: Lower bound for the setting value. type: number max: description: Upper bound for the setting value. type: number step: description: >- Increment the value must land on, counted from `min` (or from 0 when no `min` is declared). A write off the grid is rejected. Absent when the device accepts any value within the bounds. type: number required: - value sessions: type: boolean description: >- Whether this charger reports charging-session history. `true` means `GET /ev-charger/{deviceId}/sessions` serves it; `false` means the manufacturer records none and that endpoint answers 422 `SESSIONS_NOT_SUPPORTED`. Read it before calling, rather than learning from the refusal. scheduling: type: object properties: maxSlots: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- The largest number of slots a single schedule on this device can hold. supportsRecurrence: type: boolean description: >- Whether this device accepts a `recurrence` rule on a schedule. When `false`, only one-shot schedules are accepted. slotVariants: type: array items: type: string enum: - at - time description: >- The slot variants this device accepts. `at` = an absolute ISO 8601 timestamp; `time` = a wall-clock `HH:mm` resolved against a schedule-level IANA `timezone`. A schedule may not mix the two. supportedRecurrence: description: >- The recurrence rules this device accepts, when `supportsRecurrence` is `true`. Absent when the device declares no recurrence support. type: array items: type: string enum: - daily - weekly minSlotDuration: description: >- The shortest slot duration this device honours, as an ISO 8601 duration (e.g. `PT15M`). Absent when the device declares no minimum. type: string required: - maxSlots - supportsRecurrence - slotVariants description: >- The device's scheduling limits (max slots, supported slot variants, recurrence support). Presence-based and published ahead of the scheduler: the whole block is absent until the device declares its scheduling capabilities. Schedules are set on the device via `PUT /{type}/{id}/schedule` (coming soon) and followed today via the `auto.schedule` command. lastAction: anyOf: - type: object properties: id: type: string description: >- Unique action identifier. Fetch the full record at `links.self`. command: type: string description: >- The canonical verb of the action (e.g. `charge`, `heat`, `auto.schedule`). Derived from the same source as `GET /actions`, so it always matches the full record. state: type: string enum: - acknowledged - completed - failed - scheduled - cancelled description: >- Lifecycle state of the action. `scheduled` indicates a deferred action awaiting its fire time; the terminal states are `completed`, `failed`, and `cancelled`. 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 change. 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. Lets a device card show the failure reason without fetching the full record. errorMessage: anyOf: - type: string - type: 'null' description: >- Human-readable error message when `state` is `failed`. Null otherwise. links: type: object properties: self: type: string description: >- Canonical path to the full action record: `GET /actions/{actionId}`. required: - self description: Hypermedia link to the full action record. required: - id - command - state - createdAt - updatedAt - errorCode - errorMessage - links description: >- Summary of the most recent action dispatched to this device. A pointer, not a copy: the full record (parameters, timestamps, result) is at `links.self`. - type: 'null' description: >- Summary of the most recent action dispatched to this device; full record at `links.self`. Null when the device has no actions yet. A pointer for the "render a device card in one call" case, not a denormalised copy. currentSchedule: anyOf: - type: object properties: id: type: string description: >- Unique schedule identifier. Fetch the full schedule at `links.self`. status: type: string description: >- Lifecycle status of the schedule (e.g. `active`). The full status vocabulary lands with the scheduler. links: type: object properties: self: type: string description: >- Canonical path to the device's full schedule: `GET /{type}/{id}/schedule`. required: - self description: Hypermedia link to the full schedule. required: - id - status - links description: >- Summary of the schedule currently governing this device. A pointer, not a copy: the full schedule is at `links.self`. - type: 'null' description: >- The device's active Amps schedule. Always null until the scheduler ships. required: - id - vendor - sync - metadata - state - conflictStrategies - sessions - lastAction - currentSchedule title: EV Charger Response 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. securitySchemes: api-key: type: apiKey in: header name: x-api-key ````