API Reference Headless API

Headless API Reference

The HeadlessAnalytics API is the product surface. Use it to ingest events, generate trackables, query metrics and funnels, request agent-context summaries, read the GraphQL-compatible data surface, inspect usage, normalize connector records, govern consequential actions, export proof trails, and sync records to enterprise destinations. Every endpoint is designed for agents and enterprise systems first; dashboards are one optional client.

Authentication

Use a workspace API key in the `Authorization` header. Enterprise OIDC and SAML flows can also authorize scoped requests when `X-HA-Workspace-ID` is supplied.

Authorization	Bearer <API_KEY_OR_ENTERPRISE_JWT>
Content-Type	application/json
X-HA-Workspace-ID	Required for enterprise JWT access; not required for API keys.

Canonical Event Envelope

Use the same envelope across web, mobile, backend, agents, CLI, MCP, QR, RFID, sensors, robotics, and enterprise connectors. Consistent shape is what makes metrics, attribution, graph export, and proof trails work.

Field	Type	Use
event	string	Required event name, usually dot-notated by domain.
businessId	string	Optional business ID; defaults to the workspace default business.
actor	object\|string	The user, agent, system, robot, sensor, or workflow causing the event.
object	object\|string	The thing being acted on: order, product, campaign, lead, task, job, asset, etc.
entity	object	Optional graph entity to upsert from the event.
traceId	string	Correlation ID across events, agents, workflows, decisions, receipts, and proof trails.
source	object	Channel, campaign, medium, content, landing page, or platform metadata.
attribution	object	Touchpoint metadata for source, channel, campaign, revenue, and conversion analysis.
context	object	Context contract or runtime context metadata.
trackable	object	QR, barcode, RFID, sensor, robot, AI agent, MCP, or CLI identifier metadata.
decisionId	string	DecisionObject ID when the event is tied to governed execution.
proofId	string	Proof trail ID when the event is tied to evidence packaging.
outcome	object	Revenue influenced, risk reduced, hours saved, compliance verified, or similar outcome metrics.
trustTier	string	T0 raw, T1 observed, T2 attributed, T3 authority-bound, or T4 proof-ready.
complianceMapping	object	Control evidence metadata for SOC 2, ISO 27001, HIPAA, FedRAMP, EU AI Act, PCI DSS, or custom packs.
properties	object	Additional event-specific facts.
timestamp	number	Optional event timestamp in milliseconds since epoch.

GraphQL-Compatible Fields

`POST /api/graphql` accepts a GraphQL document and variables, then resolves supported root fields against the same bounded API and Convex queries used by SDK, CLI, MCP, and dashboards. It is intentionally dependency-light, agent-friendly, and optimized for flexible reads rather than replacing OpenAPI.

events	Recent event envelopes by workspace, business, event, or traceId.
trackingPlans	Persisted tracking plans for agent instrumentation.
metricDefinitions	Reusable metric definitions.
metrics	Metric values, event counts, and totals.
funnel	Step progression for conversion or workflow funnels.
attribution	Source, campaign, channel, and touchpoint counts.
businessHealth	Operating health, revenue, scans, leads, orders, and next actions.
agentPerformance	Agent run and event performance for a supplied agentId.
workflowStatus	Workflow run state for a supplied workflowId.
decisionObjects	Governance DecisionObjects.
enforcementReceipts	Full Hypervisor receipts by workspace or traceId.
proofTrails	Proof-ready evidence packets.

Agent query

{
  "query": "query Ops($limit:Int){ events(limit:$limit){ event timestamp } businessHealth { healthScore revenue nextActions } attribution { bySource byCampaign } }",
  "variables": { "limit": 100 }
}

POST/api/ingest

Ingest Event

Record a canonical event from a website, app, agent, workflow, QR scan, sensor, robot, connector, CLI, MCP server, or backend service.

Example

curl -X POST https://api.headlessanalytics.com/api/ingest \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "qr.bottle_scanned",
    "actor": { "type": "customer", "id": "anon_123" },
    "object": { "type": "product", "id": "olive-oil-500ml" },
    "source": { "channel": "qr", "campaign": "spring-launch" },
    "properties": { "sku": "olive-oil-500ml" }
  }'

POST/api/trackables

Create Trackable

Generate a tracked identifier for QR codes, barcodes, RFID tags, sensors, robots, AI agents, MCP servers, CLI workflows, or other physical/digital handles.

