Reonic Components API
Catalog of solar, storage, EV charger, and heat-pump products available to your workspace.
OpenAPI Specification
openapi: 3.1.0
info:
title: Reonic REST Api v3 Activities Components API
description: 'The Reonic REST API v3 provides programmatic access to create and manage resources. The API follows REST principles and returns responses in JSON format. Authentication is required via an API key passed in the X-Authorization header.
## Errors
All endpoints return errors with the same JSON shape:
```json
{ "message": "human-readable description" }
```
`400` responses additionally include an `errors` field with per-field validation details.
The HTTP status code identifies the cause:
| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad Request | Path params, query string, or request body failed validation. Inspect `errors` for the field-level breakdown. |
| `401` | Unauthorized | The `X-Authorization` header is missing, malformed, does not match an active API key, or belongs to a different API version. The response never indicates which check failed; check that the key matches the endpoint version. API v3 endpoints require a v3 key with the `rnc_v3_` prefix. |
| `403` | Forbidden | The API key is read-only and the request targeted a write endpoint (`POST`). Issue a key with write access. |
| `404` | Not Found | A resource referenced by a path id does not exist or is not visible to your workspace. |
| `429` | Too Many Requests | The per-client rate limit was exceeded. See **Rate limiting** below. |
| `500` | Internal Server Error | Unexpected failure. Safe to retry once; if it persists, contact support. |
| `503` | Service Unavailable | A backing dependency is temporarily unavailable. Retry with exponential backoff. |
## Rate limiting
Limits are shared across all API keys you hold and reset on a 1-minute window. Two buckets:
| Bucket | Limit | Applies to |
|--------|-------|------------|
| `cached` | 500 / min | `GET` requests served from the response cache |
| `uncached` | 30 / min | Cache misses, `GET` requests sent with `Reonic-Cache-Control: no-cache`, and all `POST` requests |
Every response includes:
- `X-RateLimit-Bucket` — `cached` or `uncached`
- `X-RateLimit-Limit` — the bucket''s ceiling (`500` or `30`)
- `X-RateLimit-Remaining` — calls left in the current window
- `X-RateLimit-Reset` — Unix epoch seconds at which the window resets
- `X-RateLimit-Policy` — `<limit>;w=60`
`429` responses additionally set `Retry-After` (in seconds). Wait at least that long before retrying.
## Caching and Reonic-Cache-Control
`GET` responses are cached for up to 1 hour. Identical requests (same path and query) on the same API key return the cached result. To force a fresh read, send `Reonic-Cache-Control: no-cache`; the response is then refreshed and re-cached. Forced refreshes count against the `uncached` rate-limit bucket.
The standard `Cache-Control` header is not honored. Use `Reonic-Cache-Control` to control caching behavior.
## Authentication
Every request must include your API key in the `X-Authorization` header:
```
X-Authorization: <your-api-key>
```
API keys are issued from the Reonic web app and look like `rnc_v3_…`. Send the full value, including the prefix.
'
version: 3.2.0
contact:
email: kontakt@reonic.de
url: https://reonic.com
name: Reonic GmbH
servers:
- url: '{apiBaseUrl}/rest/v3/'
security:
- X-Authorization: []
tags:
- name: Components
description: Catalog of solar, storage, EV charger, and heat-pump products available to your workspace.
paths:
/components:
get:
summary: List components
description: 'List all solar components.
**Allowed API keys:** Read-only, Read and Write'
tags:
- Components
parameters:
- schema:
type:
- array
- 'null'
items:
type: string
enum:
- module
- inverter
- microinverter
- optimizer
- virtualBattery
- batteryStorage
- evCharger
- heatPump
- airHeatPump
- hotWaterHeatPump
- heatingStorage
- hotWaterStorage
- heatingRod
- radiator
- indoorUnitAirHeatPump
- accessoryToEvCharger
- accessoryToHeatPump
- accessoryToModule
- accessoryToInverter
- accessoryToBatteryStorage
- other
- moduleFrameConstruction
- serviceFee
- installationFee
maxItems: 24
description: Filter by component type(s). Omit to include all types.
examples:
- module
- inverter,batteryStorage
required: false
description: Filter by component type(s). Omit to include all types.
name: componentType
in: query
- schema:
type: string
enum:
- exclude
- include
- only
default: exclude
description: 'Controls whether archived components appear in results. Default: exclude.'
required: false
description: 'Controls whether archived components appear in results. Default: exclude.'
name: archived
in: query
- schema:
type: string
example: no-cache
required: false
name: Reonic-Cache-Control
in: header
description: Set to 'no-cache' to bypass the 1-hour response cache and force a fresh read. The fresh response is then written back to the cache for subsequent callers. Forced refreshes count against the uncached rate-limit bucket (30/min); only cache hits count against the cached bucket (500/min).
responses:
'200':
description: List of all components
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Component'
description: List of items
required:
- data
/components/{componentId}:
get:
summary: Get component
description: 'Get a single solar component by its ID.
**Allowed API keys:** Read-only, Read and Write'
tags:
- Components
parameters:
- schema:
type: string
format: uuid
required: true
name: componentId
in: path
- schema:
type: string
example: no-cache
required: false
name: Reonic-Cache-Control
in: header
description: Set to 'no-cache' to bypass the 1-hour response cache and force a fresh read. The fresh response is then written back to the cache for subsequent callers. Forced refreshes count against the uncached rate-limit bucket (30/min); only cache hits count against the cached bucket (500/min).
responses:
'200':
description: The component
content:
application/json:
schema:
$ref: '#/components/schemas/Component'
/components/create:
post:
summary: Create component
description: 'Create a new component.
**Allowed API keys:** Read and Write'
tags:
- Components
requestBody:
content:
application/json:
schema:
type: object
properties:
componentType:
type: string
enum:
- module
- inverter
- microinverter
- optimizer
- virtualBattery
- batteryStorage
- evCharger
- heatPump
- airHeatPump
- hotWaterHeatPump
- heatingStorage
- hotWaterStorage
- heatingRod
- radiator
- indoorUnitAirHeatPump
- accessoryToEvCharger
- accessoryToHeatPump
- accessoryToModule
- accessoryToInverter
- accessoryToBatteryStorage
- other
- moduleFrameConstruction
- serviceFee
- installationFee
description: Type of component to create.
name:
type: string
minLength: 1
maxLength: 1000
description:
type: string
minLength: 1
maxLength: 10000
brand:
type: string
minLength: 1
maxLength: 500
articleNumber:
type: string
minLength: 1
maxLength: 100
description: Internal article / part number.
gtin:
type: string
minLength: 1
maxLength: 100
description: Global Trade Item Number, sometimes referred to as EAN.
salesPrice:
type: number
minimum: 0
maximum: 1000000000000
description: Price charged to the end customer, net (excluding VAT).
vatRate:
type: number
minimum: 0
maximum: 1
description: VAT rate as a fraction (e.g. 0.19 for 19%).
purchasePrice:
type: number
minimum: 0
maximum: 1000000000000
description: Cost paid to acquire the component, net (excluding VAT). Used internally for margin calculations.
quantityUnit:
type: string
enum:
- item
- squareMeter
- meter
- flatRate
- linearMeter
- kilometer
- hours
- day
- month
- kWp
description: Unit the component is billed in (e.g. per item, per m², flat rate).
required:
- componentType
- name
additionalProperties: false
responses:
'201':
description: The created component
content:
application/json:
schema:
$ref: '#/components/schemas/Component'
/components/{componentId}/update:
post:
summary: Update component
description: 'Update the basic fields of a solar component. Partial update: omitted fields are left unchanged.
**Allowed API keys:** Read and Write'
tags:
- Components
parameters:
- schema:
type: string
format: uuid
required: true
name: componentId
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 1000
description:
type:
- string
- 'null'
minLength: 1
maxLength: 10000
brand:
type: string
minLength: 1
maxLength: 500
articleNumber:
type:
- string
- 'null'
minLength: 1
maxLength: 100
description: Internal article / part number.
gtin:
type:
- string
- 'null'
minLength: 1
maxLength: 100
description: Global Trade Item Number, sometimes referred to as EAN.
salesPrice:
type: number
minimum: 0
maximum: 1000000000000
description: Price charged to the end customer, net (excluding VAT).
vatRate:
type: number
minimum: 0
maximum: 1
description: VAT rate as a fraction (e.g. 0.19 for 19%).
purchasePrice:
type:
- number
- 'null'
minimum: 0
maximum: 1000000000000
description: Cost paid to acquire the component, net (excluding VAT). Used internally for margin calculations.
quantityUnit:
type:
- string
- 'null'
enum:
- item
- squareMeter
- meter
- flatRate
- linearMeter
- kilometer
- hours
- day
- month
- kWp
- null
description: Unit the component is billed in (e.g. per item, per m², flat rate).
archived:
type: boolean
description: '`true` to archive the component, `false` to unarchive.'
propagateToPackagesAndTemplates:
type: boolean
default: false
description: 'When true, the changes also apply to planning packages and templates that use this component. Default: false'
additionalProperties: false
responses:
'200':
description: The updated component
content:
application/json:
schema:
$ref: '#/components/schemas/Component'
components:
schemas:
ComponentModuleFrameConstruction:
type: object
properties:
id:
type: string
format: uuid
description: Stable identifier, across versions
example: 123e4567-e89b-12d3-a456-426614174000
versionId:
type: string
format: uuid
description: Identifies this specific version of a component. Since only the latest version is returned, a change in versionId for the same id signals that the component has been updated.
example: 123e4567-e89b-12d3-a456-426614174000
name:
type: string
description:
type:
- string
- 'null'
brand:
type: string
description: User-typed brand string
articleNumber:
type:
- string
- 'null'
description: Internal article / part number.
gtin:
type:
- string
- 'null'
description: Global Trade Item Number, sometimes referred to as EAN.
salesPrice:
type: number
description: Price charged to the end customer, net (excluding VAT). Apply the `vatRate` on top to get the gross price.
vatRate:
type: number
minimum: 0
maximum: 1
description: VAT rate as a fraction (e.g. 0.19 for 19%).
purchasePrice:
type:
- number
- 'null'
description: Cost paid to acquire the component, net (excluding VAT). Used internally for margin calculations; null when not tracked.
quantityUnit:
type:
- string
- 'null'
enum:
- item
- squareMeter
- meter
- flatRate
- linearMeter
- kilometer
- hours
- day
- month
- kWp
- null
description: Unit the component is billed in (e.g. per item, per m², flat rate).
imageUrl:
type:
- string
- 'null'
format: uri
description: Short-lived URL to the component image. Expires after 24 hours.
createdAt:
type: string
format: date-time
example: '2026-01-01T15:30:00.000Z'
updatedAt:
type:
- string
- 'null'
format: date-time
description: Last edited date.
example: '2026-01-01T15:30:00.000Z'
archivedAt:
type:
- string
- 'null'
format: date-time
example: '2026-01-01T15:30:00.000Z'
componentType:
type: string
enum:
- moduleFrameConstruction
attributes:
type: object
properties: {}
additionalProperties: false
required:
- id
- versionId
- name
- description
- brand
- articleNumber
- gtin
- salesPrice
- vatRate
- purchasePrice
- quantityUnit
- imageUrl
- createdAt
- updatedAt
- archivedAt
- componentType
- attributes
ComponentAccessoryToInverter:
type: object
properties:
id:
type: string
format: uuid
description: Stable identifier, across versions
example: 123e4567-e89b-12d3-a456-426614174000
versionId:
type: string
format: uuid
description: Identifies this specific version of a component. Since only the latest version is returned, a change in versionId for the same id signals that the component has been updated.
example: 123e4567-e89b-12d3-a456-426614174000
name:
type: string
description:
type:
- string
- 'null'
brand:
type: string
description: User-typed brand string
articleNumber:
type:
- string
- 'null'
description: Internal article / part number.
gtin:
type:
- string
- 'null'
description: Global Trade Item Number, sometimes referred to as EAN.
salesPrice:
type: number
description: Price charged to the end customer, net (excluding VAT). Apply the `vatRate` on top to get the gross price.
vatRate:
type: number
minimum: 0
maximum: 1
description: VAT rate as a fraction (e.g. 0.19 for 19%).
purchasePrice:
type:
- number
- 'null'
description: Cost paid to acquire the component, net (excluding VAT). Used internally for margin calculations; null when not tracked.
quantityUnit:
type:
- string
- 'null'
enum:
- item
- squareMeter
- meter
- flatRate
- linearMeter
- kilometer
- hours
- day
- month
- kWp
- null
description: Unit the component is billed in (e.g. per item, per m², flat rate).
imageUrl:
type:
- string
- 'null'
format: uri
description: Short-lived URL to the component image. Expires after 24 hours.
createdAt:
type: string
format: date-time
example: '2026-01-01T15:30:00.000Z'
updatedAt:
type:
- string
- 'null'
format: date-time
description: Last edited date.
example: '2026-01-01T15:30:00.000Z'
archivedAt:
type:
- string
- 'null'
format: date-time
example: '2026-01-01T15:30:00.000Z'
componentType:
type: string
enum:
- accessoryToInverter
attributes:
type: object
properties: {}
additionalProperties: false
required:
- id
- versionId
- name
- description
- brand
- articleNumber
- gtin
- salesPrice
- vatRate
- purchasePrice
- quantityUnit
- imageUrl
- createdAt
- updatedAt
- archivedAt
- componentType
- attributes
ComponentHotWaterStorage:
type: object
properties:
id:
type: string
format: uuid
description: Stable identifier, across versions
example: 123e4567-e89b-12d3-a456-426614174000
versionId:
type: string
format: uuid
description: Identifies this specific version of a component. Since only the latest version is returned, a change in versionId for the same id signals that the component has been updated.
example: 123e4567-e89b-12d3-a456-426614174000
name:
type: string
description:
type:
- string
- 'null'
brand:
type: string
description: User-typed brand string
articleNumber:
type:
- string
- 'null'
description: Internal article / part number.
gtin:
type:
- string
- 'null'
description: Global Trade Item Number, sometimes referred to as EAN.
salesPrice:
type: number
description: Price charged to the end customer, net (excluding VAT). Apply the `vatRate` on top to get the gross price.
vatRate:
type: number
minimum: 0
maximum: 1
description: VAT rate as a fraction (e.g. 0.19 for 19%).
purchasePrice:
type:
- number
- 'null'
description: Cost paid to acquire the component, net (excluding VAT). Used internally for margin calculations; null when not tracked.
quantityUnit:
type:
- string
- 'null'
enum:
- item
- squareMeter
- meter
- flatRate
- linearMeter
- kilometer
- hours
- day
- month
- kWp
- null
description: Unit the component is billed in (e.g. per item, per m², flat rate).
imageUrl:
type:
- string
- 'null'
format: uri
description: Short-lived URL to the component image. Expires after 24 hours.
createdAt:
type: string
format: date-time
example: '2026-01-01T15:30:00.000Z'
updatedAt:
type:
- string
- 'null'
format: date-time
description: Last edited date.
example: '2026-01-01T15:30:00.000Z'
archivedAt:
type:
- string
- 'null'
format: date-time
example: '2026-01-01T15:30:00.000Z'
componentType:
type: string
enum:
- hotWaterStorage
attributes:
type: object
properties:
volume:
type: number
description: Storage volume in litres.
standingHeatLoss:
type: number
description: Standing heat loss in W.
required:
- volume
- standingHeatLoss
required:
- id
- versionId
- name
- description
- brand
- articleNumber
- gtin
- salesPrice
- vatRate
- purchasePrice
- quantityUnit
- imageUrl
- createdAt
- updatedAt
- archivedAt
- componentType
- attributes
ComponentOther:
type: object
properties:
id:
type: string
format: uuid
description: Stable identifier, across versions
example: 123e4567-e89b-12d3-a456-426614174000
versionId:
type: string
format: uuid
description: Identifies this specific version of a component. Since only the latest version is returned, a change in versionId for the same id signals that the component has been updated.
example: 123e4567-e89b-12d3-a456-426614174000
name:
type: string
description:
type:
- string
- 'null'
brand:
type: string
description: User-typed brand string
articleNumber:
type:
- string
- 'null'
description: Internal article / part number.
gtin:
type:
- string
- 'null'
description: Global Trade Item Number, sometimes referred to as EAN.
salesPrice:
type: number
description: Price charged to the end customer, net (excluding VAT). Apply the `vatRate` on top to get the gross price.
vatRate:
type: number
minimum: 0
maximum: 1
description: VAT rate as a fraction (e.g. 0.19 for 19%).
purchasePrice:
type:
- number
- 'null'
description: Cost paid to acquire the component, net (excluding VAT). Used internally for margin calculations; null when not tracked.
quantityUnit:
type:
- string
- 'null'
enum:
- item
- squareMeter
- meter
- flatRate
- linearMeter
- kilometer
- hours
- day
- month
- kWp
- null
description: Unit the component is billed in (e.g. per item, per m², flat rate).
imageUrl:
type:
- string
- 'null'
format: uri
description: Short-lived URL to the component image. Expires after 24 hours.
createdAt:
type: string
format: date-time
example: '2026-01-01T15:30:00.000Z'
updatedAt:
type:
- string
- 'null'
format: date-time
description: Last edited date.
example: '2026-01-01T15:30:00.000Z'
archivedAt:
type:
- string
- 'null'
format: date-time
example: '2026-01-01T15:30:00.000Z'
componentType:
type: string
enum:
- other
attributes:
type: object
properties: {}
additionalProperties: false
required:
- id
- versionId
- name
- description
- brand
- articleNumber
- gtin
- salesPrice
- vatRate
- purchasePrice
- quantityUnit
- imageUrl
- createdAt
- updatedAt
- archivedAt
- componentType
- attributes
ComponentInverter:
type: object
properties:
id:
type: string
format: uuid
description: Stable identifier, across versions
example: 123e4567-e89b-12d3-a456-426614174000
versionId:
type: string
format: uuid
description: Identifies this specific version of a component. Since only the latest version is returned, a change in versionId for the same id signals that the component has been updated.
example: 123e4567-e89b-12d3-a456-426614174000
name:
type: string
description:
type:
- string
- 'null'
brand:
type: string
description: User-typed brand string
articleNumber:
type:
- string
- 'null'
description: Internal article / part number.
gtin:
type:
- string
- 'null'
description: Global Trade Item Number, sometimes referred to as EAN.
salesPrice:
type: number
description: Price charged to the end customer, net (excluding VAT). Apply the `vatRate` on top to get the gross price.
vatRate:
type: number
minimum: 0
maximum: 1
description: VAT rate as a fraction (e.g. 0.19 for 19%).
purchasePrice:
type:
- number
- 'null'
description: Cost paid to acquire the component, net (excluding VAT). Used internally for margin calculations; null when not tracked.
quantityUnit:
type:
- string
- 'null'
enum:
- item
- squareMeter
- meter
- flatRate
- linearMeter
- kilometer
- hours
- day
- month
- kWp
- null
description: Unit the component is billed in (e.g. per item, per m², flat rate).
imageUrl:
type:
- string
- 'null'
format: uri
description: Short-lived URL to the component image. Expires after 24 hours.
createdAt:
type: string
format: date-time
example: '2026-01-01T15:30:00.000Z'
updatedAt:
type:
- string
- 'null'
format: date-time
description: Last edited date.
example: '2026-01-01T15:30:00.000Z'
archivedAt:
type:
- string
- 'null'
format: date-time
example: '2026-01-01T15:30:00.000Z'
componentType:
type: string
enum:
- inverter
attributes:
type: object
properties:
nominalOutputPower:
type: number
description: Nominal AC output power in W.
outputVoltage:
type: integer
description: Nominal AC output voltage in V.
nominalInputPower:
type: number
description: Nominal DC input power in W.
efficiency:
type: number
description: Conversion efficiency as a fraction (e.g. 0.97 for 97%).
numberOfPhases:
type:
- integer
- 'null'
description: Number of AC phases (1 or 3).
width:
type: number
description: Width in cm.
height:
type: number
description: Height in cm.
depth:
type: number
description: Depth in cm.
weight:
type: number
description: Weight in kg.
minimumMPPVoltage:
type:
- number
- 'null'
description: Minimum MPP-tracker input voltage in V.
maximumMPPVoltage:
type:
- number
- 'null'
description: Maximum MPP-tracker input voltage in V.
maximumVoltage:
type:
- number
- 'null'
description: Absolute maximum DC input voltage in V.
maximumCurrent:
type:
- number
- 'null'
description: Maximum DC input current per string in A.
numberOfStringInputs:
type:
- integer
- 'null'
description: Number of DC string inputs.
numberOfMPPTrackers:
type:
- integer
- 'null'
description: Number of independent MPP trackers.
required:
- nominalOutputPower
- outputVoltage
- nominalInputPower
- efficiency
- numberOfPhases
- width
- height
- depth
- weight
- minimumMPPVoltage
- maximumMPPVoltage
- maximumVoltage
- maximumCurrent
- numberOfStringInputs
- numberOfMPPTrackers
required:
- id
- versionId
- name
- description
- brand
- articleNumber
- gtin
- salesPrice
- vatRate
- purchasePrice
- quantityUnit
- imageUrl
- createdAt
- updatedAt
- archivedAt
- componentType
- attributes
ComponentOptimizer:
type: object
properties:
id:
type: string
format: uuid
description: Stable identifier, across versions
example: 123e4567-e89b-12d3-a456-426614174000
versionId:
type: string
format: uuid
description: Identifies this specific version of a component. Since only the latest version is returned, a change in versio
# --- truncated at 32 KB (108 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/reonic/refs/heads/main/openapi/reonic-components-api-openapi.yml