Skip to content
docs

Declare a CHANGE of equipment on the probe

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

Creates a new VERSION of the setup. The version covering effectiveFrom is closed on that date; those starting AFTER it are never touched — which is what makes it possible to document the past after the fact. Waterings of the probe (or of the parcel’s probes) left without a dose are then completed automatically; a dose already recorded is never rewritten. To fix a typo without lengthening the history, use PATCH /irrigation/installations/{versionId}.

Path parameters

  • moduleId integer required

Headers

  • Idempotency-Key string

    Replays the same 2xx response (24 h)

Request body

  • system string required

    Type of equipment. Determines the default wetted soil fraction (FAO-56 table 20): drip 0.35 · micro_sprinkler 0.60 · all others 1.00.

    Values: dripmicro_sprinklersprinklerpivotgravitymanualother
  • emitterFlowLph number

    Flow rate of one emitter, in L/h (printed on the equipment).

  • emittersPerM2 number

    Emitters per m² = 1 ÷ (emitter spacing × lateral spacing, in m).

  • flowMmPerH number

    Application rate in mm/h. IGNORED if emitterFlowLph AND emittersPerM2 are both provided — the geometry is the more precise entry, and letting the two diverge would produce millimetres nobody could account for.

  • irrigatedAreaM2 number

    Irrigated area in m². Needed to convert a volume (m³) into mm.

  • fractionWetted number

    Wetted soil fraction (fw). NOT to be filled in under normal circumstances: the system default (FAO-56 table 20) applies. Reserved for atypical installations.

  • notes string
  • effectiveFrom string date-time

    Date it TAKES EFFECT in the field. Absent = now, EXCEPT for the very first setup applicable to the target (no version for it nor, for a probe, for its parcel): it then applies from the very beginning (validFrom = 1970-01-01T00:00:00Z), so that waterings already logged receive their dose. A past date documents the period back then: the version covering that date is closed at that instant, and later versions are left INTACT. The future is refused (EFFECTIVE_FROM_IN_FUTURE).

Response

200

Configuration after the write

  • moduleId integer
  • parcelId integer nullable
  • installation IrrigationInstallation nullable

    Setup EFFECTIVE today, after scope resolution. null = no setup.

    Show 13 attributes Hide attributes
    • id integer
    • scope string

      Scope. A probe setup wins AS A WHOLE over its parcel’s — never field by field.

      Values: moduleparcel
    • parcelId integer nullable
    • moduleId integer nullable
    • system string

      Type of equipment. Determines the default wetted soil fraction (FAO-56 table 20): drip 0.35 · micro_sprinkler 0.60 · all others 1.00.

      Values: dripmicro_sprinklersprinklerpivotgravitymanualother
    • flowMmPerH number nullable

      Application rate in mm/h. Computed when the drip geometry is provided (emitterFlowLph × emittersPerM2), otherwise entered directly — it is the manufacturer’s unit for sprinkler and pivot systems. null: a duration will not be convertible into mm.

    • emitterFlowLph number nullable

      Flow rate of ONE emitter, in L/h. This is what is printed on the equipment.

    • emittersPerM2 number nullable

      Density of emitters per m². Nobody knows this figure off the top of their head: it follows from the spacings — 1 ÷ (emitter spacing × lateral spacing, in m), or (emitters per tree) ÷ (area per tree).

    • fractionWetted number

      Wetted soil fraction (fw, FAO-56 table 20), 0 < fw ≤ 1. Always filled in: the entered value, otherwise the system default. Not something to ask a farmer.

    • fractionWettedIsDefault boolean

      true = comes from the system default, never entered.

    • irrigatedAreaM2 number nullable

      Irrigated area in m². Required to convert a volume into mm.

    • validFrom string date-time

      Date this version TAKES EFFECT in the field.

    • validTo string date-time nullable

      Upper bound, EXCLUDED. null = current version.

  • defaultFractionWetted number nullable

    What fw would be if it were not entered.

  • placement IrrigationPlacement nullable

    Position of the probe relative to the emitter. ⚠️ It enters NO calculation and must not: it is an observation variable, meant to explain after the fact why a sensor stays silent (probe planted outside the wetted bulb).

    Show 3 attributes Hide attributes
    • emitterDistanceCm integer nullable

      Distance to the nearest emitter, in cm. 0 is legitimate.

    • notes string nullable
    • setAt string date-time
  • canGeneralize boolean

    Can this probe’s setup be pushed up to the parcel?

  • hasParcelInstallation boolean

    Is there a parcel setup to fall back on?

  • siblingOverrides integer

    Number of OTHER probes on the parcel carrying their own current setup — what generalize with dropSiblings would overwrite.

  • versions array of IrrigationInstallationVersion

    Full history applicable to this probe — its own versions AND its parcel’s, each tagged with its scope, most recent first.

    Show 15 attributes Hide attributes
    • id integer
    • scope string

      Scope. A probe setup wins AS A WHOLE over its parcel’s — never field by field.

      Values: moduleparcel
    • parcelId integer nullable
    • moduleId integer nullable
    • system string

      Type of equipment. Determines the default wetted soil fraction (FAO-56 table 20): drip 0.35 · micro_sprinkler 0.60 · all others 1.00.

      Values: dripmicro_sprinklersprinklerpivotgravitymanualother
    • flowMmPerH number nullable

      Application rate in mm/h. Computed when the drip geometry is provided (emitterFlowLph × emittersPerM2), otherwise entered directly — it is the manufacturer’s unit for sprinkler and pivot systems. null: a duration will not be convertible into mm.

    • emitterFlowLph number nullable

      Flow rate of ONE emitter, in L/h. This is what is printed on the equipment.

    • emittersPerM2 number nullable

      Density of emitters per m². Nobody knows this figure off the top of their head: it follows from the spacings — 1 ÷ (emitter spacing × lateral spacing, in m), or (emitters per tree) ÷ (area per tree).

    • fractionWetted number

      Wetted soil fraction (fw, FAO-56 table 20), 0 < fw ≤ 1. Always filled in: the entered value, otherwise the system default. Not something to ask a farmer.

    • fractionWettedIsDefault boolean

      true = comes from the system default, never entered.

    • irrigatedAreaM2 number nullable

      Irrigated area in m². Required to convert a volume into mm.

    • validFrom string date-time

      Date this version TAKES EFFECT in the field.

    • validTo string date-time nullable

      Upper bound, EXCLUDED. null = current version.

    • setAt string date-time

      Date it was ENTERED, distinct from validFrom, which is the date it takes effect in the field.

    • notes string nullable
  • missingDoses object

    Recorded waterings whose dose could never be computed.

    Show 3 attributes Hide attributes
    • count integer
    • withoutInstallation integer

      The share of them that no recompute will ever be able to complete: no setup version covers their date. The useful move is then to declare a retroactive setup.

    • oldestWithoutInstallation string date-time nullable

Errors

  • 400

    Entry refused

    INVALID_SYSTEMINVALID_EMITTER_FLOWINVALID_EMITTER_DENSITYINVALID_FLOW_RATEINVALID_FRACTION_WETTEDINVALID_IRRIGATED_AREAINVALID_EFFECTIVE_FROMEFFECTIVE_FROM_IN_FUTUREINSTALLATION_VERSION_EXISTS_AT_DATEMODULE_NOT_OWNED
  • 401

    Not authenticated

  • 403

    Insufficient scope/role, or outside your company