The API surface

Design rules

• Versioned paths — a breaking change to a shape is a new version, not a surprise
• Metric reads go through the semantic layer, never raw SQL against the store
• Every write that carries value requires an idempotency key
• Responses carry the metric definition, period and segment they used, so a number is never returned without its meaning

Endpoints

The top-level collections.

POST   /v1/events                    send a business event
POST   /v1/events/batch              send many, one idempotency key each
GET    /v1/sites                     connected sites and their configuration
GET    /v1/metrics                   the semantic metric catalogue
POST   /v1/query                     a governed metric query
GET    /v1/insights                  detected changes, newest first
GET    /v1/insights/:id/evidence     the evidence behind one insight
GET    /v1/reports/:id               a generated briefing
POST   /v1/annotations               deployments, campaigns, business events
GET    /v1/exports/:id               a prepared export
POST   /v1/webhooks                  subscribe to insight and report events

A metric query

Metrics and dimensions are named, not expressed. That is the constraint that makes the result trustworthy and the AI safe to point at it.

POST /v1/query

{
  "site_id":    "site_123",
  "metrics":    ["conversion_rate", "revenue", "revenue_per_visit"],
  "dimensions": ["channel"],
  "period":     { "from": "2026-09-01", "to": "2026-09-21" },
  "compare_to": "previous_period",
  "filters":    { "traffic_type": "human" },
  "order_by":   "revenue",
  "limit":      10
}

Webhook events

• insight.created — an anomaly or opportunity was detected and decomposed
• report.generated — a scheduled briefing is ready
• anomaly.resolved — a detected change returned to its normal range
• sync.completed — a connected system finished importing
• Every delivery is signed and carries an event ID, so a consumer can verify it and deduplicate

Authentication

• Site-scoped API keys with least-privilege roles
• A read-only role is a first-class option, not a permission you have to remove
• Event ingestion keys are separate from query keys — the service sending conversions has no reason to read your revenue reports
• Every call is recorded with its actor