> ## Documentation Index > Fetch the complete documentation index at: https://docs.nox.energy/llms.txt > Use this file to discover all available pages before exploring further. # Get Devices Battery > **Preview: not available yet.** This endpoint is documented ahead of its release and currently answers `501 Not Implemented`. Its contract may still change before release. Get information about all NOX-connected batteries associated with your energy supplier account. * `allowed_modes` lists the battery modes the battery accepts in a schedule. They depend on the battery model and on the other devices in its household. * `min_soc_pct` is the lower limit for `force_discharge`: below it, NOX Energy takes control and puts the battery in the default mode `auto`. It does not limit `auto` itself, where the battery may keep covering the house load. It is fixed at 20 % for now. * The optimization settings of a battery are available with `GET /v1/devices/battery/settings`. The battery modes: * `auto` (default): the battery follows its own logic. Pv surplus charges the battery, the battery covers the house load, the grid covers the rest. The battery returns to `auto` outside your schedules and whenever NOX Energy takes over. * `pause_charge`: the battery does not charge. Pv surplus is exported, the battery can still discharge. * `pause_discharge`: the battery does not discharge. The grid covers the house load, pv surplus can still charge the battery. * `force_charge`: the battery charges at its fixed charge power, from pv first and from the grid for the rest. * `force_discharge`: the battery discharges at its fixed discharge power, to the house first and to the grid for the rest. Only while the state of charge is above `min_soc_pct`: when it reaches that limit, NOX Energy takes control and puts the battery in `auto` for the rest of the entry. If you want to know the response structure or possible enum values, like steerable reasons, you can check it in the response model `schema`. ## OpenAPI ````yaml /api-docs/battery/openapi-battery.json get /v1/devices/battery openapi: 3.1.0 info: title: NOX Energy API - Battery description: > # Battery API Documentation This documentation shows only the endpoints available to battery users. **Preview:** these endpoints are documented ahead of their release and currently answer `501 Not Implemented`. ## Authentication 1. Get your API key from [NOX Energy](mailto:support@nox.energy). 2. Include the API key in your API calls with the header: `x-api-key: YOUR_API_KEY`. ## Access Level This documentation is specifically for **battery users** who have access to these endpoints. Base URL: [https://api.nox.energy](https://api.nox.energy) version: 1.0.0 servers: - url: https://api.nox.energy description: Production Server security: - ApiKeyAuth: [] tags: - name: Asset Info description: API to get basic information about your assets. - name: Battery Control description: API for battery control specific endpoints. - name: User Management description: API endpoints to manage users and their data. paths: /v1/devices/battery: get: tags: - Asset Info summary: Get Devices Battery description: >- **Preview: not available yet.** This endpoint is documented ahead of its release and currently answers `501 Not Implemented`. Its contract may still change before release. Get information about all NOX-connected batteries associated with your energy supplier account. * `allowed_modes` lists the battery modes the battery accepts in a schedule. They depend on the battery model and on the other devices in its household. * `min_soc_pct` is the lower limit for `force_discharge`: below it, NOX Energy takes control and puts the battery in the default mode `auto`. It does not limit `auto` itself, where the battery may keep covering the house load. It is fixed at 20 % for now. * The optimization settings of a battery are available with `GET /v1/devices/battery/settings`. The battery modes: * `auto` (default): the battery follows its own logic. Pv surplus charges the battery, the battery covers the house load, the grid covers the rest. The battery returns to `auto` outside your schedules and whenever NOX Energy takes over. * `pause_charge`: the battery does not charge. Pv surplus is exported, the battery can still discharge. * `pause_discharge`: the battery does not discharge. The grid covers the house load, pv surplus can still charge the battery. * `force_charge`: the battery charges at its fixed charge power, from pv first and from the grid for the rest. * `force_discharge`: the battery discharges at its fixed discharge power, to the house first and to the grid for the rest. Only while the state of charge is above `min_soc_pct`: when it reaches that limit, NOX Energy takes control and puts the battery in `auto` for the rest of the entry. If you want to know the response structure or possible enum values, like steerable reasons, you can check it in the response model `schema`. operationId: get_devices_battery_v1_devices_battery_get parameters: - name: limit in: query required: false schema: type: integer maximum: 1000 minimum: 1 description: > The maximum number of items to return per page of results. This should be used together with the `next_token` parameter to paginate through results. Read the pagination parameter documentation for more details. default: 1000 title: Limit description: > The maximum number of items to return per page of results. This should be used together with the `next_token` parameter to paginate through results. Read the pagination parameter documentation for more details. - name: next_token in: query required: false schema: anyOf: - type: string - type: 'null' description: > The `next_token` is a token used to retrieve the next page of results when there are more results than can fit in a single page(=API response). By default, the API will return a `next_token` of the first page if no token was given as a parameter. If the token is `null` you have reached the end of the results. This should be used together with the `limit` parameter to paginate through results. To get all results of your call, you can keep calling the same API call with the previously returned `next_token` until it returns `null`. title: Next Token description: > The `next_token` is a token used to retrieve the next page of results when there are more results than can fit in a single page(=API response). By default, the API will return a `next_token` of the first page if no token was given as a parameter. If the token is `null` you have reached the end of the results. This should be used together with the `limit` parameter to paginate through results. To get all results of your call, you can keep calling the same API call with the previously returned `next_token` until it returns `null`. - name: device_id in: query required: false schema: anyOf: - type: string - type: 'null' description: > The ID of the device to filter on. If not provided, all devices are returned. title: Device Id description: > The ID of the device to filter on. If not provided, all devices are returned. - name: user_id in: query required: false schema: anyOf: - type: string - type: 'null' description: > Your own ID of the user to filter on: the ID you use internally for this user, whether you are an energy supplier, an OEM or another partner. If not provided, all users are returned. title: User Id description: > Your own ID of the user to filter on: the ID you use internally for this user, whether you are an energy supplier, an OEM or another partner. If not provided, all users are returned. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/DevicesBatteryResponse' example: data: - device_id: e4da3b7f-bbce-4a45-9d2b-1c0e8f7a6b5c user_id: '1234' brand: Huawei model: LUNA2000-10-S0 country: BE capacity_kwh: 10 max_charge_power_kw: 5 max_discharge_power_kw: 5 min_soc_pct: 20 steerable_status: steering_enabled: true steerable: true learning_period_ended: true allowed_modes: - auto - pause_charge - pause_discharge - force_charge - force_discharge needs_reauthentication: false first_connection_at: '2026-09-01T08:12:00Z' meta: energy_supplier: Energy Supplier A '403': description: Your API key has no access to the battery features content: application/json: example: detail: Energy Supplier A is not authorized to access this feature. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '501': description: Not implemented yet content: application/json: example: detail: This endpoint is not available yet. components: schemas: DevicesBatteryResponse: properties: data: anyOf: - items: $ref: '#/components/schemas/DeviceBattery' type: array - type: 'null' title: Data description: List of batteries meta: anyOf: - $ref: '#/components/schemas/DevicesBatteryMeta' - type: 'null' description: Response metadata type: object title: DevicesBatteryResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError DeviceBattery: properties: device_id: anyOf: - type: string - type: 'null' title: Device Id description: Unique device identifier user_id: anyOf: - type: string - type: 'null' title: User Id description: >- Your own identifier of the user, as used internally by you (supplier, OEM or other partner) brand: anyOf: - type: string - type: 'null' title: Brand description: Device brand model: anyOf: - type: string - type: 'null' title: Model description: Device model country: anyOf: - type: string - type: 'null' title: Country description: Country code capacity_kwh: anyOf: - type: number - type: 'null' title: Capacity Kwh description: Usable battery capacity in kWh max_charge_power_kw: anyOf: - type: number - type: 'null' title: Max Charge Power Kw description: Maximum charge power in kW max_discharge_power_kw: anyOf: - type: number - type: 'null' title: Max Discharge Power Kw description: Maximum discharge power in kW steerable_status: anyOf: - $ref: '#/components/schemas/BatterySteerableStatus' - type: 'null' description: Device steering status min_soc_pct: anyOf: - type: number - type: 'null' title: Min Soc Pct description: >- Lower limit for `force_discharge`, as a state of charge in %. Below it, NOX Energy takes control and puts the battery in the default mode `auto`. Fixed at 20 % for now. allowed_modes: anyOf: - items: $ref: '#/components/schemas/BatteryMode' type: array - type: 'null' title: Allowed Modes description: >- Battery modes this battery accepts in a schedule. Depends on the battery model and on the other devices in its household. needs_reauthentication: anyOf: - type: boolean - type: 'null' title: Needs Reauthentication description: Whether the device needs reauthentication first_connection_at: anyOf: - type: string - type: 'null' title: First Connection At description: >- The date when the device was first connected to Nox, in UTC time format. type: object title: DeviceBattery DevicesBatteryMeta: properties: energy_supplier: anyOf: - type: string - type: 'null' title: Energy Supplier description: Energy supplier name next_token: anyOf: - type: string - type: 'null' title: Next Token description: Token for pagination type: object title: DevicesBatteryMeta ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError BatterySteerableStatus: properties: steering_enabled: anyOf: - type: boolean - type: 'null' title: Steering Enabled description: Whether steering is enabled steerable: anyOf: - type: boolean - type: 'null' title: Steerable description: Whether device is steerable learning_period_ended: anyOf: - type: boolean - type: 'null' title: Learning Period Ended description: Whether the learning period has ended general_reason: anyOf: - $ref: '#/components/schemas/BatteryGeneralReason' - type: 'null' description: General reason for steerable status type: object title: BatterySteerableStatus BatteryMode: type: string enum: - auto - pause_charge - pause_discharge - force_charge - force_discharge title: BatteryMode BatteryGeneralReason: type: string enum: - Battery connected recently, still collecting data to improve models. - Processing error, please contact support. - >- Device disconnected, it might reconnect later or be permanently be disconnected. - Device in error state. Might recover automatically later. - User settings prevent steering. - >- Device is unsupported brand/model, will be supported in future updates. - Device is unsupported model, will not be supported in future updates. - Important data missing, this might improve with future updates. - Unauthorized country, steering not allowed in this country. - Reauthentication required. - Unknown reason, please contact support. title: BatteryGeneralReason securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: 'API Key authentication. Enter your API key in the format: YOUR_API_KEY' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.