> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a device > Creates a device. Set `reference_id` to the device's ID in your systems. > [accordion] View device Properties diagram (important!) > > ```mermaid actions={false} placement="top-right" theme={"system"} > --- > config: > theme: mc > --- > flowchart LR > subgraph Storage["Battery system"] > Inverter["Inverter
+ac_export_limit_kw"] > B1@{ label: "BATTERY
+power_kw
+capacity_kwh
" } > end > Grid["Grid"] <--> J(("Main panel")) > J <--
--> EV@{ label: "EV_CHARGER
+max_power_kw
+min_power_kw
+v2g_capable" } > EV <-.-> Vehicle["Electric Vehicle"] > Solar["PV
+peak_power_kw
+azimuth
+tilt
+terrain_shading"] --> Inverter > Inverter --> J & B1 > > B1@{ shape: cylinder} > EV@{ shape: rect} > Solar@{ shape: rect} > style Grid stroke-width:2px,stroke-dasharray: 2 > style J stroke-width:2px,stroke-dasharray: 2 > style Vehicle stroke-width:2px,stroke-dasharray: 2 > ``` ## OpenAPI ````yaml energy-api/reference/flatpeak-api-spec-energy-tariffs.json POST /devices openapi: 3.0.3 info: description: >- The tariff functions of the Flatpeak Energy API: tariff connection, prices, forecasts and costs. Generated from the full Energy API spec by scripts/build-tariff-spec.py. Do not edit. version: 2027-01-01.busbar title: 'Flatpeak Energy API: Tariffs' 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 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: Events description: Retrieve and list account events. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /devices: parameters: [] post: tags: - Devices summary: Create a device description: Creates a device. Set `reference_id` to the device's ID in your systems. operationId: create-device parameters: [] requestBody: $ref: '#/components/requestBodies/DeviceCreate' responses: '201': $ref: '#/components/responses/Device' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '409': $ref: '#/components/responses/409' '422': $ref: '#/components/responses/422' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: requestBodies: DeviceCreate: content: application/json: schema: type: object additionalProperties: false properties: reference_id: type: string description: Your own reference, for example an ID from your system. example: DEV1234567890 location_id: type: string description: Flatpeak Location ID. example: loc_641b90b758fb8e6293716e40 device_type: type: string enum: - BATTERY_STORAGE - ELECTRIC_VEHICLE - EV_CHARGER - AIR_CONDITIONER - HEAT_PUMP - WATER_HEATER - PV_SYSTEM - POWER_GENERATOR - OTHER description: >- What the device is, as your users would name it. Set when you create the device. Connect uses it for the noun your users see: `BATTERY_STORAGE` reads "your battery". example: BATTERY_STORAGE capabilities: allOf: - $ref: '#/components/schemas/DeviceCapabilities' description: >- What the device can do, by subsystem. For tariffs, only a `pv` block is used: optimizations take the solar part of each window from it. required: - location_id - device_type examples: Heat pump: value: reference_id: DEV3456789012 location_id: loc_641b90b758fb8e6293716e40 device_type: HEAT_PUMP Solar system with forecasts: value: reference_id: DEV1234567890 location_id: loc_641b90b758fb8e6293716e40 device_type: PV_SYSTEM capabilities: pv: peak_power_kw: 6.2 azimuth: 180 tilt: 23 terrain_shading: false forecasts_enabled: true description: Creates a device. 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' '403': description: '403 Forbidden: you do not have permission to access this resource.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- 409 Conflict: the resource conflicts with existing data, for example a duplicate reference. 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' Device: description: 'Success: the device resource.' content: application/json: schema: $ref: '#/components/schemas/Device' example: id: dev_63a6087272941ef077a8fd3e object: device reference_id: DEV1234567890 live_mode: true location_id: loc_641b90b758fb8e6293716e40 capabilities: pv: peak_power_kw: 6.2 azimuth: 180 tilt: 23 terrain_shading: false forecasts_enabled: true device_type: PV_SYSTEM time_last_seen: '2026-07-08T19:30:00Z' time_created: '2026-01-20T09:30:00Z' account_id: acc_661677911f2197045e6cf1b1 schemas: DeviceCapabilities: title: DeviceCapabilities type: object description: >- Technical envelope of the device, grouped by subsystem. Include only the subsystems the device has: a battery-only unit omits pv, a solar-only unit omits battery. additionalProperties: false properties: pv: type: object additionalProperties: false description: Present when the device has solar generation. properties: peak_power_kw: type: number minimum: 0 description: >- Peak DC generation capacity of the PV array, in kWp. Required when forecasts_enabled is true. example: 6.4 azimuth: type: number minimum: -180 maximum: 180 description: >- Optional. Degrees from true north the array faces, 0 = north, positive anticlockwise (-90 = east, 135 = southwest). Defaults to the optimal azimuth for the latitude. example: 0 tilt: type: number minimum: 0 maximum: 90 description: >- Optional. Tilt angle in degrees, 0 = horizontal, 90 = vertical. Defaults to 23. example: 23 terrain_shading: type: boolean default: false description: >- Optional. If true, irradiance is adjusted for surrounding terrain using a 90 m elevation model. Defaults to false. forecasts_enabled: type: boolean default: false description: >- Optional. Enables generation forecasting. Requires `peak_power_kw` and a geocoded location, which Connect captures. Defaults to `false`. Device: type: object title: Device description: >- A device: an energy asset at a location, with its hardware identity, capabilities, consents, telemetry duties and, through its own methods, state and settings. properties: id: type: string description: Flatpeak Device ID. example: dev_63a6087272941ef077a8fd3e pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ readOnly: true object: type: string description: Object type. example: device enum: - device default: device readOnly: true reference_id: type: string description: >- Your own reference, for example an ID from your system. `null` when not set. example: DEV1234567890 nullable: true live_mode: type: boolean description: '`true` for live data, `false` for test data.' location_id: type: string description: >- Flatpeak Location ID of the device's current location. Moves are appended to the device's location history; past records keep the location current at the time. example: loc_641b90b758fb8e6293716e40 capabilities: $ref: '#/components/schemas/DeviceCapabilities' device_type: type: string enum: - BATTERY_STORAGE - ELECTRIC_VEHICLE - EV_CHARGER - AIR_CONDITIONER - HEAT_PUMP - WATER_HEATER - PV_SYSTEM - POWER_GENERATOR - OTHER description: >- What the device is, as your users would name it. Set when you create the device. Connect uses it for the noun your users see: `BATTERY_STORAGE` reads "your battery". example: BATTERY_STORAGE time_last_seen: type: string format: date-time description: >- Time when Flatpeak last heard from the device, through an API call or telemetry, in UTC. `null` until first contact. example: '2026-03-22T11:12:21Z' nullable: true time_created: type: string description: Time when the object was created, in UTC. example: '2026-01-24T14:15:22Z' format: date-time account_id: type: string description: Flatpeak Account ID. example: acc_661677911f2197045e6cf1b1 pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ readOnly: true required: - id - object - reference_id - live_mode - location_id - capabilities - device_type - time_last_seen - 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' 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.