> ## Documentation Index > Fetch the complete documentation index at: https://docs.flatpeak.com/llms.txt > Use this file to discover all available pages before exploring further. # Schedule by State of Charge > Generates a schedule to reach the target state of charge submitted via [Submit a device state](/api-reference/busbar/devices/submit-a-device-state) endpoint. This endpoint performs a calculation and has no side effects; it is safe to retry. ## OpenAPI ````yaml api-reference/busbar/flatpeak-api-spec-busbar.json POST /schedules/soc openapi: 3.0.3 info: description: >- The Flatpeak API connects energy hardware (batteries, EV chargers, solar) to electricity prices, grid fees, and VPP programmes. ## 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://api.flatpeak.com` ## Pagination List endpoints return a `list` envelope with `data`, `has_more`, and `url`. Page forward with `starting_after` (the last item id) or backward with `ending_before` (the first item id). ## 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 Objects carry a `live_mode` flag indicating whether they belong to live or test data. version: 2026-08-01.busbar title: Flatpeak 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://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 customer authorisation flows. - name: Customers description: Create, retrieve, update, delete, and list customers. - name: Locations description: Create, retrieve, update, delete, and list locations. - name: Devices description: Create, retrieve, update, delete, and list device identifiers. - name: Meters description: Submit meter readings and retrieve records or batch status. - name: Tariffs description: Create, retrieve, update, 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: Schedules description: Find optimal times to consume or export energy by price. - name: Events description: Retrieve and list account events. - name: VPP Participations description: Retrieve and list VPP Participations. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /schedules/soc: parameters: [] post: tags: - Schedules summary: Schedule by State of Charge description: >- Generates a schedule to reach the target state of charge submitted via [Submit a device state](/api-reference/busbar/devices/submit-a-device-state) endpoint. This endpoint performs a calculation and has no side effects; it is safe to retry. operationId: schedule-by-soc parameters: [] requestBody: $ref: '#/components/requestBodies/ScheduleBySocCreate' responses: '200': $ref: '#/components/responses/ScheduleBySoc' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '422': $ref: '#/components/responses/422' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: requestBodies: ScheduleBySocCreate: content: application/json: schema: type: object properties: device_id: type: string example: dev_63a6087272941ef077a8fd3e description: Flatpeak Device ID. schedule_horizon: type: number description: >- Number of hours into the future for which the schedule should be generated. Flatpeak may return a shorter schedule if sufficient data is unavailable. When omitted, the maximum available horizon is used. example: 24 device_state: $ref: '#/components/schemas/DeviceStateSubmit' required: - device_id - schedule_horizon additionalProperties: false required: true 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' '422': description: >- 422 Unprocessable Entity: the request is well-formed but cannot be processed, e.g. 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' ScheduleBySoc: description: Example response content: application/json: schema: $ref: '#/components/schemas/ScheduleBySoc' schemas: DeviceStateSubmit: type: object title: Submit a device state description: >- Submit the current operational state of a device, such as BESS state of charge and power. properties: record_reference_id: type: string example: MET1234567890 description: >- Optional unique identifier for the telemetry record, used for idempotency and reconciliation. time: type: string example: '2022-02-01T10:30:00Z' description: Time the measurement was recorded, in RFC3339 format. format: date-time state_of_charge_percent: type: number example: 34.2 description: Current battery state of charge as a percentage from 0 to 100. target_state_of_charge_percent: type: number example: 80 description: Target battery state of charge as a percentage from 0 to 100. energy_flow_direction: type: string example: EXPORT description: >- Direction of energy flow this applies to. IMPORT (from grid) or EXPORT (to grid). enum: - IMPORT - EXPORT battery_power_kw: type: number description: Current battery power in kilowatts. example: 3.4 energy_remaining_kwh: type: number description: >- Estimated usable energy currently available in the battery, in kilowatt-hours. example: 8.3 backup_reserve_percent: type: number description: >- Percentage of battery capacity reserved for backup and unavailable for optimisation or dispatch. example: 20 required: - time - state_of_charge_percent - target_state_of_charge_percent additionalProperties: false ScheduleBySoc: title: ScheduleBySoC type: object properties: device_id: type: string example: dev_6563a6757360a6d6a628e839 description: Flatpeak device ID. pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ location_id: type: string example: loc_641b90b758fb8e6293716e40 description: Flatpeak location ID. pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ id: type: string example: ssc_65ea3fb185c1541f247c251e description: Flatpeak schedule id. pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ object: type: string example: schedule_soc description: Object type. enum: - schedule_soc default: schedule_soc account_id: type: string example: acc_661677911f2197045e6cf1b1 description: Flatpeak Account ID. pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ live_mode: type: boolean description: Set to `true` if the object exists in live mode, otherwise `false`. example: true location_timezone: type: string description: >- The timezone at the location, in 'tz database format'. I.e. 'Europe/Berlin'. example: Europe/London currency_code: type: string example: GBP description: >- Currency code for cost of energy measure. Always returned in large currency units. pattern: ^[A-Z]{3}$ data: type: array description: This object that contains device schedules. items: type: object properties: start_time: type: string format: date-time example: '2022-02-01T20:14:00Z' description: Time when schedule starts. end_time: type: string format: date-time example: '2022-02-02T06:00:00Z' description: Time when schedule ends. cost: type: object description: Expected monetary value of energy. required: - value - confidence properties: value: type: number example: 928.372 description: >- Monetary energy cost in major currency units. Negative values represent earnings confidence: type: number description: >- Estimated confidence of data where '1' is 100% accurate and 0.1 is 10% accurate. example: 1 schedule: type: array description: Core schedule object. items: type: object properties: start_time: type: string format: date-time example: '2022-02-02T02:00:00Z' description: >- Time when energy transfer must start, in timezone of the original request. end_time: type: string example: '2022-02-02T04:30:00Z' format: date-time description: >- Time when energy transfer must end, in timezone of the original request. energy_flow_direction: type: string example: IMPORT description: >- Direction of energy flow this applies to. IMPORT (from grid) or EXPORT (to grid). enum: - IMPORT - EXPORT power_kw: type: number description: Speed of power transfer in kilowatts. example: 4.3 vpp_event: type: boolean default: false description: >- Indicates that the scheduled period is influenced by a VPP or other flexibility event. required: - start_time - end_time - energy_flow_direction - power_kw required: - start_time - end_time - cost - schedule time_created: type: string format: date-time example: '2022-01-24T14:15:22Z' description: Time when this object was created, in UTC. required: - device_id - location_id - id - object - account_id - live_mode - location_timezone - currency_code - time_created 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, e.g. `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: '2025-01-01T00:00:00Z' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authenticate with `bearer` you obtained from [authentication](/api-reference/busbar/authentication) endpoint. ````