Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Hiloop API key sent as an HTTP Bearer token.

Body

application/json

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).

run_id
string

The run (session) the annotation belongs to. Exactly one of run_id or project_id is set.

schema_name
string

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

target_event_id
string

The event_id of the single event this annotation is about. Only valid with run_id; empty annotates the run (or project) itself.

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.

project_id
string

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.

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.