> ## 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. # Update EV Charger device settings > Write one or more writable settings on the device. Sparse: send only the settings you want to change. Unknown or read-only keys are rejected with 422. ## OpenAPI ````yaml /openapi.json post /ev-charger/{deviceId}/settings 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}/settings: post: tags: - EV Charger summary: Update EV Charger device settings description: >- Write one or more writable settings on the device. Sparse: send only the settings you want to change. Unknown or read-only keys are rejected with 422. operationId: updateEvChargerSettings 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 description: >- Sparse map of writable settings. At least one field is required. Each value uses the canonical `{ value, unit }` shape; unit must match the canonical setting. content: application/json: schema: $ref: '#/components/schemas/EvChargerSettingsUpdateRequest' examples: setMaxChargeRate: summary: Cap the charging power at 11 kW description: >- `max_charge_rate` is the configuration ceiling on charging power. Persistent, non-conflicting, fire-and-forget — distinct from the `charge`/`idle` push actions. value: max_charge_rate: value: 11 unit: kw throttleLow: summary: Throttle to a slow charge (1.4 kW) description: >- Use a low cap to extend session duration overnight or coordinate with on-site solar. value: max_charge_rate: value: 1.4 unit: kw setMaxChargeCurrent: summary: Cap the charging current at 16 A description: >- The current ceiling is the native lever on most chargers, and the one to reach for when the constraint is the circuit rather than the tariff. It moves in whole amps: a value between the increments is rejected. value: max_charge_current: value: 16 unit: amps lockCable: summary: Lock the cable to the charger description: >- A boolean setting carries a bare `value` and no unit. Locking keeps the cable captive between sessions. value: cable_lock: value: true multipleSettings: summary: Write more than one setting at once description: >- The body is sparse: send only what you want to change. `updated` in the response lists the keys that changed, in the order you sent them. value: max_charge_rate: value: 7.4 unit: kw cable_lock: value: false responses: '200': description: >- Settings written. Response lists the canonical setting keys that changed. 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/EvChargerSettingsUpdateResponse' meta: $ref: '#/components/schemas/ResponseMeta' examples: maxChargeRateUpdated: summary: Charging-power cap written value: success: true data: deviceId: device_ev_001 updated: - max_charge_rate meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 multipleUpdated: summary: Two settings written in one call value: success: true data: deviceId: device_ev_001 updated: - max_charge_rate - cable_lock meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 '400': description: >- Invalid request body (not a key-value map, or empty `{}` after parsing). 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`, `EMPTY_SETTINGS`, `INVALID_PARAMETERS`, `INVALID_REQUEST_BODY`, `UNSUPPORTED_CREDENTIAL_TYPE`, `VALIDATION_ERROR`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: emptyBody: summary: Request body parsed to an empty settings map value: success: false error: code: EMPTY_SETTINGS message: At least one setting must be provided. meta: requestId: req_1bA0eFgC timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001/settings latencyMs: 2 '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/settings 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/settings latencyMs: 5 '409': description: 'Error codes: `VEHICLE_NOT_CONNECTED`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '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 a setting can't be applied. Common codes: `DEVICE_NOT_CAPABLE` (the key is not declared for this device, or is read-only through the public API — `details.availableSettings` lists the keys it does declare, `details.setting` names a read-only one), `INVALID_SETTING_UNIT` (unit doesn't match the canonical), `INVALID_SETTING_VALUE` (wrong type), `SETTING_OUT_OF_RANGE` (outside the `min`/`max` this device declares, or off the `step` increment it declares with `details.step` naming the increment, or outside a narrower limit the connected unit itself reports — a model rated to 22 kW can be an 11 kW unit, and the request is refused rather than quietly clamped). Every code at this status: `DEVICE_NOT_CAPABLE`, `INVALID_SETTING_UNIT`, `INVALID_SETTING_VALUE`, `SETTING_OUT_OF_RANGE`, `UNSUPPORTED_SETTING_COMBINATION`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unsupportedSetting: summary: Setting key is not declared for this device value: success: false error: code: DEVICE_NOT_CAPABLE message: >- This device cannot do that. Read its capabilities to see what it can do. details: availableSettings: - max_charge_rate - max_charge_current - cable_lock description: >- Setting 'min_charge_rate' is not supported for this device. meta: requestId: req_4eD7iPuU timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001/settings latencyMs: 5 invalidUnit: summary: Unit does not match the canonical setting value: success: false error: code: INVALID_SETTING_UNIT message: The supplied setting unit is invalid. details: expected: kw received: amps description: >- Setting 'max_charge_rate' expects unit 'kw', got 'amps'. meta: requestId: req_5fE8jQvV timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001/settings latencyMs: 5 outOfRange: summary: '`max_charge_rate` exceeds the canonical maximum' value: success: false error: code: SETTING_OUT_OF_RANGE message: >- The supplied setting value is outside the supported range. details: min: 0 max: 50 unit: kw description: Setting 'max_charge_rate' value 75 exceeds maximum 50. meta: requestId: req_6gF9kRwW timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001/settings latencyMs: 5 exclusiveSettings: summary: >- Two rate ceilings in one request. Most chargers hold a single rate register, so the kW cap and the ampere cap are one limit expressed two ways — supplying both would leave the charger to choose. Read `details.conflictingSettings` for the keys that collided, and send one of them. Which settings collide is per-device: a charger that holds them independently accepts both. value: success: false error: code: UNSUPPORTED_SETTING_COMBINATION message: >- The requested settings cannot be written in the same request. details: conflictingSettings: - max_charge_rate - max_charge_current description: >- Settings 'max_charge_rate' and 'max_charge_current' cannot be written in the same request — they set the same thing on this device, so two values leave it ambiguous. Supply one. meta: requestId: req_8iH1mTyY timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001/settings latencyMs: 4 offStep: summary: >- A value inside the range but between the accepted increments. The current ceiling moves in whole amps, so half an amp is refused; `details.step` carries the grid so the value can be rounded without a second GET. value: success: false error: code: SETTING_OUT_OF_RANGE message: >- The supplied setting value is outside the supported range. details: min: 6 max: 32 step: 1 unit: amps description: >- Setting 'max_charge_current' value 16.5 is not an accepted increment: values step by 1 from 6. meta: requestId: req_7hG0lSxX timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_ev_001/settings latencyMs: 5 '429': description: 'Error codes: `RATE_LIMITED`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 'Error codes: `INTERNAL_ERROR`, `UNKNOWN_ERROR`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': description: 'Error codes: `NETWORK_ERROR`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Error codes: `SERVICE_UNAVAILABLE`, `SIMULATED_FAILURE`, `CAPABILITY_PAUSED`, `SETTINGS_STORE_UNAVAILABLE`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '504': description: 'Error codes: `TIMEOUT`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - api-key: [] x-codeSamples: - lang: curl label: curl source: |- curl --request POST \ --url 'https://api.amps.ai/ev-charger/device_abc123/settings' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' \ --header 'content-type: application/json' \ --data '{ "max_charge_rate": { "value": 11, "unit": "kw" } }' - lang: javascript label: Node source: >- const response = await fetch('https://api.amps.ai/ev-charger/device_abc123/settings', { method: 'POST', headers: { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', 'content-type': 'application/json', }, body: JSON.stringify({ "max_charge_rate": { "value": 11, "unit": "kw" } }), }); const data = await response.json(); - lang: python label: Python source: |- import requests url = 'https://api.amps.ai/ev-charger/device_abc123/settings' headers = { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', 'content-type': 'application/json', } payload = { "max_charge_rate": { "value": 11, "unit": "kw", }, } response = requests.post(url, headers=headers, json=payload) data = response.json() components: schemas: EvChargerSettingsUpdateRequest: type: object properties: max_charge_rate: $ref: '#/components/schemas/Quantity' description: >- Maximum charging power the charger will draw. (unit: `kw`, min: 0, max: 50) max_charge_current: $ref: '#/components/schemas/Quantity' description: >- Maximum charging current the charger will draw. (unit: `amps`, min: 0, max: 32) cable_lock: type: object properties: value: type: boolean required: - value additionalProperties: false description: Whether the charging cable is locked to the charger. smart_charging: type: object properties: value: type: boolean required: - value additionalProperties: false description: >- Whether the charger's own smart-charging schedule is active. When off, the charger does not start charges on its own, so a stop holds until you command a charge. description: >- Sparse map of writable settings. At least one field is required. Unknown or read-only keys are rejected with `DEVICE_NOT_CAPABLE`. Some settings cannot share a request because they set the same thing on the device — `max_charge_rate` and `max_charge_current` are one rate ceiling expressed in kilowatts and in amperes, and a charger that holds a single rate register refuses the pair with `UNSUPPORTED_SETTING_COMBINATION` rather than choosing between them. Which settings collide is a property of the device, so send one of a colliding pair and read `details.conflictingSettings` if a request is refused. examples: - max_charge_rate: value: 11 unit: kw title: Ev Charger Settings Update EvChargerSettingsUpdateResponse: type: object properties: deviceId: type: string description: The EV charger the settings were written to. updated: type: array items: type: string description: >- Canonical setting keys that the request changed. Order mirrors the request body order. required: - deviceId - updated description: >- Acknowledgement of a settings write. `updated` lists the canonical setting keys that changed; OEMs that fire-and-forget will still echo the keys. A device holds only the values its own hardware steps to, so a written value can land on the nearest step it can deliver. Read the settings back to see what it holds. A value the device cannot deliver at all is refused rather than quietly adjusted. title: Ev Charger Settings Update 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 - DEVICE_NOT_CAPABLE - 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 - SIMULATED_FAILURE - UNKNOWN_ERROR - VEHICLE_NOT_CONNECTED - CONSENT_REVOKED - CREDENTIAL_NOT_FOUND - CAPABILITY_PAUSED - 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 - DEVICE_OVERAGE - SETTINGS_STORE_UNAVAILABLE - ACTION_NOT_FOUND - UNSUPPORTED_PARAMETER_COMBINATION - 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 - UNSUPPORTED_SETTING_COMBINATION - 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`, `DEVICE_NOT_CAPABLE`). 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.