HeadlessAnalytics Documentation

Operating Intelligence Model

A normal analytics platform asks what happened. HeadlessAnalytics asks what happened, what it changed in the operating graph, what an agent should know next, whether a recommendation is consequential, and what proof should be generated.

Full glossary with all terms →

Quickstart

Use the API directly, or configure the SDK, CLI, and MCP server around the same API key. The dashboard is useful for setup and operations, but it is not required for daily execution.

curl -X POST https://api.headlessanalytics.com/api/ingest \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "qr.bottle_scanned",
    "businessId": "default",
    "traceId": "trace_spring_launch",
    "actor": { "type": "customer", "id": "anon_123" },
    "object": { "type": "product", "id": "olive-oil-500ml" },
    "source": { "channel": "qr", "campaign": "spring-launch" },
    "attribution": { "source": "qr", "campaign": "spring-launch" },
    "trackable": { "kind": "qr_code", "code": "ethiopia-bag-001" },
    "context": { "surface": "bag", "region": "northeast" },
    "properties": { "sku": "olive-oil-500ml", "lot": "L2026-04" },
    "trustTier": "T2"
  }'

This is the HA public dialect. The ROIzilla canonical shape uses id, type, organization_id, workspace_id, and schema_version fields internally.

End-to-End Flow

A DTC brand ships 10,000 bags of single-origin coffee, each with a QR code. Their growth agent provisions the tracking plan, generates identifiers, and begins operating. No dashboard. No manual setup. The agent seeds, tracks, queries, decides, enforces, and exports — entirely headlessly.

ha tracking-plan-create '{"name":"Roast & Origin","vertical":"dtc_commerce_ops"}'
ha create-trackable qr_code "Ethiopia Single-Origin Bag" https://roastandorigin.com/ethiopia
ha use ethiopia-bag-001 qr_scan '{"sku":"ETH-250G","lot":"L2026-04","campaign":"spring-launch"}'
ha track order.created '{"revenue":22,"source":"bag_qr","campaign":"spring-launch"}'
ha agent-context recommend_next_actions '{"businessId":"default","limit":250}'
ha graphql 'query Ops { businessHealth { healthScore revenue nextActions } attribution { bySource byCampaign } }'
ha decision-create campaign.scale '{"status":"approved","risk":"medium"}'
ha enforce '{"action":"campaign.scale","amount":500,"currency":"USD"}' '{"decisionObjectId":"..."}'
ha proof-export '{"title":"Campaign scale proof","receiptIds":["..."]}'

What To Track

Track every event that changes state, creates context, influences revenue, modifies risk, or helps an agent decide what should happen next.

QR Codes, Barcodes, RFID, Sensors, And Robotics

Trackables let enterprises generate and observe identifiers that exist outside your website. A QR code on a bottle, an RFID tag in a warehouse, a barcode on packaging, a sensor ping, a robot action, and an MCP tool call can all become first-class events in the same operating graph.

ha create-trackable qr_code "Single-Origin Coffee Bag" https://roastandorigin.com/ethiopia
ha use ethiopia-bag-001 qr_scan '{"sku":"ETH-250G","lot":"L2026-04"}'
ha metric-query '{"eventName":"qr.bag_scanned","limit":500}'

MCP For Agentic Work

The MCP server gives agents governed tools for tracking, querying metrics, reading business health, getting agent context, querying GraphQL, checking usage, recommending actions, creating decisions, enforcing actions, and exporting proof trails.

{
  "mcpServers": {
    "headlessanalytics": {
      "command": "npx",
      "args": ["-y", "@headlessanalytics/mcp"],
      "env": {
        "HA_API_KEY": "ha_live_...",
        "HA_API_URL": "https://api.headlessanalytics.com"
      }
    }
  }
}

CLI

The CLI is built for operators, CI jobs, local scripts, and agent shells. It can generate trackables, query intelligence, process alerts, pull connectors, enforce actions, and export packets.

ha health default
ha usage
ha agent-context recommend_next_actions '{"limit":250}'
ha graphql 'query Ops { businessHealth { healthScore revenue nextActions } }'
ha funnel-query '[{"name":"Scan","event":"qr.bottle_scanned"},{"name":"Order","event":"order.created"}]'
ha decision-create campaign.scale '{"status":"approved","risk":"medium"}'
ha enforce '{"action":"campaign.scale","amount":500}' '{"decisionObjectId":"..."}'
ha destination-export bigquery '{"limit":500,"config":{"projectId":"analytics-prod","datasetId":"ha","tableId":"events"}}'

SDKs And Agent Frameworks

First-party clients are available for TypeScript/JavaScript, Python, Go, and Ruby. The TypeScript SDK also exposes OpenAI tool schemas and dependency-free LangChain, LlamaIndex, and AutoGPT hooks.

const ha = new HeadlessAnalytics({ writeKey: process.env.HA_API_KEY! });
await ha.track("order.created", { properties: { revenue: 149 } });
const health = await ha.getBusinessHealth("default");
const usage = await ha.getApiUsage();
const tools = ha.openAITools();
const callbacks = [ha.langChainCallbackHandler({ agentId: "growth-agent" })];

Enterprise Connectors

Connector ingestion normalizes external records into events, entities, attribution, sync records, and health state. Supported providers include Salesforce, HubSpot, Shopify, Stripe, Amazon, Walmart, QuickBooks, Xero, NetSuite, Google Ads, Meta Ads, GA4, Resend, YouTube, Twitch, Discord, TikTok, Roblox, Fortnite, ServiceNow, Jira, Asana, Linear, Procore, ServiceTitan, Fieldwire, QR.io, RFID, sensors, robotics, and generic records.

Full Hypervisor Governance

Analytics can recommend actions, but consequential execution should route through governance. The enforcement flow validates API access, DecisionObject state, authority grants, context contracts, trust tier, compliance mapping, and attestation evidence before returning `allow`, `deny`, `escrow`, or `needs_human_approval`.

Exports And Destinations

Export bounded operating graphs, proof trails, or event batches to GraphNative, SovereignProof, Snowflake, BigQuery, Redshift, S3, GCS, or custom HTTPS endpoints. Every external push records a receipt with destination, status, request ID, response status, external ID, error, and payload hash.

Acceptance Stories

Endpoint Map

The machine-readable OpenAPI document is available at GET /api/openapi.