Skip to content
docs

Create an annotation

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

An h-line of the humidity curve whose style.fill is threshold2 sets the wilting point and creates the matching alert (source: annotation), just as in the hub; threshold1 sets field capacity. Both feed GET /modules/{id}/agronomic-state. A threshold is set in vwc: in any other unit the request is refused (THRESHOLD_REQUIRES_VWC). unit only exists on the humidity and humidity-detail curves (INVALID_ANNOTATION_UNIT elsewhere). The key must have a user behind it: that user is the author.

Path parameters

  • id integer required

Headers

  • Idempotency-Key string

    Replays the same 2xx response (24 h)

Request body

  • chart_type string required

    Hub curve the annotation belongs to. humidity: the summary curve, weighted moisture — this is the one carrying the agronomic thresholds. humidity-detail: moisture per depth. humidity-heatmap: heat map. temperature: temperature. tensio: tensiometer probe (tension is still accepted on input).

    Values: humidityhumidity-detailhumidity-heatmaptemperaturetensio
  • type string required

    Shape of the drawing (see Annotation).

  • p1 array of any required

    A point of the curve, [instant, value]: the instant in milliseconds since 1 January 1970 UTC, the value in the annotation’s unit (unit; for moisture, % VWC by default).

  • p2 array of any

    A point of the curve, [instant, value]: the instant in milliseconds since 1 January 1970 UTC, the value in the annotation’s unit (unit; for moisture, % VWC by default).

  • unit string

    Unit of the points’ height, on the humidity and humidity-detail curves (see AnnotationUnit). Omitted: vwc.

    Values: vwcvwc_maxmm
    Default: vwc
  • content object

    Style and text: { style, text }.

  • style object

    Shorthand, merged into content.style.

  • text string

    Shorthand, merged into content.text.

Response

201

Annotation created

  • id string uuid always present
  • module_id integer always present
  • probe_id any nullable always present

    Deprecated: always null.

  • chart_type string always present

    Hub curve the annotation belongs to. humidity: the summary curve, weighted moisture — this is the one carrying the agronomic thresholds. humidity-detail: moisture per depth. humidity-heatmap: heat map. temperature: temperature. tensio: tensiometer probe (tension is still accepted on input).

    Values: humidityhumidity-detailhumidity-heatmaptemperaturetensio
  • type string always present

    Shape of the drawing, as the hub’s tools draw it: h-line (horizontal line), v-line (vertical), segment, ray (half-line), infinite (full line), arrow, h-free, rect (area), text. Older annotations carry line.

  • p1 array of any always present

    A point of the curve, [instant, value]: the instant in milliseconds since 1 January 1970 UTC, the value in the annotation’s unit (unit; for moisture, % VWC by default).

  • p2 array of any nullable always present

    Second point, for drawings that have two.

  • unit string nullable always present

    Unit of the points’ height (p1, p2), that is, the view of the curve the annotation belongs to: it is only shown in that unit. humidity and humidity-detail curves only: vwc — volumetric water content, %, the reference unit, the one used by the alert and the water status —, vwc_max — share of soil saturation, % —, mm. null on the other curves, which have a single unit.

    Values: vwcvwc_maxmmnull
  • content object always present

    Style and text of the drawing: { style, text }.

  • user_id string always present

    Author: userId of a member (GET /company/users).

  • created_at string date-time always present
  • updated_at string date-time always present
  • style object

    Copy of content.style, present when there is one.

  • text string

    Copy of content.text, present when there is one.

Errors

  • 400

    Entry refused

    invalid_idinvalid_bodyINVALID_ANNOTATION_UNITTHRESHOLD_REQUIRES_VWC
  • 401

    Not authenticated

  • 403

    Insufficient scope or role, resource outside your company, or key with no user

    insufficient_scopeinsufficient_roleforbidden_resourceno_user