> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Update device settings > Updates the device's desired settings. Send only the fields that change; when two writes change the same field, the last one wins. Unsupported field paths return `422` `setting_not_supported`. Requires an `ACTIVE` enrollment with the `SETTINGS` scope. ## OpenAPI ````yaml fleet-api/reference/flatpeak-api-spec-fleet.json PATCH /devices/{device_id}/settings openapi: 3.0.3 info: description: >- The Flatpeak Fleet API. VPP operators use it to enroll, dispatch and settle OEM device fleets. ## Authentication Exchange your `account_id` and `secret_key` for a bearer token at `POST /auth/tokens` with basic auth. Send it as `Authorization: Bearer ` on every request. ## Base URL `https://fleet-api.flatpeak.com` ## Pagination Lists return `data`, `next_cursor` and `url`. Pass `next_cursor` as `cursor` until it is `null`. A cursor is opaque and bound to the endpoint and query parameters that issued it. ## Errors Every non-2xx response carries `object`, `type`, `code` and `message`. Branch on `code`. ## Money and energy Money is a decimal number paired with a `currency_code` (ISO 4217). Power is in kW and energy in kWh. Positive is import, negative is export. ## Live and test `live_mode` marks live or test data. version: 2027-01-01.busbar title: Flatpeak Fleet API termsOfService: https://flatpeak.com/legal contact: name: Technical Support email: support@flatpeak.com url: https://flatpeak.com/contact license: name: Apache 2.0 url: https://flatpeak.com/legal servers: - url: https://fleet-api.flatpeak.com security: - bearerAuth: [] tags: - name: Authentication description: >- Exchange your account credentials for a bearer token to authenticate API requests. - name: Connect description: >- Create and retrieve Connect sessions for onboarding customers through your own app. - name: OEMs description: List and retrieve the OEMs whose devices your fleet can reach. - name: Devices description: >- Retrieve, list and update the devices connected to your account, and read their consent history and shared settings. - name: Locations description: >- Read the location a device sits behind: its timezone, currency, metering and your devices there. - name: Dispatch description: Submit plans to devices on managed tariffs and read the dispatch timeline. - name: Telemetry description: Read device state, device meter records and location meter records. - name: Tariffs description: Create, retrieve, delete, and list tariffs. - name: Events description: Retrieve and list account events. - name: VPP Programs description: >- Define and manage VPP programs: the commercial terms devices enroll under, and their live state. - name: Groups description: >- Named collections of devices for bulk dispatch and aggregated reads. OEMs see them read-only as [groups](/energy-api/reference/groups/list) on the Energy API. - name: Zones description: >- Network areas resolved to devices by Flatpeak, for locational eligibility and grouping without handling addresses. - name: Exports description: >- Package settlement evidence, consent records and enrollment registers as downloadable files. - name: Rewards description: >- The reward ledger: entries accrue from delivery, you approve them, pay the customers and mark them paid. - name: VPP Enrollments description: Track and act on device enrollments across your programs. - name: VPP Events description: >- Commit market activations: create an event for a group, then read its state and its devices' results. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /devices/{device_id}/settings: parameters: - schema: type: string name: device_id in: path required: true description: Flatpeak Device ID. patch: tags: - Devices summary: Update device settings description: >- Updates the device's desired settings. Send only the fields that change; when two writes change the same field, the last one wins. Unsupported field paths return `422` `setting_not_supported`. Requires an `ACTIVE` enrollment with the `SETTINGS` scope. operationId: update-device-settings parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeviceSettingsUpdate' examples: Change the backup reserve: value: battery: backup_reserve_percent: 30 Set a departure time: value: vehicle: charge_limit_percent: 80 time_departure: '2026-09-02T07:30:00Z' Start a one-off charge: value: evse: one_off_charge: true responses: '200': $ref: '#/components/responses/DeviceSettings' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '422': $ref: '#/components/responses/422' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: schemas: DeviceSettingsUpdate: title: DeviceSettingsUpdate type: object additionalProperties: false description: >- Partial update of the device's desired operating settings. Send only the fields that change, nested under their namespace. When two writes change the same field, the last one wins. properties: battery: $ref: '#/components/schemas/DeviceSettingsBattery' evse: $ref: '#/components/schemas/DeviceSettingsEvse' vehicle: $ref: '#/components/schemas/DeviceSettingsVehicle' minProperties: 1 DeviceSettingsBattery: title: DeviceSettingsBattery type: object additionalProperties: false description: >- Desired operating settings for a battery. All fields are persistent except `one_off_charge`. properties: backup_reserve_percent: type: number minimum: 0 maximum: 100 example: 20 description: >- Percentage of capacity reserved for backup and unavailable for optimization or dispatch. The device owner sets it freely; none of your programs constrains it. strategy: type: string enum: - SELF_POWER - SAVINGS example: SELF_POWER description: >- Strategy the device should operate under: `SELF_POWER` maximizes use of self-generated energy, `SAVINGS` charges when prices are low and discharges when high. Stored and shared; the OEM's planning decides what it means for the device. storm_mode_enabled: type: boolean example: true description: >- When `true`, the battery holds or increases charge ahead of storms and other severe weather events. export_rule: type: string enum: - BATTERY_OK - PV_ONLY - NEVER example: BATTERY_OK description: >- Which energy may be exported. A battery that may not export is never asked to; the interval is recorded as declined. | Value | May export | | :--- | :--- | | `BATTERY_OK` | Battery and PV | | `PV_ONLY` | PV surplus only | | `NEVER` | No export | charge_from_grid_enabled: type: boolean example: true description: >- Whether the battery may charge from the grid. When `false`, the battery charges from solar only: plans and events cannot schedule grid charging, including pre-charging ahead of a VPP event. one_off_charge: type: boolean example: false description: >- One-off charge. `true` charges the battery to full, starting now and once, regardless of plans, VPP events and the other settings. You or the OEM can set it. The OEM writes `false` when the charge ends. Not persistent, and not compared in `sync_status`. An instruction it overrides is recorded as a deviation. DeviceSettingsEvse: title: DeviceSettingsEvse type: object additionalProperties: false description: Desired operating settings for an EV charger. properties: max_charging_power_kw: type: number minimum: 0 nullable: true example: 7.4 description: >- Ceiling on charging power the user allows, in kW, at or below the device's `capabilities` maximum. Plans and dispatch never exceed it. `null` removes the ceiling. one_off_charge: type: boolean example: false description: >- One-off charge. `true` charges the connected vehicle, starting now and once, regardless of plans, VPP events and the other settings. You or the OEM can set it. The OEM writes `false` when the charge ends. Not persistent, and not compared in `sync_status`. An instruction it overrides is recorded as a deviation. `true` with no vehicle plugged in returns `422`. DeviceSettingsVehicle: title: DeviceSettingsVehicle type: object additionalProperties: false description: Desired operating settings for an electric vehicle. properties: charge_limit_percent: type: number minimum: 0 maximum: 100 example: 80 description: >- Charge limit, as a percentage from 0 to 100. Charging stops at this level. Persistent. time_departure: type: string format: date-time nullable: true example: '2026-09-02T07:30:00Z' description: >- Next planned departure, RFC 3339 in UTC. Plans aim to reach `charge_limit_percent` by this time. Persistent until changed; `null` when no departure is scheduled. max_charging_power_kw: type: number minimum: 0 nullable: true example: 7.4 description: >- Ceiling on charging power the user allows, in kW, at or below the device's `capabilities` maximum. Plans and dispatch never exceed it. `null` removes the ceiling. one_off_charge: type: boolean example: false description: >- One-off charge. `true` charges the vehicle, starting now and once, regardless of plans, VPP events and the other settings. You or the OEM can set it. The OEM writes `false` when the charge ends. Not persistent, and not compared in `sync_status`. An instruction it overrides is recorded as a deviation. `true` for an unplugged vehicle returns `422`. DeviceSettings: title: DeviceSettings type: object description: >- The device's desired settings, one record shared with its OEM. Device-local changes are reconciled in from the OEM's state submissions. `supported` lists the writable field paths; writes outside it return `422`. Only the blocks for subsystems the device has are returned. properties: object: type: string enum: - device_settings example: device_settings readOnly: true description: Object type, `device_settings`. device_id: type: string readOnly: true example: dev_63a6087272941ef077a8fd3e description: Flatpeak Device ID of the device these settings belong to. oem_id: type: string readOnly: true pattern: ^oem_[A-Za-z0-9]+$ example: oem_6a3a8dada72cd0a249ff9528 description: >- Flatpeak OEM ID: the OEM that connects the device. See [list all OEMs](/fleet-api/reference/oems/list). supported: type: array readOnly: true items: type: string example: - battery.backup_reserve_percent - battery.strategy - battery.storm_mode_enabled - battery.export_rule - battery.charge_from_grid_enabled - battery.one_off_charge description: >- The field paths that can be written for this device, from its type and declared hardware support. Read only. Empty for device types without settings. battery: $ref: '#/components/schemas/DeviceSettingsBattery' evse: $ref: '#/components/schemas/DeviceSettingsEvse' vehicle: $ref: '#/components/schemas/DeviceSettingsVehicle' sync_status: type: string enum: - IN_SYNC - PENDING - FAILED readOnly: true example: IN_SYNC description: >- Whether the device has applied the desired settings, from comparing this record with reported state. Numeric fields compare within a tolerance. A `null` desired value is in sync only with a `null` reported value. `one_off_charge` is not compared, because device state does not report it. `FAILED` fires `device.settings.sync_failed`. updated_by: type: string enum: - OPERATOR - OEM readOnly: true example: OEM description: >- Who made the last change. When two writes change the same field, the last one wins. | Value | Meaning | | :--- | :--- | | `OPERATOR` | You | | `OEM` | The device's OEM, or a device-local change | time_updated: type: string format: date-time readOnly: true example: '2026-08-31T09:12:44Z' description: When the record last changed, in UTC. required: - object - device_id - oem_id - supported - sync_status - updated_by - time_updated Error: type: object description: Standard error envelope returned by every non-2xx response. required: - object - type - code - message properties: object: type: string enum: - error default: error description: Object type. type: type: string description: High-level error category. example: invalid_request code: type: string description: Machine-readable error code, safe to branch on. example: access_denied message: type: string description: Human-readable description of the error. example: The requested resource could not be found. context: type: string description: Optional originating context, for example `api.price_get`. example: api.price_get live_mode: type: boolean description: Whether the error occurred against live or test data. time_created: type: string format: date-time description: Time the error was generated (RFC 3339). example: '2026-01-01T00:00:00Z' responses: '400': description: >- 400 Bad Request: the request was malformed or a required field is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: '401 Unauthorized: authentication credentials are missing or invalid.' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: '403 Forbidden: you do not have permission to access this resource.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '404 Not Found: the requested resource does not exist.' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- 422 Unprocessable Entity: the request is well-formed but cannot be processed, for example missing required data. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '429 Too Many Requests: the rate limit has been exceeded.' content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: >- 500 Internal Server Error: an unexpected error occurred. Safe to retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- 503 Service Unavailable: the service is temporarily down for maintenance. Retry after the indicated delay. content: application/json: schema: $ref: '#/components/schemas/Error' DeviceSettings: description: Device settings record. content: application/json: schema: $ref: '#/components/schemas/DeviceSettings' example: object: device_settings device_id: dev_63a6087272941ef077a8fd3e oem_id: oem_6a3a8dada72cd0a249ff9528 supported: - battery.backup_reserve_percent - battery.strategy - battery.storm_mode_enabled - battery.export_rule - battery.charge_from_grid_enabled - battery.one_off_charge battery: backup_reserve_percent: 20 strategy: SELF_POWER storm_mode_enabled: true export_rule: BATTERY_OK charge_from_grid_enabled: true one_off_charge: false sync_status: IN_SYNC updated_by: OEM time_updated: '2026-08-31T09:12:44Z' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authenticate with the `bearer_token` obtained from the [authentication](/fleet-api/reference/authentication) endpoint. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.