> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Confirm instructions > Confirms the power the device will deliver for each instruction segment. Confirm each time you fetch instructions, up to 72 hours ahead. Confirm the instruction windows only, not the rest of the device's day. A later confirmation replaces earlier ones for the windows it covers. Power below the instruction is recorded as a deviation; delivery is still measured from meter records. Pass `record_reference_id` for idempotent retries. ## OpenAPI ````yaml energy-api/reference/flatpeak-api-spec-energy.json POST /devices/{device_id}/instructions/confirm 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}/instructions/confirm: parameters: - name: device_id in: path required: true schema: type: string example: dev_63a6087272941ef077a8fd3e description: Flatpeak Device ID. post: tags: - Dispatch summary: Confirm instructions description: >- Confirms the power the device will deliver for each instruction segment. Confirm each time you fetch instructions, up to 72 hours ahead. Confirm the instruction windows only, not the rest of the device's day. A later confirmation replaces earlier ones for the windows it covers. Power below the instruction is recorded as a deviation; delivery is still measured from meter records. Pass `record_reference_id` for idempotent retries. operationId: confirm-instructions parameters: [] requestBody: $ref: '#/components/requestBodies/InstructionConfirmationSubmit' responses: '201': $ref: '#/components/responses/InstructionConfirmation' '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: requestBodies: InstructionConfirmationSubmit: required: true content: application/json: schema: $ref: '#/components/schemas/InstructionConfirmationSubmit' 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' InstructionConfirmation: description: Instruction confirmation response. content: application/json: schema: $ref: '#/components/schemas/InstructionConfirmation' schemas: InstructionConfirmationSubmit: type: object title: InstructionConfirmationSubmit additionalProperties: false description: What the device will deliver for each instruction segment you fetched. properties: record_reference_id: type: string description: >- Optional unique identifier for the submission. Resubmitting the same value returns the stored confirmation. example: nova-7d1c-2026-08-04T16:01 data: type: array items: $ref: '#/components/schemas/InstructionConfirmationSegment' description: >- One entry per instruction segment, or per part of one, in chronological order. A segment you leave out is unconfirmed: the device is expected to follow it and is scored on delivery as usual. required: - data InstructionConfirmation: type: object title: InstructionConfirmation description: What the device will deliver for its instructions, as you confirmed it. properties: id: type: string description: Flatpeak Instruction Confirmation ID. example: icf_6a284b7596d3f2b722544e70 pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ object: type: string enum: - instruction_confirmation description: Object type, `instruction_confirmation`. example: instruction_confirmation live_mode: type: boolean description: '`true` for live data, `false` for test data.' device_id: type: string description: Flatpeak Device ID. example: dev_63a6087272941ef077a8fd3e record_reference_id: type: string nullable: true description: The `record_reference_id` the confirmation was submitted with. example: nova-7d1c-2026-08-04T16:01 data: type: array items: $ref: '#/components/schemas/InstructionConfirmationRow' description: >- Confirmed windows, in chronological order, each beside the instruction it answers. response: allOf: - $ref: '#/components/schemas/ResponseTimeSample' readOnly: true description: How quickly the instructions were fetched and confirmed. time_created: type: string format: date-time description: Time when this object was created, in UTC. example: '2026-08-04T16:01:40Z' account_id: type: string example: acc_661677911f2197045e6cf1b1 description: Flatpeak Account ID. pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ required: - id - object - live_mode - device_id - record_reference_id - data - response - time_created - 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' InstructionConfirmationSegment: type: object title: InstructionConfirmationSegment additionalProperties: false properties: start_time: type: string format: date-time description: >- Start of the confirmed window, in UTC. Must lie within an instruction segment. example: '2026-08-04T20:14:00Z' end_time: type: string format: date-time description: End of the confirmed window, in UTC. example: '2026-08-04T22:00:00Z' power_kw: type: number description: >- Power the device will deliver over the window, in kilowatts, signed like the instruction. Equal to the instruction when the device follows it; anything less is recorded as a deviation. example: -4.3 required: - start_time - end_time - power_kw InstructionConfirmationRow: type: object title: InstructionConfirmationRow properties: start_time: type: string format: date-time description: >- Start of the confirmed window, in UTC. Must lie within an instruction segment. example: '2026-08-04T20:14:00Z' end_time: type: string format: date-time description: End of the confirmed window, in UTC. example: '2026-08-04T22:00:00Z' power_kw: type: number description: >- Power the device will deliver over the window, in kilowatts, signed like the instruction. Equal to the instruction when the device follows it; anything less is recorded as a deviation. example: -4.3 instructed_power_kw: type: number description: Power the instruction asked for over the window, in kilowatts. example: -4.3 vpp_event_id: type: string nullable: true description: >- Flatpeak VPP Event ID the instruction is a share of. `null` for a plan. example: vpe_7a1c3e5b9d2f4a6c8e0b1d3f plan_id: type: string nullable: true description: >- Flatpeak Plan ID the instruction comes from. `null` for a VPP event commitment. example: null required: - start_time - end_time - power_kw - instructed_power_kw - vpp_event_id - plan_id ResponseTimeSample: type: object title: ResponseTimeSample description: >- Response timing for one set of instructions, measured by Flatpeak. The trailing medians are published on the Device as `response_time`. additionalProperties: false required: - pickup_seconds - apply_seconds - total_seconds properties: pickup_seconds: type: number description: >- Time between the instructions being created and the OEM fetching them, in seconds. example: 38 apply_seconds: type: number description: >- Time between the OEM fetching the instructions and confirming them, in seconds. example: 173 total_seconds: type: number description: >- Time between the instructions being created and their confirmation, in seconds. example: 211 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.