HTTP API

horopter-ingress records events; horopter-egress serves what they describe. Both speak JSON over HTTP.

RoutesCopy Anchor Link

Each daemon also serves Prometheus metrics at /metrics, on a listener of its own; see Metrics.

CredentialsCopy Anchor Link

A credential is sent as Authorization: Bearer <key>. Which role grants which capability is Credentials and Capabilities.

A revocation reaches new requests within the credential cache's TTL, 30 seconds.

TenantsCopy Anchor Link

Ingress takes the tenant from the credential: a request body naming tenant is answered 400. Every egress route reads ?tenant=:

ErrorsCopy Anchor Link

Every error Horopter answers is a JSON object, {"error": "<message>"}. A read that fails is answered 500, and an append the store cannot take 503, with a generic message; the cause, which can name tables and the database host, goes to the daemon's log.

POST /v1/eventsCopy Anchor Link

Appends one event. The body is a JSON object, at most 1 MiB (413 above it):

tenant and source are refused with 400, whatever their value, null included: both come from the credential.

The Append ResponseCopy Anchor Link

201 for a new event, 200 for an idempotency key already stored. Both append routes answer the same four fields:

Do not send ref as the next correlation_ref: it is already prefixed with the credential's locus, and would be prefixed again. Ingress refuses that mistake with 400, naming what would have been stored: a correlation_ref whose first segment is the credential's own locus. HOROPTER_INGRESS_ALLOW_LOCUS_PREFIXED_REF=true lifts the check for every producer on that ingress; such a ref is then stored with the double prefix. A ref may otherwise contain / freely: myorg/repo#123 is stored as <locus>/myorg/repo#123.

Attribute SizeCopy Anchor Link

An event whose attributes encode to more than HOROPTER_INGRESS_MAX_EVENT_ATTRIBUTE_BYTES (default 4096) bytes of compact JSON, measured without HTML escaping, is refused with 400:

invalid event "01J8Z3Q4R5S6T7V8W9X0Y1Z2A3": attributes encode to 5120 bytes of JSON;
the limit is 4096 — keep attributes to identifiers and short text, and link to anything
larger

(one line, wrapped here). Events already stored are not checked again when the limit changes. What belongs in attributes is Attributes.

POST /v1/events/cloudeventsCopy Anchor Link

Appends one event from a CloudEvents 1.0 envelope in structured mode, with Content-Type: application/cloudevents+json. It answers as POST /v1/events does.

• id and source are required, and together are the idempotency key, so a redelivered envelope is deduplicated. The event's own source comes from the credential, not the envelope.
• time becomes occurred_at; without it, the time the envelope was received.
• type and subject are the event's.
• data, when present, must be a JSON object. Four keys in it are reserved, lifted into the event's own fields and removed from its attributes; every other key is kept as an attribute.

A reserved key holding anything but a string is left in the attributes, and the field is treated as absent. A data.tenant of any value, null included, is refused with 400.

Type Suffixes and the Lifecycle FieldCopy Anchor Link

Each event asserts whether its change starts, ends, or neither. An explicit lifecycle, the field or the data key, decides; without one, the type's final dot-separated segment does:

A type ending in anything else asserts nothing. lifecycle: "none" asserts nothing whatever the type ends in, so a type that happens to end .started can be recorded as a point.

POST /v1/admin/refoldCopy Anchor Link

Rebuilds one stored change from its events, with ingest running. The body is {"ref": "<locus>/<ref>"}; a global key adds "tenant": "<tenant id>". The answer names how many events were read and which fields of the stored change were repaired, [] when none were:

{"ref":"ci/dep-1","events":12,"altered":["end","status"]}

A ref with no events is answered 404. How and when to use it is Re-fold One Change.

GET /v1/changesCopy Anchor Link

The changes overlapping a window, oldest first.

It takes the filters too. The answer is {"changes": [...], "next": "..."}, each change an object of:

GET /v1/eventsCopy Anchor Link

A tenant's event log, for audit and export, oldest first.

The answer is {"events": [...], "next": "..."}, each event an object of id, tenant, idempotency_key, schema_version, source, type, subject, actor, title, occurred_at, received_at, correlation_ref, attributes, lifecycle, locus, origin (whether a human or a process appended it) and edited.

GET /adapters/grafana/annotationsCopy Anchor Link

The changes overlapping a window, as Grafana annotations: an array of objects with time, timeEnd, title, tags and text. text is the change's horopter.description attribute.

It takes the filters. ref is refused with 400: fetch one change with GET /v1/changes?ref=. Wiring it to Grafana is Show Changes on Your Grafana Dashboards.

GET /adapters/otlp/spansCopy Anchor Link

The changes overlapping a window, as OTLP/JSON trace data (resourceSpans), one span per change, carrying horopter.subject, horopter.ref and horopter.status among its attributes.

It takes the filters.

FiltersCopy Anchor Link

GET /v1/changes and both adapter routes take these, all optional, combined with AND. An empty value is no filter.

subject uses path.Match syntax, * within one /-separated segment, ? one character, [...] a class and \ an escape, plus {a,b} alternation: subject=*/{lastlight,logging}/*. Inside braces every comma separates alternatives, and \, does not escape one. A subject first seen after the change ended does not count. A malformed pattern, one that is not valid UTF-8, or a reversed range such as [9-0] is a 400.

Any other attr. key is a 400 naming the keys that are filterable, its value empty or not.

PagingCopy Anchor Link

Every read returns at most 1000 rows. GET /v1/changes and GET /v1/events page past that: while rows remain, the answer carries next, the next request with every parameter repeated and a cursor added, and the same URL in a Link: <...>; rel="next" header. Follow it until it is absent:

url="/v1/changes?from=$FROM&to=$TO"
while [ -n "$url" ]; do
  page="$(curl -s -H "Authorization: Bearer $KEY" "$EGRESS$url")"
  echo "$page" | jq -c '.changes[]'
  url="$(echo "$page" | jq -r '.next // empty')"
done

A cursor is bound to its query: sent with other filters or another window, it is a 400. limit may change between pages. Pages are not a snapshot: a change's start can move while you page, so a change can be missed or returned twice.

TruncationCopy Anchor Link

When rows were left out, the answer carries X-Horopter-Truncated: true; when none were, the header is absent. All four read routes set it, the adapters too, whose vendor-owned bodies have no room for a field. Rows are oldest first, so what is left out is the most recent. Narrow the window or filter, and ask again until the header is gone.

Read AdmissionCopy Anchor Link

Egress serves a read only when it has the capacity to: Read Admission.

GET /healthz and GET /readyzCopy Anchor Link

Both daemons answer them without a credential, and read admission never sheds them. /healthz answers 200 while the process runs and never touches the database; /readyz answers 200 when the database answers, and 503 when it does not.