Documentation

Install Headstream and use the API, MCP server and CLI.

• Getting started

  Set up Headstream in a few steps: create a project, add one script tag, confirm events arrive, set a goal and connect Stripe. You can also let an agent do it.

• Install the script

  Add Headstream's script to your site, route it through your own domain, pin a locked version, turn off heatmaps, and add session recordings. All the options.

• Track events

  Send custom events to Headstream with headstream.track, add properties, queue calls before the script loads, and use events in goals, funnels and A/B tests.

• Identify people

  Link browsers to people with headstream.identify or automatic form capture, so payments connect to visits across devices. Fields, matching rules and erasure.

• Self-reported attribution

  Collect "how did you hear about us?" answers through a form field, identify call, API or import, group them, and compare them with tracked first visits.

• Connect Stripe

  Connect Stripe with read-only access, import your history and link payments to people. Covers matching, visitor metadata and limits. This feature is in beta.

• Goals

  Create Headstream goals from a page path or custom event, using the dashboard, API or MCP. See how conversions and conversion rate are calculated, with limits.

• Reports and dashboards

  Run any Headstream report from the dashboard, API or MCP using a report spec, then save it to a dashboard. All report kinds, fields, and funnel rules are here.

• API

  Headstream's REST API reference: authentication, rate limits, errors, and every endpoint under /api/v1 with parameters, for reports, goals and more.

• MCP server

  Connect AI tools to Headstream through its MCP server at /api/mcp. Authentication, setup for Claude Code and Cursor, and the full list of tools by category.

• CLI

  Headstream's headstream command reads reports from your terminal as JSON. See every command, the flags it takes, and the matching REST API endpoints for each.

• Export your data

  Export every raw Headstream event as NDJSON from the dashboard or page through the API. Covers cursors, included fields, bots, and exporting revenue rows.