Example

curl -X POST https://api.headlessanalytics.com/api/trackables \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "qr_code",
    "name": "Olive Oil Bottle QR",
    "targetUrl": "https://roastandorigin.com/ethiopia",
    "eventName": "qr.bottle_scanned",
    "includeQrSvg": true
  }'

POST/api/metrics/query

Query Metrics

Query metric definitions, live event counts, and optionally persist materialized snapshots for reports and dashboards.

Example

curl -X POST https://api.headlessanalytics.com/api/metrics/query \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "order.created",
    "from": 1764547200000,
    "to": 1767225599000,
    "persistSnapshots": true
  }'

POST/api/graphql

GraphQL-Compatible Query

Query events, metrics, funnels, attribution, business health, governance receipts, and proof trails through one flexible headless endpoint.

Example

curl -X POST https://api.headlessanalytics.com/api/graphql \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Ops($limit:Int){ events(limit:$limit){ event timestamp } businessHealth { healthScore revenue nextActions } metrics { metrics totalEvents } }",
    "variables": { "limit": 100 }
  }'

POST/api/intelligence/agent-context

Agent Context

Return what changed, anomalies, missing proof events, and governed next actions in a format an AI agent can read and act on.

Example

curl -X POST https://api.headlessanalytics.com/api/intelligence/agent-context \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "recommend_next_actions",
    "businessId": "default",
    "limit": 250
  }'

POST/api/funnels/query

Query Funnel

Calculate step-by-step progression across conversion, fulfillment, workflow, agent, QR, or operational funnels.

Example

curl -X POST https://api.headlessanalytics.com/api/funnels/query \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      { "name": "Scan", "event": "qr.bottle_scanned" },
      { "name": "Product View", "event": "page.product_viewed" },
      { "name": "Order", "event": "order.created" }
    ]
  }'

GET/api/businesses/{id}/health

Business Health

Return an agent-readable operating summary for a business, including recent events, metrics, attribution, alerts, workflows, and recommendations.

Example

curl https://api.headlessanalytics.com/api/businesses/default/health?limit=100 \
  -H "Authorization: Bearer ha_live_..."

GET/api/usage

API Usage

Return API usage metering for billing, quotas, connector load, agent activity, and abuse review. This is also available through SDK, CLI, MCP, and the app Usage console.

Example

curl https://api.headlessanalytics.com/api/usage?limit=1000 \
  -H "Authorization: Bearer ha_live_..."

GET/api/health

Runtime Health

Check deployment readiness, required environment variables, production integration configuration, rate limiting, and usage metering without exposing secret values.

Example

curl https://api.headlessanalytics.com/api/health
curl https://api.headlessanalytics.com/api/health?strict=1

POST/api/connectors/ingest

Connector Ingestion

Normalize records from Shopify, Stripe, Salesforce, HubSpot, ads platforms, marketplaces, email, creator channels, field ops, QR/RFID/sensors/robotics, or generic enterprise systems.

Example

curl -X POST https://api.headlessanalytics.com/api/connectors/ingest \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "shopify",
    "records": [{ "id": "order_1", "total_price": 149, "currency": "USD" }]
  }'

POST/api/governance/enforce

Full Hypervisor Enforcement

Validate a proposed consequential action against DecisionObject state, AuthorityGrant, ContextContract, trust tier, compliance mapping, and attestation evidence.

Example

curl -X POST https://api.headlessanalytics.com/api/governance/enforce \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "decisionObjectId": "j57...",
    "authorityGrantId": "j58...",
    "contextContractId": "j59...",
    "proposedAction": {
      "action": "campaign.scale",
      "amount": 500,
      "currency": "USD"
    },
    "attestation": { "provider": "software_local" }
  }'

POST/api/proof-event-trails/export

Proof Trail Export

Create a SovereignProof-compatible packet from events, decisions, enforcement receipts, and additional evidence payloads.

Example

curl -X POST https://api.headlessanalytics.com/api/proof-event-trails/export \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Campaign scale proof",
    "receiptIds": ["j60..."],
    "pushToSovereignProof": true
  }'

POST/api/exports/destinations

Destination Export

Export recent events or supplied records to Snowflake, BigQuery, Redshift, S3, GCS, or a custom HTTPS destination with receipt tracking.

Example

