Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Hiloop API key sent as an HTTP Bearer token.

Body

application/json

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.

run_id
string

The run (session) the annotation belongs to.

schema_name
string

The registered annotation-schema name the payload validates against (the event name).

range_start_ns
string

Inclusive start of the annotated window, in wall-clock nanoseconds. Mutually exclusive with the event-pair form.

range_end_ns
string

Inclusive end of the annotated window, in wall-clock nanoseconds. Mutually exclusive with the event-pair form.

payload_json
string

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.

range_start_event_id
string

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.

range_end_event_id
string

The event_id whose recorded timestamp ends the annotated window. Set together with range_start_event_id, and not alongside the nanosecond bounds.

event_id
string

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

event_id
string

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.