Post v1telemetryannotations
Annotate a single target event in a run. Mints one signal = "annotation" 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
One annotation: run-scoped (optionally targeting a single event within the run) or project-scoped (no run — durable cross-run knowledge that outlives any sandbox).
The run (session) the annotation belongs to. Exactly one of run_id or project_id is set.
The registered annotation-schema name the payload validates against (the event name).
The event_id of the single event this annotation is about. Only valid with run_id; empty
annotates the run (or project) itself.
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 project a run-less annotation belongs to. Exactly one of run_id or project_id is set;
a project-scoped annotation carries no run lineage and no target event.
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.