curl -X POST https://api.headlessanalytics.com/api/exports/destinations \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "bigquery",
    "limit": 500,
    "config": {
      "projectId": "analytics-prod",
      "datasetId": "headlessanalytics",
      "tableId": "events"
    }
  }'

GET/api/openapi

OpenAPI

Return the machine-readable OpenAPI document for Zapier, Make, OpenAI tools, API gateways, and enterprise integration teams.

Example

curl https://api.headlessanalytics.com/api/openapi

API Reference Headless API

Headless API Reference

Authentication

Use a workspace API key in the `Authorization` header. Enterprise OIDC and SAML flows can also authorize scoped requests when `X-HA-Workspace-ID` is supplied.

Authorization	Bearer <API_KEY_OR_ENTERPRISE_JWT>
Content-Type	application/json
X-HA-Workspace-ID	Required for enterprise JWT access; not required for API keys.

Canonical Event Envelope

Field	Type	Use
event	string	Required event name, usually dot-notated by domain.
businessId	string	Optional business ID; defaults to the workspace default business.
actor	object\|string	The user, agent, system, robot, sensor, or workflow causing the event.
object	object\|string	The thing being acted on: order, product, campaign, lead, task, job, asset, etc.
entity	object	Optional graph entity to upsert from the event.
traceId	string	Correlation ID across events, agents, workflows, decisions, receipts, and proof trails.
source	object	Channel, campaign, medium, content, landing page, or platform metadata.
attribution	object	Touchpoint metadata for source, channel, campaign, revenue, and conversion analysis.
context	object	Context contract or runtime context metadata.
trackable	object	QR, barcode, RFID, sensor, robot, AI agent, MCP, or CLI identifier metadata.
decisionId	string	DecisionObject ID when the event is tied to governed execution.
proofId	string	Proof trail ID when the event is tied to evidence packaging.
outcome	object	Revenue influenced, risk reduced, hours saved, compliance verified, or similar outcome metrics.
trustTier	string	T0 raw, T1 observed, T2 attributed, T3 authority-bound, or T4 proof-ready.
complianceMapping	object	Control evidence metadata for SOC 2, ISO 27001, HIPAA, FedRAMP, EU AI Act, PCI DSS, or custom packs.
properties	object	Additional event-specific facts.
timestamp	number	Optional event timestamp in milliseconds since epoch.

GraphQL-Compatible Fields

events	Recent event envelopes by workspace, business, event, or traceId.
trackingPlans	Persisted tracking plans for agent instrumentation.
metricDefinitions	Reusable metric definitions.
metrics	Metric values, event counts, and totals.
funnel	Step progression for conversion or workflow funnels.
attribution	Source, campaign, channel, and touchpoint counts.
businessHealth	Operating health, revenue, scans, leads, orders, and next actions.
agentPerformance	Agent run and event performance for a supplied agentId.
workflowStatus	Workflow run state for a supplied workflowId.
decisionObjects	Governance DecisionObjects.
enforcementReceipts	Full Hypervisor receipts by workspace or traceId.
proofTrails	Proof-ready evidence packets.

Agent query

{
  "query": "query Ops($limit:Int){ events(limit:$limit){ event timestamp } businessHealth { healthScore revenue nextActions } attribution { bySource byCampaign } }",
  "variables": { "limit": 100 }
}

POST/api/ingest

Ingest Event

Record a canonical event from a website, app, agent, workflow, QR scan, sensor, robot, connector, CLI, MCP server, or backend service.

Example

curl -X POST https://api.headlessanalytics.com/api/ingest \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "qr.bottle_scanned",
    "actor": { "type": "customer", "id": "anon_123" },
    "object": { "type": "product", "id": "olive-oil-500ml" },
    "source": { "channel": "qr", "campaign": "spring-launch" },
    "properties": { "sku": "olive-oil-500ml" }
  }'

POST/api/trackables

Create Trackable

Generate a tracked identifier for QR codes, barcodes, RFID tags, sensors, robots, AI agents, MCP servers, CLI workflows, or other physical/digital handles.

Example

curl -X POST https://api.headlessanalytics.com/api/trackables \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "qr_code",
    "name": "Olive Oil Bottle QR",
    "targetUrl": "https://roastandorigin.com/ethiopia",
    "eventName": "qr.bottle_scanned",
    "includeQrSvg": true
  }'

POST/api/metrics/query

Query Metrics

Query metric definitions, live event counts, and optionally persist materialized snapshots for reports and dashboards.

