Skip to main content

Working with endpoints

This section explains how to use Homsai APIs to model a plant: creating and managing plants, devices and sensors, and the recommended client‑side workflow.

Overview​

In Homsai, modeling a plant usually follows these steps:

  1. Create a Plant.
  2. Configure the Sensors attached to the plant and/or devices.
  3. Add one or more Devices to the plant.

In this guide you will see:

  • how to create, read, update and delete Plants;
  • how to define and use Sensors to collect data;
  • how to manage Devices within a plant.

Plants​

Plants are the starting point: without a plant you cannot attach devices or sensors.

Typical operations:

  • Create a plant

    • Endpoint: POST /plants
    • Purpose: defines a new plant (e.g. “Rossi Home – PV + Battery”).
    • Requires: permission PLANTS CREATE.

  • List plants

    • Endpoint: GET /plants
    • Purpose: get the list of the user’s plants with pagination and filters (search, plantUuids, externalIds).
    • Requires: permission PLANTS READ.

  • Get plant details

    • Endpoint: GET /plants/{plantUuid}
    • Purpose: retrieve full information for a single plant.
    • Requires: permission PLANTS READ and ownership on the plant.

  • Update a plant

    • Endpoint: PUT /plants/{plantUuid}
    • Purpose: modify metadata and configuration of an existing plant.
    • Requires: permission PLANTS UPDATE and ownership.

  • Delete a plant

    • Endpoint: DELETE /plants/{plantUuid}
    • Purpose: remove a plant (and dependent entities according to domain rules).
    • Requires: permission PLANTS DELETE and ownership.

Devices​

Devices represent the physical or logical components of the plant (inverters, batteries, heat pumps, wallboxes, etc.) and are always linked to a plant.

Typical operations:

  • Create a device in a plant

    • Endpoint: POST /plants/{plantUuid}/devices
    • Purpose: add a new device to the plant (body: DevicesCreateDto).
    • Requires: permission DEVICES CREATE and plant ownership.

  • List devices of a plant

    • Endpoint: GET /plants/{plantUuid}/devices
    • Purpose: get the list of devices of a plant, with support for search, includeRelationships, pagination.
    • Requires: permission DEVICES READ.

  • Get device details

    • Endpoint: GET /plants/{plantUuid}/devices/{deviceUuid}
    • Purpose: retrieve full information about a device, optionally including relationships (e.g. linked sensors).
    • Parameters: includeRelationships.
    • Requires: permission DEVICES READ.

  • Update a device

    • Endpoint: PUT /plants/{plantUuid}/devices/{deviceUuid}
    • Purpose: modify configuration or metadata of a device.
    • Requires: permission DEVICES UPDATE and plant ownership.

  • Delete a device

    • Endpoint: DELETE /plants/{plantUuid}/devices/{deviceUuid}
    • Purpose: remove a device from the plant.
    • Requires: permission DEVICES DELETE and plant ownership.

Sensors​

Sensors are the data sources of the plant: they measure consumption, production and other values, and can be attached to devices or directly to the plant.

Typical operations:

  • Create a sensor

    • Endpoint: POST /plants/{plantUuid}/sensors
    • Purpose: add a new sensor linked to a plant (and optionally to a device).
    • Parameters: optional flag ignoreConnectionsTest to skip connection checks.
    • Requires: permission SENSORS CREATE.

  • List sensors of a plant

    • Endpoint: GET /plants/{plantUuid}/sensors
    • Purpose: get the list of sensors associated with a plant.
    • Parameters:
      • search for text filtering;
      • dataTypesCollectUuid to filter by collected data type;
      • includeRelationships to include relationships (e.g. linked device);
      • pagination parameters (page, size, sort).
    • Requires: permission SENSORS READ and ownership.

  • Get sensor details

    • Endpoint: GET /plants/{plantUuid}/sensors/{sensorUuid}
    • Purpose: retrieve configuration and relationships of a specific sensor.
    • Parameters: includeRelationships.
    • Requires: permission SENSORS READ and ownership.

  • Update a sensor

    • Endpoint: PUT /plants/{plantUuid}/sensors/{sensorUuid}
    • Purpose: change configuration, associations or metadata of the sensor.
    • Requires: permission SENSORS UPDATE and ownership.

  • Delete a sensor

    • Endpoint: DELETE /plants/{plantUuid}/sensors/{sensorUuid}
    • Purpose: remove a sensor from the plant.
    • Requires: permission SENSORS DELETE and ownership.

To correctly model a new plant from a client perspective, the recommended order is:

  1. Create the Plant

    • Use POST /plants to define the plant (name, external identifiers, metadata).

  2. Configure Sensors

    • Create sensors with POST /plants/{plantUuid}/sensors, linking them to devices or directly to the plant.
    • Make sure to use the appropriate Sensor Types and Data Types Collects (power, energy, temperature, etc.).

  3. Register main Devices

    • For each physical component (inverter, battery, heat pump, wallbox, etc.), use POST /plants/{plantUuid}/devices.
    • Assign the correct Device Type to enable proper metrics and forecasts.

  4. Verify configuration

    • Use GET /plants/{plantUuid}/devices and GET /plants/{plantUuid}/sensors with includeRelationships to check that the domain structure is correct.
    • Only after this phase does it make sense to start using metrics and forecast endpoints (consumptions, productions, pv‑health, predict, etc.).

Following this flow makes client‑side integration more straightforward and reduces configuration errors that may impact energy metrics and subsequent analyses.