> ## Documentation Index > Fetch the complete documentation index at: https://docs.amps.ai/llms.txt > Use this file to discover all available pages before exploring further. # Push EV Charger action > Send a command to an EV Charger device. The action is processed asynchronously and a webhook is sent on completion. ## OpenAPI ````yaml /openapi.json post /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}: post: tags: - EV Charger summary: Push EV Charger action description: >- Send a command to an EV Charger device. The action is processed asynchronously and a webhook is sent on completion. operationId: pushEvCharger parameters: - name: deviceId required: true in: path description: The unique identifier for the EV Charger device schema: example: device_abc123 type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EvChargerPushRequest' examples: charge: summary: Begin charging the connected vehicle description: >- Every parameter is optional. Sent bare, the charger draws at whatever rate it and the vehicle negotiate, until the vehicle stops it. Add a rate cap (`power` or `current`) to hold it below that, or the `energy` stop condition to end the session early. value: action: command: charge idle: summary: Pause charging, holding the session description: >- `command: idle` is the canonical stop. It takes no parameters. Idempotent if the charger is not charging. value: action: command: idle chargeRateCapped: summary: Charge at a capped rate through an off-peak window description: >- A rate cap plus a window: charge at no more than 4.2 kW between the two wall-clock times. Supply `power` (kW) or `current` (A), never both — they cap the same ceiling, so two values leave it ambiguous and the request is refused. `onConflict` clears whatever the charger was already doing. value: action: command: charge parameters: power: value: 4.2 unit: kw start: '2026-06-01T22:00:00' end: '2026-06-02T05:00:00' onConflict: cancel_and_replace autoCheapest: summary: Hand charging to the charger's own tariff optimiser description: >- The smart-charging shape. `auto.charge_tariff` hands the charger its own tariff schedule and lets it decide when and how fast to draw; it runs until another command replaces it. It takes no parameters and no `end`: a goal such as "80% by 07:00" needs a planner reading the vehicle's state of charge, which the platform does not have, so it is refused rather than answered with a mode change. value: action: command: auto.charge_tariff chargeUntilEnergyDelivered: summary: Deliver a fixed amount of energy, then stop description: >- A stop condition rather than a rate cap: charge until 20 kWh has gone into the vehicle, then stop on its own. Use `energy` when you are buying a quantity. value: action: command: charge parameters: energy: value: 20 unit: kwh chargeScheduled: summary: Charge starting at a future time (deferred) description: >- `start` alone schedules the action to fire at the given time. Returns 202 with `state: scheduled`. Times are plant-local wall-clock — no `Z`, no `+HH:MM` — interpreted in the charger's own timezone, so you never convert. A relative duration (`30m`, `1.5h`) is also accepted. value: action: command: charge start: '2026-06-01T22:00:00' chargeWindowed: summary: Charge during an off-peak window (start + end) description: >- `start` + `end` together describe a windowed action, available on any mode whose `execution` set includes `windowed`. The session begins at `start` and the window closes at `end`. value: action: command: charge start: '2026-06-01T22:00:00' end: '2026-06-02T05:00:00' chargeWithConflictStrategy: summary: Charge with a conflict-resolution strategy description: >- `onConflict: cancel_and_replace` replaces a scheduled or windowed conflict that has not been dispatched yet. A command already sent to the manufacturer cannot be recalled, so it returns 409 `CONFLICT_IN_EXECUTION`. value: action: command: charge onConflict: cancel_and_replace sandboxFail: summary: Simulate a failure in sandbox description: >- Sandbox-only. Use `sandbox.result: "failed"` plus an `errorCode` to test client error handling without touching a real device. value: action: command: charge sandbox: result: failed errorCode: COMMAND_NOT_SUPPORTED responses: '202': description: Action acknowledged and queued for processing content: application/json: schema: type: object required: - success - data - meta properties: success: type: boolean const: true description: Always `true` for success responses. data: $ref: '#/components/schemas/EvChargerPushResponse' meta: $ref: '#/components/schemas/ResponseMeta' examples: setOperationModeAcknowledged: summary: Operation mode dispatched description: >- The response mirrors the dispatch: `command` + `deviceType` + the `parameters` the command carried (`null` when it carried none). Track the action at `links.self`. value: success: true data: id: act_2026050712000ev02 deviceId: dev_ev7a3b1f deviceType: ev_charger command: charge parameters: power: value: 7.4 unit: kw state: acknowledged createdAt: '2026-05-07T12:00:00.000Z' start: null links: self: /actions/act_2026050712000ev02 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 deferredScheduled: summary: Deferred action scheduled to fire at `start` description: >- `state: scheduled` and `start` carries the absolute fire time. The session begins when the scheduled instant arrives. Cancel via `POST /actions/{actionId}/cancel` before then. value: success: true data: id: act_2026050708000ev03 deviceId: dev_ev7a3b1f deviceType: ev_charger command: charge parameters: null state: scheduled createdAt: '2026-05-07T08:00:00.000Z' start: '2026-06-01T22:00:00.000Z' links: self: /actions/act_2026050708000ev03 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 acceptedWithWarning: summary: 'Accepted with a heads-up: no vehicle connected' description: >- The command is accepted and armed; `warnings` names what must clear before it takes effect. Absence of `warnings` is the all-clear. Warnings never appear on deferred pushes. value: success: true data: id: act_2026050712450ev04 deviceId: dev_ev7a3b1f deviceType: ev_charger command: charge parameters: null state: acknowledged createdAt: '2026-05-07T12:45:00.000Z' start: null links: self: /actions/act_2026050712450ev04 warnings: - code: vehicle_not_connected message: >- No vehicle is connected to the charger. The command is accepted and takes effect when a vehicle plugs in. observedAt: '2026-05-07T12:44:31.000Z' meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 idleCompleted: summary: Idle completed synchronously description: >- Some OEMs return a synchronous confirmation; others remain `acknowledged` until the device echoes the new mode. value: success: true data: id: act_2026050711300ev01 deviceId: dev_ev7a3b1f deviceType: ev_charger command: idle parameters: null state: completed createdAt: '2026-05-07T11:30:00.000Z' links: self: /actions/act_2026050711300ev01 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 '400': description: >- Invalid request body. The device manufacturer can also refuse a well-formed request with this status (`COMMAND_FAILED`, `INVALID_PARAMETERS`, `UNSUPPORTED_CREDENTIAL_TYPE`). Every code at this status: `COMMAND_FAILED`, `INVALID_PARAMETERS`, `INVALID_REQUEST_BODY`, `UNSUPPORTED_CREDENTIAL_TYPE`, `VALIDATION_ERROR`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingAction: summary: '`action` field missing from the body' value: success: false error: code: INVALID_REQUEST_BODY message: The request body is invalid. details: fields: action: - Required description: Invalid request body meta: requestId: req_1bA0eFgC timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 3 missingCommand: summary: >- `action` is present but carries no `command`. A command the platform does not recognise (`auto.cheapest`) is NOT a 400 — it is a 422 `UNSUPPORTED_MODE` naming the modes this charger accepts, exactly like a canonical command from another device family such as `discharge`. value: success: false error: code: INVALID_REQUEST_BODY message: The request body is invalid. details: fields: action.command: - >- Unsupported command. This device supports: `charge`, `idle`, `auto.charge_tariff`, `auto.charge_surplus_only`, `auto.charge_surplus_first`. description: Invalid request body meta: requestId: req_6mE3jKlW timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 3 '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: No `x-api-key` header present value: success: false error: code: UNAUTHORIZED message: Authentication is required. details: description: API key is required meta: requestId: req_8sW2dRtX timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 2 '403': description: >- Error codes: `FORBIDDEN`, `INVALID_MFA_CODE`, `MFA_REQUIRED`, `ACCOUNT_LOCKED`, `DEVICE_UNAUTHORIZED`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Device not found or access denied content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: deviceNotFound: summary: No device matches the ID for this customer value: success: false error: code: DEVICE_NOT_FOUND message: No matching device was found for the supplied details. details: description: Device not found or access denied meta: requestId: req_5pH1cQbY timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_unknown_999 latencyMs: 5 '409': description: >- A conflicting action is already in progress. Provide `onConflict: "cancel_and_replace"` to resolve automatically. The error `details.conflictingActionIds` lists the actions you need to consider. Every code at this status: `CONFLICT`, `CONFLICT_IN_EXECUTION`, `VEHICLE_NOT_CONNECTED`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflictNoStrategy: summary: Another action is already in flight on this charger value: success: false error: code: CONFLICT message: The request conflicts with the current resource state. details: reason: no_strategy_supplied conflictingActionIds: - act_2026050712000ev02 strategies: - cancel_and_replace description: >- A conflicting action is already pending for this device. Provide onConflict to resolve automatically, or cancel the existing action. meta: requestId: req_2cB5gNqR timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 12 '410': description: 'Error codes: `DEVICE_OFFLINE`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: 'Error codes: `PAYLOAD_TOO_LARGE`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '415': description: 'Error codes: `UNSUPPORTED_MEDIA_TYPE`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- The request is well-formed but violates a device or canonical constraint. Common codes: `COMMAND_NOT_SUPPORTED` (the charger does not implement this command), `UNSUPPORTED_MODE`, `STRATEGY_NOT_SUPPORTED`. A route that is built but not switched on for live yet answers `503 NOT_YET_AVAILABLE` instead, never this status. Every code at this status: `COMMAND_NOT_SUPPORTED`, `DIRECT_ACTION_UNSUPPORTED`, `EXECUTION_NOT_SUPPORTED`, `INVALID_TIMEZONE`, `INVALID_TIME_WINDOW`, `PARAMETER_OUT_OF_RANGE`, `SESSIONS_NOT_SUPPORTED`, `SETTING_OUT_OF_RANGE`, `START_INVALID_FORMAT`, `START_IN_PAST`, `START_NONEXISTENT_WALL_CLOCK`, `START_OFFSET_NOT_ACCEPTED`, `START_OUT_OF_RANGE`, `STRATEGY_NOT_SUPPORTED`, `TIMEZONE_UNRESOLVED`, `UNSUPPORTED_ACTION`, `UNSUPPORTED_MODE`, `UNSUPPORTED_PARAMETER`, `UNSUPPORTED_PARAMETER_COMBINATION`, `UNSUPPORTED_UNIT`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unsupportedMode: summary: >- `heat` is a canonical command, but it belongs to a thermostat, not a charger. The body is well-formed, so it is a recoverable 422 listing the modes this charger does support, not a 400. value: success: false error: code: UNSUPPORTED_MODE message: The requested mode is not supported by this device. details: deviceCapabilities: supportedModes: - charge - idle - auto.charge_tariff - auto.charge_surplus_only - auto.charge_surplus_first description: Mode `heat` is not supported by this device. meta: requestId: req_4eD7iPuU timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 9 unsupportedParameter: summary: >- `reserve` is a battery parameter and is not declared on an EV `charge`. The 422 names the offending key and lists what the mode does accept. value: success: false error: code: UNSUPPORTED_PARAMETER message: One or more parameters are not supported by this device. details: unsupportedParameters: - reserve deviceCapabilities: supportedParameters: - power - current - energy description: 'Parameter(s) not supported for mode `charge`: reserve.' meta: requestId: req_5fE8jQvV timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 8 unsupportedCombination: summary: >- Both rate caps sent on one command. A charger accepts either lever, but two ceilings on one request would leave the device to choose — so it is refused rather than silently reinterpreted. value: success: false error: code: UNSUPPORTED_PARAMETER_COMBINATION message: Two supplied parameters cannot ride the same command. details: conflictingParameters: - power - current description: >- Parameters `power` and `current` cannot be supplied on the same command — they cap the same rate, so two values leave the ceiling ambiguous. Supply one. meta: requestId: req_8jH1mUyZ timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 7 parameterOffStep: summary: >- A value inside `min`/`max` but between the accepted increments. `details.step` is the bound a caller cannot infer from the range, so it rides along and the request can be rounded to a legal value without a second GET. value: success: false error: code: PARAMETER_OUT_OF_RANGE message: One or more parameters are outside the supported range. details: parameter: power value: 7.05 min: 1.4 max: 22 step: 0.1 unit: kw description: >- Parameter `power` value 7.05 is not an accepted increment: values step by 0.1 from 1.4. meta: requestId: req_9kI2nVaA timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 7 executionNotSupported: summary: >- Caller requested `windowed` (start + end) on a mode that only supports `immediate` and `scheduled` value: success: false error: code: EXECUTION_NOT_SUPPORTED message: >- The requested execution mode is not supported for this device. details: requestedExecution: windowed supportedExecution: - immediate - scheduled description: >- Mode 'idle' does not support windowed execution on this device. Supported shapes: immediate, scheduled. meta: requestId: req_7hG0lSxX timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 6 strategyNotSupported: summary: >- `onConflict: queue_after` requested but this device declares only `cancel_and_replace` value: success: false error: code: STRATEGY_NOT_SUPPORTED message: >- The requested conflict strategy is not supported by this device. details: requestedStrategy: queue_after supportedStrategies: - cancel_and_replace description: >- Conflict strategy 'queue_after' is not supported by this device. Supported strategies: cancel_and_replace. meta: requestId: req_6gF9kRwW timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 6 '429': description: 'Error codes: `RATE_LIMITED`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 'Error codes: `INTERNAL_ERROR`, `UNKNOWN_ERROR`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': description: 'Error codes: `NETWORK_ERROR`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Two different refusals share this status. `SERVICE_UNAVAILABLE` means the manufacturer service is temporarily down: retry with exponential backoff. `NOT_YET_AVAILABLE` means Amps has not switched this route on for live yet and refused before contacting the manufacturer: do not retry it automatically, because nothing changes until the route is enabled. Every code at this status: `NOT_YET_AVAILABLE`, `OEM_CIRCUIT_OPEN`, `SERVICE_UNAVAILABLE`, `SETTINGS_STORE_UNAVAILABLE`, `SIMULATED_FAILURE`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: comingSoon: summary: >- Control is built but not yet confirmed on a real device. The platform refuses before contacting the manufacturer, so this is a 503 (temporarily unavailable, coming) rather than a permanent 422. value: success: false error: code: NOT_YET_AVAILABLE message: >- This capability is coming soon and is not yet available for this device. meta: requestId: req_3dC6hOsT timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 2 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_9kI2nVzA timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001 latencyMs: 2034 '504': description: 'Error codes: `TIMEOUT`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - api-key: [] x-codeSamples: - lang: curl label: curl source: |- curl --request POST \ --url 'https://api.amps.ai/ev-charger/device_abc123' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' \ --header 'content-type: application/json' \ --data '{ "action": { "command": "charge" } }' - lang: javascript label: Node source: >- const response = await fetch('https://api.amps.ai/ev-charger/device_abc123', { method: 'POST', headers: { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', 'content-type': 'application/json', }, body: JSON.stringify({ "action": { "command": "charge" } }), }); 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', 'content-type': 'application/json', } payload = { "action": { "command": "charge", }, } response = requests.post(url, headers=headers, json=payload) data = response.json() components: schemas: EvChargerPushRequest: type: object properties: action: $ref: '#/components/schemas/EvChargerAction' onConflict: $ref: '#/components/schemas/EvChargerOnConflict' sandbox: $ref: '#/components/schemas/EvChargerSandboxConfig' required: - action description: >- A single EV-charger action plus optional `onConflict` strategy and `sandbox` controls. Action variants describe what the API accepts. Per-device support varies; the `commands` map on `GET /ev-charger/{deviceId}` shows which actions a specific device handles. examples: - action: command: charge - action: command: idle onConflict: cancel_and_replace title: Ev Charger Push EvChargerPushResponse: type: object properties: id: type: string description: Unique identifier for the action. deviceId: type: string description: Device the action targets. deviceType: type: string const: ev_charger description: The device family the action targets. command: type: string enum: - charge - idle - auto.charge_tariff - auto.charge_surplus_only - auto.charge_surplus_first description: The canonical command issued. Mirrors the verb sent on dispatch. parameters: anyOf: - type: object properties: power: $ref: '#/components/schemas/Quantity' current: $ref: '#/components/schemas/Quantity' target: $ref: '#/components/schemas/Quantity' energy: $ref: '#/components/schemas/Quantity' - type: 'null' description: >- Constraints the command was issued with: the rate caps (`power`/`current`) and the stop conditions (`target`/`energy`). Null for `idle` and the `auto.*` modes, which take none, and for any command sent without constraints. state: type: string enum: - acknowledged - completed - failed - scheduled - cancelled description: >- Current state of the action. `scheduled` indicates a deferred action awaiting its fire time. `cancelled` is a terminal state reachable from `scheduled` via POST /actions/{actionId}/cancel. createdAt: type: string format: date-time description: Timestamp when the action was created. start: description: >- Absolute firing instant for deferred actions, as an ISO 8601 timestamp. Null or absent for immediate actions. anyOf: - type: string format: date-time - type: 'null' end: description: >- Absolute end instant for windowed actions, as an ISO 8601 timestamp. Present whenever `end` was requested, including a window sent without a `start`, which runs from now until this instant. Null or absent when no `end` was requested. anyOf: - type: string format: date-time - type: 'null' links: type: object properties: self: type: string description: >- Canonical path to this action: `GET /actions/{actionId}`. Poll it to follow the action to a terminal state. required: - self description: Hypermedia links for this action. warnings: description: >- Conditions observed at submission that delay the command taking effect. The command is accepted; each entry names what must clear first. Advisory and best-effort: absence means nothing to report, not a guarantee that nothing is blocking. Never sent for deferred pushes (the state now does not describe the fire time). type: array items: $ref: '#/components/schemas/PushWarning' required: - id - deviceId - deviceType - command - parameters - state - createdAt - links title: Ev Charger Push Response description: >- Result of a push. Mirrors the dispatch (`command` + `parameters` + `deviceType`) and carries `links.self` to track the action. For immediate actions, `state` reflects the dispatch outcome. For deferred actions, `state` is `scheduled`, `start` carries the fire time, and `end` the window close when a window was requested. ResponseMeta: type: object title: Response Meta description: >- Metadata attached to every response: the request identifier, the serving environment, the build timestamp, and the server-side latency. required: - environment - timestamp - latencyMs properties: requestId: description: >- Unique request identifier. Echoes the `x-request-id` header when present; otherwise generated server-side. type: string environment: type: string description: The environment that served the request (`sandbox` or `live`). timestamp: type: string format: date-time description: ISO 8601 timestamp when the response was built. latencyMs: type: integer description: Server-side processing time in milliseconds. ErrorResponse: type: object properties: success: type: boolean description: Always `false` for error responses. error: type: object properties: code: type: string enum: - INVALID_CREDENTIALS - INVALID_API_KEY - INVALID_MFA_CODE - MFA_REQUIRED - ACCOUNT_LOCKED - UNSUPPORTED_CREDENTIAL_TYPE - DEVICE_NOT_FOUND - DEVICE_OFFLINE - DEVICE_UNAUTHORIZED - NO_DEVICES_FOUND - COMMAND_FAILED - COMMAND_NOT_SUPPORTED - EXECUTION_NOT_SUPPORTED - MODE_OVERRIDDEN - VPP_LOCKED - INVALID_PARAMETERS - INVALID_OEM_PARAMETERS - INVALID_TIME_WINDOW - BIND_NOT_SUPPORTED - SCHEDULER_ACTIVE - SCHEDULER_FULL - UNSUPPORTED_AUTH_PATH - SETTING_OUT_OF_RANGE - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - VEHICLE_NOT_CONNECTED - SESSIONS_NOT_SUPPORTED - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - INVALID_OEM_RESPONSE - COMMAND_NOT_APPLIED - STALE_ACTION - DEFERRED_SCHEDULE_FAILED - UNROUTABLE_ACTION_TYPE - UNAUTHORIZED - EXPIRED_TOKEN - FORBIDDEN - INSUFFICIENT_PERMISSIONS - LIVE_ACCESS_DISABLED - VALIDATION_ERROR - INVALID_INPUT - INVALID_REQUEST_BODY - EMPTY_SETTINGS - PAYLOAD_TOO_LARGE - UNSUPPORTED_MEDIA_TYPE - NOT_FOUND - METHOD_NOT_ALLOWED - CONFLICT - CONFLICT_IN_EXECUTION - GONE - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - NOT_IMPLEMENTED - BAD_GATEWAY - GATEWAY_TIMEOUT - DEVICE_TYPE_MISMATCH - CONSENT_REVOKED - DEVICE_OVERAGE - SETTINGS_STORE_UNAVAILABLE - ACTION_NOT_FOUND - DIRECT_ACTION_UNSUPPORTED - UNSUPPORTED_ACTION - UNSUPPORTED_MODE - UNSUPPORTED_PARAMETER - UNSUPPORTED_PARAMETER_COMBINATION - UNSUPPORTED_UNIT - PARAMETER_OUT_OF_RANGE - START_IN_PAST - START_OUT_OF_RANGE - START_OFFSET_NOT_ACCEPTED - START_INVALID_FORMAT - START_NONEXISTENT_WALL_CLOCK - TIMEZONE_UNRESOLVED - INVALID_TIMEZONE - ACTION_NOT_CANCELLABLE - STRATEGY_NOT_SUPPORTED - UNSUPPORTED_SETTING - UNSUPPORTED_SETTING_COMBINATION - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - NO_OP - NO_OVERRIDE - AVAILABILITY_ENV_UNSUPPORTED - UNSUPPORTED_COMBINATION description: >- Machine-readable error code (e.g. `VALIDATION_ERROR`, `CONFLICT`, `UNSUPPORTED_MODE`). Stable across releases; safe to switch on. message: type: string description: Human-readable error message. details: description: >- Structured context for the error: which fields were invalid, which actions conflicted, which capabilities the device declares. Shape varies by error code. type: object properties: {} additionalProperties: {} required: - code - message description: Error envelope. meta: type: object properties: requestId: description: >- Unique request identifier. Echoes the `x-request-id` header when present; otherwise generated server-side. type: string timestamp: type: string description: ISO 8601 timestamp when the error response was built. path: type: string description: Request path that produced the error. latencyMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Server-side processing time in milliseconds. required: - timestamp - path - latencyMs description: Request metadata. required: - success - error - meta title: Error Response description: >- Uniform error response. The `error.code` identifies the failure, `error.message` carries a human-readable explanation, and `error.details` carries structured context (failed fields, conflicting action IDs, supported capabilities) where relevant. EvChargerAction: type: object properties: command: type: string enum: - charge - idle - auto.charge_tariff - auto.charge_surplus_only - auto.charge_surplus_first description: >- The EV charger command. Device support varies; an unavailable EV charger command is rejected at runtime with `422 UNSUPPORTED_MODE` carrying the supported modes. A token outside the canonical vocabulary altogether is answered the same way, as long as the rest of the body is well-formed; `400` is for a body that is malformed for some other reason. parameters: $ref: '#/components/schemas/EvChargerCommandParameters' start: description: >- Start time. Plant-local wall-clock ISO 8601 without timezone offset (e.g. `2026-06-01T22:00:00`), or a relative duration (e.g. `30m`, `1.5h`). The platform interprets the wall-clock in the device's plant timezone. Omit for immediate execution. type: string end: description: >- End time for windowed execution. Plant-local wall-clock ISO 8601 without timezone offset (e.g. `2026-06-01T06:00:00`). Supplied without `start`, the window opens now: the command is sent on this request and confirmed in the response, which reports `state: acknowledged`, no `start`, and this `end`. The platform takes the command back when `end` arrives. type: string required: - command additionalProperties: false title: EV Charger Action description: >- A canonical EV-charger command. `charge` begins charging (rate-capped by `power`/`current`, stopped by `energy`); `idle` pauses, holding the session; the `auto.*` modes hand control to the charger own optimisation and run until replaced. `auto.charge_surplus_only` charges from on-site surplus alone and stops when it runs out; `auto.charge_surplus_first` tops up from the grid so charging never stops. examples: - command: charge - command: charge parameters: power: value: 4.2 unit: kw start: '2026-07-30T17:00:00' end: '2026-07-30T19:00:00' - command: auto.charge_tariff - command: auto.charge_surplus_only start: '2026-07-31T09:00:00' EvChargerOnConflict: type: string enum: - cancel_and_replace - queue_after description: >- `cancel_and_replace` cancels the active action before running this one; `queue_after` defers this one until the active action completes. Omit to receive 409 on conflict. title: Ev Charger On Conflict EvChargerSandboxConfig: type: object properties: result: description: Outcome to simulate. Defaults to `success`. type: string enum: - success - failed errorCode: description: >- Error code to emit when `result` is `failed`. Defaults to `SIMULATED_FAILURE`. Constrained to the EV-charger canonical error codes. type: string enum: - INVALID_CREDENTIALS - INVALID_API_KEY - INVALID_MFA_CODE - MFA_REQUIRED - ACCOUNT_LOCKED - UNSUPPORTED_CREDENTIAL_TYPE - DEVICE_NOT_FOUND - DEVICE_OFFLINE - DEVICE_UNAUTHORIZED - NO_DEVICES_FOUND - VEHICLE_NOT_CONNECTED - COMMAND_FAILED - COMMAND_NOT_SUPPORTED - INVALID_PARAMETERS - SETTING_OUT_OF_RANGE - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SESSIONS_NOT_SUPPORTED - SIMULATED_FAILURE - UNKNOWN_ERROR oemError: description: >- Inject a raw device-manufacturer error (message, optional code and HTTP status) and receive back the canonical error code the platform classifies it to, exactly as a live failure would surface. Takes precedence over `errorCode` when `result` is `failed`. type: object properties: message: type: string minLength: 1 maxLength: 4096 oemCode: anyOf: - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 httpStatus: type: integer minimum: 100 maximum: 599 required: - message additionalProperties: false description: Sandbox controls for testing error paths. Ignored in live environments. title: Ev Charger Sandbox Config Quantity: type: object properties: value: type: number description: Numeric magnitude. unit: type: string enum: - percent - kw - watts - kwh - amps - volts - hours - minutes - celsius - fahrenheit description: >- Unit of measure. Closed set so consumers can switch exhaustively at the type layer. required: - value - unit title: Quantity description: >- Self-describing numeric value with its unit. `value` is the magnitude, `unit` names one of the canonical units. PushWarning: type: object properties: code: type: string enum: - vehicle_not_connected - awaiting_authorization description: >- Stable identifier for the observed condition. `vehicle_not_connected`: no vehicle is plugged in. `awaiting_authorization`: the charge waits for approval in the manufacturer app. message: type: string description: Human-readable description of the condition. observedAt: type: string format: date-time description: >- When the reading behind this warning was taken, as an ISO 8601 timestamp. A stale reading may no longer describe the device. required: - code - message - observedAt description: >- A condition observed at submission that delays the command taking effect. The command is accepted and armed; the warning names what must clear first. Never a refusal. title: Push Warning EvChargerCommandParameters: type: object properties: power: $ref: '#/components/schemas/Quantity' description: >- Rate cap in kilowatts. The charger will not draw faster than this. (unit: `kw`) current: $ref: '#/components/schemas/Quantity' description: >- Rate cap in amperes — the native lever on most chargers. (unit: `amps`) target: $ref: '#/components/schemas/Quantity' description: >- Stop when the vehicle reaches this state of charge. Only chargers that can read the car's level accept it; the rest declare `energy` instead and count on their own meter. (unit: `percent`) energy: $ref: '#/components/schemas/Quantity' description: >- Stop after this much energy has been delivered in the session. (unit: `kwh`) additionalProperties: {} description: >- Command parameters. Which parameters a given command accepts on a given device is declared in that device's `commands` capability response; a parameter it does not declare is rejected at runtime with `422 UNSUPPORTED_PARAMETER`. The `auto.*` modes declare none: a goal such as "80% by 07:00" needs a planner the platform does not have, so it is refused rather than answered with a mode change. title: Ev Charger Command Parameters securitySchemes: api-key: type: apiKey in: header name: x-api-key ````