> ## 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. # Post Battery Control Schedule > **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. Submit battery schedules: per battery, a list of time windows with the battery mode to apply. Schedules are only accepted for batteries with `flex_trading` enabled in their settings (see `PATCH /v1/devices/battery/settings`). `mode` can be set to: * `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. Only the modes in the battery's `allowed_modes` are accepted. Outside your time windows the battery falls back to `auto`. A `force_discharge` entry that starts while the state of charge is already at or below `min_soc_pct` is accepted, but the battery stays in `auto` until the entry ends. When you send a new schedule for a battery, it replaces every schedule previously sent for that battery. You can send schedules for many batteries in one request. Timestamp fields in UTC. Time format examples: * 2023-10-01T00:00:00Z * 2023-10-01T00:00:00 **NOTE**: * The battery might need some time to react. `start_time` must be at least 1 minute in the future. ## OpenAPI ````yaml /api-docs/battery/openapi-battery.json post /v1/devices/battery/schedules 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/schedules: post: tags: - Battery Control summary: Post Battery Control Schedule 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. Submit battery schedules: per battery, a list of time windows with the battery mode to apply. Schedules are only accepted for batteries with `flex_trading` enabled in their settings (see `PATCH /v1/devices/battery/settings`). `mode` can be set to: * `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. Only the modes in the battery's `allowed_modes` are accepted. Outside your time windows the battery falls back to `auto`. A `force_discharge` entry that starts while the state of charge is already at or below `min_soc_pct` is accepted, but the battery stays in `auto` until the entry ends. When you send a new schedule for a battery, it replaces every schedule previously sent for that battery. You can send schedules for many batteries in one request. Timestamp fields in UTC. Time format examples: * 2023-10-01T00:00:00Z * 2023-10-01T00:00:00 **NOTE**: * The battery might need some time to react. `start_time` must be at least 1 minute in the future. operationId: post_battery_control_schedule_v1_devices_battery_schedules_post parameters: [] requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/DevicesBatteryScheduleRequest' title: Request Body examples: schedule_example: summary: Sample battery control schedule value: - device_id: e4da3b7f-bbce-4a45-9d2b-1c0e8f7a6b5c schedules: - start_time: '2026-10-17T11:00:00Z' end_time: '2026-10-17T14:00:00Z' mode: pause_charge - start_time: '2026-10-17T18:00:00Z' end_time: '2026-10-17T19:30:00Z' mode: force_discharge - device_id: 1679091c-5a88-4c2f-8e1d-3b2a0f9e8d7c schedules: - start_time: '2026-10-17T02:00:00Z' end_time: '2026-10-17T04:00:00Z' mode: force_charge responses: '200': description: All schedules accepted successfully content: application/json: schema: $ref: '#/components/schemas/DevicesBatteryScheduleResponse' example: rejected: [] meta: energy_supplier: Energy Supplier A accepted_count: 2 rejected_count: 0 '207': description: 'Partial success: some device_ids were rejected' content: application/json: example: rejected: - device_id: 1679091c-5a88-4c2f-8e1d-3b2a0f9e8d7c reason: >- The requested mode is not in the allowed_modes of this battery. reason_code: 5 meta: energy_supplier: Energy Supplier A accepted_count: 1 rejected_count: 1 '400': description: Invalid request parameters content: application/json: example: detail: >- None of the provided device_ids allow steering or are compatible. '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: DevicesBatteryScheduleRequest: properties: device_id: type: string title: Device Id description: Battery device ID the schedule applies to. schedules: items: $ref: '#/components/schemas/BatteryScheduleEntry' type: array title: Schedules description: >- Schedule entries for the battery. Replaces any schedule previously sent for it. type: object required: - device_id - schedules title: DevicesBatteryScheduleRequest DevicesBatteryScheduleResponse: properties: rejected: items: $ref: '#/components/schemas/DevicesBatteryScheduleRejected' type: array title: Rejected description: Devices for which the schedule could not be applied. meta: $ref: '#/components/schemas/DevicesBatteryScheduleMeta' type: object required: - meta title: DevicesBatteryScheduleResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError BatteryScheduleEntry: properties: start_time: type: string title: Start Time description: >- Start of the entry in ISO 8601 UTC format. At least 1 minute in the future. end_time: type: string title: End Time description: >- End of the entry in ISO 8601 UTC format. After the end, the battery falls back to `auto` unless another entry starts. mode: $ref: '#/components/schemas/BatteryMode' description: >- Battery mode to apply during the entry. Must be one of the battery's `allowed_modes`. type: object required: - start_time - end_time - mode title: BatteryScheduleEntry DevicesBatteryScheduleRejected: properties: device_id: type: string title: Device Id description: Device ID for which the schedule could not be applied. reason: $ref: '#/components/schemas/BatteryScheduleRejectedReasons' description: Reason why the schedule for the device was rejected. reason_code: anyOf: - type: integer - type: 'null' title: Reason Code description: >- Reason code mapping to the reason. {'No battery found for this device_id.': 1, 'flex_trading is not enabled in the optimization settings of this battery.': 2, 'The device is currently not steerable, please check its steerable status.': 3, 'The requested mode is not in the allowed_modes of this battery.': 4, 'start_time must be at least 1 minute in the future.': 5, 'start_time and end_time must be ISO 8601 UTC timestamps with start_time before end_time.': 6, 'Schedule entries for the same device overlap.': 7}. type: object required: - device_id - reason title: DevicesBatteryScheduleRejected DevicesBatteryScheduleMeta: properties: energy_supplier: type: string title: Energy Supplier accepted_count: type: integer title: Accepted Count description: Number of devices that had schedules successfully applied. rejected_count: type: integer title: Rejected Count description: Number of device schedules that were rejected. type: object required: - energy_supplier - accepted_count - rejected_count title: DevicesBatteryScheduleMeta 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 BatteryMode: type: string enum: - auto - pause_charge - pause_discharge - force_charge - force_discharge title: BatteryMode BatteryScheduleRejectedReasons: type: string enum: - No battery found for this device_id. - >- flex_trading is not enabled in the optimization settings of this battery. - >- The device is currently not steerable, please check its steerable status. - The requested mode is not in the allowed_modes of this battery. - start_time must be at least 1 minute in the future. - >- start_time and end_time must be ISO 8601 UTC timestamps with start_time before end_time. - Schedule entries for the same device overlap. title: BatteryScheduleRejectedReasons 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.