Skip to content
docs

Log a watering

POST /modules/{moduleId}/irrigation/events
  • Scope irrigation:write
  • API key x-api-key
  • Base URL https://api.hub.akuasense.com/v1

Millimetres are FROZEN here, using the equipment valid on the DATE OF THE WATERING (not the date of the call) and a snapshot of the parameters used. warnings is not a failure: the row is recorded even with no computable dose — validation refuses the inconsistent, never the incomplete. The row carries source: "api".

Path parameters

  • moduleId integer required

Headers

  • Idempotency-Key string

    Replays the same 2xx response (24 h)

Request body

  • startedAt string date-time required

    Start of the watering.

  • endedAt string date-time

    End. Alternative to durationMin — the duration is derived from it.

  • inputMode string required

    How the application is declared. duration requires NO configuration (it is the universal fallback mode) but only yields a dose once the flow rate is known; depth_mm is taken as is; volume_m3 requires the irrigated area.

    Values: durationdepth_mmvolume_m3
  • durationMin integer

    Duration in minutes. Alternative to endedAt — only one of the two is stored.

  • inputDepthMm number

    Depth of water in mm. Required in depth_mm mode, and then taken as is.

  • inputVolumeM3 number

    Volume in m³. Required in volume_m3 mode.

  • status string

    planned = scheduled, done = done, skipped = cancelled (never shown on charts).

    Values: planneddoneskipped
  • note string

Response

201

Watering recorded

  • event IrrigationEvent

    One water application, at the probe. Millimetres are FROZEN at write time and never recomputed on read.

    Show 18 attributes Hide attributes
    • id integer
    • moduleId integer
    • scheduleId integer nullable

      Schedule this row is an occurrence of, if any.

    • isDetached boolean

      Schedule occurrence corrected by hand: the nightly regeneration will never touch it again.

    • startedAt string date-time
    • durationMin integer nullable

      Duration in minutes. null in depth_mm/volume_m3 mode when no duration was declared.

    • endedAt string date-time nullable

      Computed (startedAt + durationMin), not stored. null if the duration is unknown.

    • inputMode string

      How the application is declared. duration requires NO configuration (it is the universal fallback mode) but only yields a dose once the flow rate is known; depth_mm is taken as is; volume_m3 requires the irrigated area.

      Values: durationdepth_mmvolume_m3
    • inputDepthMm number nullable

      Value entered in depth_mm mode, in mm.

    • inputVolumeM3 number nullable

      Value entered in volume_m3 mode, in m³.

    • waterMm number nullable

      Dose over the TOTAL AREA, in mm — the figure comparable to rainfall, ETc or the water meter. null = cannot be converted as things stand; the row stays valid and is shown with its duration.

    • waterMmWetted number nullable

      Dose in the WETTED ZONE (= waterMm ÷ fw), in mm — where the probe is installed, and therefore what explains the observed rise in VWC. null when fw is 1: both figures would be identical.

    • configSnapshot IrrigationConfigSnapshot nullable

      Snapshot of the parameters ACTUALLY USED to compute this row, frozen at write time. Distinct from the setup history: the history says which equipment was in place on a given date, the snapshot says what was actually used — the two can legitimately differ if the setup has been corrected since.

      Show 8 attributes Hide attributes
      • installationId integer nullable

        Setup version used.

      • scope string nullable

        Scope this setup came from.

        Values: moduleparcelnull
      • system string nullable
      • flowMmPerH number nullable

        Application rate used, in mm/h.

      • fractionWetted number nullable

        Wetted soil fraction used (0 < fw ≤ 1).

      • fractionWettedIsDefault boolean

        true = system default, not entered.

      • irrigatedAreaM2 number nullable

        Irrigated area used, in m².

      • computedAt string date-time
    • status string

      planned = scheduled, done = done, skipped = cancelled (never shown on charts).

      Values: planneddoneskipped
    • source string

      Where the row comes from. manual = entered in the hub · schedule = occurrence materialized by a schedule · api = this API · mcp = AI assistant. Read-only: the source is set by whichever surface writes the row.

      Values: manualscheduleapimcp
    • verifiedAt string date-time nullable

      null = nobody confirmed this watering (occurrence auto-confirmed by a schedule).

    • note string nullable
    • createdAt string date-time
  • warnings array of IrrigationWarning

    Why the dose could not be computed, or which assumption it rests on. NONE of them is blocking: the watering is recorded whatever happens, waterMm simply staying null.

    Values: NO_INSTALLATIONMISSING_FLOW_RATEMISSING_IRRIGATED_AREADEFAULT_FRACTION_WETTED

Errors

  • 400

    Entry refused

    INVALID_INPUT_MODEINVALID_DURATIONINVALID_ENDED_ATENDED_BEFORE_STARTEDINVALID_DEPTHINVALID_VOLUMEMISSING_DURATIONMISSING_DEPTHMISSING_VOLUMEINVALID_STARTED_ATINVALID_STATUSMODULE_NOT_OWNED
  • 401

    Not authenticated

  • 403

    Insufficient scope/role, or outside your company