> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve device settings > Retrieves the device's desired operating settings, including `supported`, the field paths that can be written for this device, and `sync_status`, whether the device has applied them. ## OpenAPI ````yaml energy-api/reference/flatpeak-api-spec-energy.json GET /devices/{device_id}/settings openapi: 3.0.3 info: description: >- The Flatpeak Energy API connects energy hardware (batteries, EV chargers, vehicles, heat pumps, water heaters, solar and generators) to electricity prices, grid fees, and VPP programs. ## Create bearer token Obtain a bearer token from `POST /auth/tokens` using your `account_id` and `secret_key` via basic auth, then send it as `Authorization: Bearer ` on every request. ## Base URL `https://energy-api.flatpeak.com` ## Pagination List endpoints return a `list` envelope with `data`, `next_cursor`, and `url`. Page forward by passing `next_cursor` as `cursor` on the next request, until it is `null`. Cursors are opaque and bound to the endpoint and query parameters that issued them. ## Errors Every non-2xx response uses a standard error envelope with `object`, `type`, `code`, and `message`. Codes are machine-readable and safe to branch on. ## Money Monetary values are decimal numbers and are always paired with a `currency_code` (ISO 4217). Energy is expressed in kilowatt hours (kWh). ## Live vs test `live_mode` marks live or test data. version: 2027-01-01.busbar title: Flatpeak Energy 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://energy-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. Connect drives the user journeys for tariff connection, VPP enrollment, and [tariff error reporting](/energy-api/reference/connect/tariff/error-report). What happens in those journeys reaches your backend as [Connect webhooks](/energy-api/guides/platform/events). x-tariff-description: >- Create and retrieve Connect sessions. Connect drives the user journeys for tariff connection and [tariff error reporting](/energy-api/reference/connect/tariff/error-report). What happens in those journeys reaches your backend as [Connect webhooks](/energy-api/guides/platform/events). - name: Users description: Create, retrieve, update, delete, and list users. - name: Locations description: Create, retrieve, update, delete, and list locations. - name: Devices description: >- Create, retrieve, update, delete and list devices; submit and retrieve their state; read and write their shared settings. - name: Meters description: Submit meter records and check batch status. - name: Tariffs description: Create, retrieve, delete, and list tariffs. - name: Prices description: Retrieve and audit calculated energy prices. - name: Costs description: Calculate the monetary cost of imported or exported energy. - name: Optimizations description: >- Rank the connected tariff to find the best times to consume or export energy, as inputs to your own scheduling. - name: Dispatch description: >- Fetch the VPP operator's instructions for a device, and confirm what the device will deliver. - name: Events description: Retrieve and list account events. - name: VPP Enrollments description: Create, retrieve and list VPP enrollments, and unenroll a device. - name: VPP Programs description: List VPP programs available to devices. - name: VPP Events description: >- VPP events committed by VPP operators, with your fleet's share and its per-device allocation. You can take over the allocation while it is open. - name: Operator groups description: >- Read-only views of the device groups VPP operators define. You see the groups that touch your fleet, and only your own devices in them. - name: Zones description: >- Network areas VPP operators define that touch your fleet. Read-only. You see only your own devices in them. 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. get: tags: - Devices summary: Retrieve device settings description: >- Retrieves the device's desired operating settings, including `supported`, the field paths that can be written for this device, and `sync_status`, whether the device has applied them. operationId: retrieve-device-settings parameters: [] 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' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: 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' '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 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' account_id: acc_661677911f2197045e6cf1b1 schemas: DeviceSettings: title: DeviceSettings type: object description: >- The device's desired settings, one record shared between you and its VPP operator. Device-local changes are reconciled in from your 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. 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, derived from its type and capabilities. Recomputed on a capabilities update. 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` | VPP operator | | `OEM` | You, 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. account_id: type: string description: Flatpeak Account ID. example: acc_661677911f2197045e6cf1b1 pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ readOnly: true required: - object - device_id - supported - sync_status - updated_by - time_updated - account_id 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: not_found 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' 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 dispatch. The device owner sets it freely; no VPP program 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; your 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 VPP operator can set it. Write `false` when the charge ends; Flatpeak does not clear it. 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 VPP operator can set it. Write `false` when the charge ends; Flatpeak does not clear it. 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 VPP operator can set it. Write `false` when the charge ends; Flatpeak does not clear it. Not persistent, and not compared in `sync_status`. An instruction it overrides is recorded as a deviation. `true` for an unplugged vehicle returns `422`. securitySchemes: bearerAuth: type: http scheme: bearer description: Bearer token obtained from POST /auth/tokens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.