Example

curl -X POST https://api.headlessanalytics.com/api/metrics/query \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "order.created",
    "from": 1764547200000,
    "to": 1767225599000,
    "persistSnapshots": true
  }'

POST/api/graphql

GraphQL-Compatible Query

Query events, metrics, funnels, attribution, business health, governance receipts, and proof trails through one flexible headless endpoint.

Example

curl -X POST https://api.headlessanalytics.com/api/graphql \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Ops($limit:Int){ events(limit:$limit){ event timestamp } businessHealth { healthScore revenue nextActions } metrics { metrics totalEvents } }",
    "variables": { "limit": 100 }
  }'

POST/api/intelligence/agent-context

Agent Context

Return what changed, anomalies, missing proof events, and governed next actions in a format an AI agent can read and act on.

Example

curl -X POST https://api.headlessanalytics.com/api/intelligence/agent-context \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "recommend_next_actions",
    "businessId": "default",
    "limit": 250
  }'

POST/api/funnels/query

Query Funnel

Calculate step-by-step progression across conversion, fulfillment, workflow, agent, QR, or operational funnels.

Example

curl -X POST https://api.headlessanalytics.com/api/funnels/query \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      { "name": "Scan", "event": "qr.bottle_scanned" },
      { "name": "Product View", "event": "page.product_viewed" },
      { "name": "Order", "event": "order.created" }
    ]
  }'

GET/api/businesses/{id}/health

Business Health

Return an agent-readable operating summary for a business, including recent events, metrics, attribution, alerts, workflows, and recommendations.

Example

curl https://api.headlessanalytics.com/api/businesses/default/health?limit=100 \
  -H "Authorization: Bearer ha_live_..."

GET/api/usage

API Usage

Return API usage metering for billing, quotas, connector load, agent activity, and abuse review. This is also available through SDK, CLI, MCP, and the app Usage console.

Example

curl https://api.headlessanalytics.com/api/usage?limit=1000 \
  -H "Authorization: Bearer ha_live_..."

GET/api/health

Runtime Health

Check deployment readiness, required environment variables, production integration configuration, rate limiting, and usage metering without exposing secret values.

Example

curl https://api.headlessanalytics.com/api/health
curl https://api.headlessanalytics.com/api/health?strict=1

POST/api/connectors/ingest

Connector Ingestion

Normalize records from Shopify, Stripe, Salesforce, HubSpot, ads platforms, marketplaces, email, creator channels, field ops, QR/RFID/sensors/robotics, or generic enterprise systems.

Example

curl -X POST https://api.headlessanalytics.com/api/connectors/ingest \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "shopify",
    "records": [{ "id": "order_1", "total_price": 149, "currency": "USD" }]
  }'

POST/api/governance/enforce

Full Hypervisor Enforcement

Validate a proposed consequential action against DecisionObject state, AuthorityGrant, ContextContract, trust tier, compliance mapping, and attestation evidence.

Example

curl -X POST https://api.headlessanalytics.com/api/governance/enforce \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "decisionObjectId": "j57...",
    "authorityGrantId": "j58...",
    "contextContractId": "j59...",
    "proposedAction": {
      "action": "campaign.scale",
      "amount": 500,
      "currency": "USD"
    },
    "attestation": { "provider": "software_local" }
  }'

POST/api/proof-event-trails/export

Proof Trail Export

Create a SovereignProof-compatible packet from events, decisions, enforcement receipts, and additional evidence payloads.

Example

curl -X POST https://api.headlessanalytics.com/api/proof-event-trails/export \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Campaign scale proof",
    "receiptIds": ["j60..."],
    "pushToSovereignProof": true
  }'

POST/api/exports/destinations

Destination Export

Export recent events or supplied records to Snowflake, BigQuery, Redshift, S3, GCS, or a custom HTTPS destination with receipt tracking.

Example

curl -X POST https://api.headlessanalytics.com/api/exports/destinations \
  -H "Authorization: Bearer ha_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "bigquery",
    "limit": 500,
    "config": {
      "projectId": "analytics-prod",
      "datasetId": "headlessanalytics",
      "tableId": "events"
    }
  }'

GET/api/openapi

OpenAPI

Return the machine-readable OpenAPI document for Zapier, Make, OpenAI tools, API gateways, and enterprise integration teams.

Example

curl https://api.headlessanalytics.com/api/openapi