Post v1telemetryannotations:range
Annotate a wall-clock range within a run. Mints one signal = "annotation" range event, validates
its payload against the named schema, and durably appends it; returns the minted event_id.
Authorizations
Hiloop API key sent as an HTTP Bearer token.
Body
A range annotation spanning a window within a run (rather than a single target event). The window is either a pair of wall-clock nanosecond bounds or a pair of event ids whose recorded timestamps become the bounds — supply exactly one form.
The run (session) the annotation belongs to.
The registered annotation-schema name the payload validates against (the event name).
Inclusive start of the annotated window, in wall-clock nanoseconds. Mutually exclusive with the event-pair form.
Inclusive end of the annotated window, in wall-clock nanoseconds. Mutually exclusive with the event-pair form.
The annotation payload as a JSON object string; validated against schema_name's registered
JSON Schema at ingest. Reserved hiloop.annotation.* keys are platform-owned and excluded.
The event_id whose recorded timestamp starts the annotated window. Both event endpoints must
exist in run_id; the window bounds are materialized from their timestamps. Set together with
range_end_event_id, and not alongside the nanosecond bounds.
The event_id whose recorded timestamp ends the annotated window. Set together with
range_start_event_id, and not alongside the nanosecond bounds.
Optional caller-minted event_id for the annotation event (a 26-character ULID). Supplying one
makes retries safe: re-sending the request with the same event_id returns the existing
annotation instead of writing a duplicate, so an ambiguous failure (a 5xx or a lost response)
can be retried blindly. The id names this logical annotation — never reuse it for different
content. Omitted, the server mints a fresh id per call and a retry writes a new annotation.
Response
OK
The stable event_id of the annotation event (the dedup/lookup key): the caller-minted id when
the request carried one, otherwise the freshly server-minted one.