Documentation

Getting started

MagnetHits is analytics designed for minimal friction — whether you're a developer adding a script tag, or an AI agent spinning up tracking as part of a larger workflow. This guide covers both paths.

Quick start (agent path)

Send one POST request. Get back everything you need to start tracking:

bash 
curl -X POST https://api.magnethits.com/api/v1/agent/signup

Response:

json 
{
  "site_id":               1,
  "site_code":             "myproject",
  "count_api_token":       "abc123xyz...",
  "owner_secret":          "mh_sEcReT...",
  "recovery_codes":        ["xxxx-xxxx-xx", "..."],
  "dashboard_url":         "https://myproject.magnethits.com",
  "embed_snippet":         "<script data-magnethits=\"myproject\" async src=\"//cdn.magnethits.com/track.js\"></script>",
  "verification_method":   "meta",
  "verification_token":    "mhv-abc123...",
  "verification_instructions": "Add to <head>: <meta name=\"magnethits-verification\" content=\"mhv-abc123...\">"
}

That's it. Paste the embed_snippet into your HTML and traffic appears on your dashboard.

Agent signup endpoint

POST /api/v1/agent/signup is designed to be called without any authentication — by an agent, a script, or a human with curl. It creates a new site and returns credentials.

Optional request body (all fields optional):

json 
{
  "site_url":                    "https://example.com",  // optional
  "site_name":                   "My Project",           // optional
  "email":                       "[email protected]",      // optional — for recovery
  "requested_verification_method": "meta",               // "meta", "file", or "dns"
  "agent_name":                  "my-deploy-bot"         // optional
}

The endpoint is idempotent-safe: retrying with the same parameters will not create duplicate sites.

Install — Script tag

The fastest way to add tracking to any HTML page:

html 
<script
  data-magnethits="YOUR_SITE_CODE"
  async
  src="//cdn.magnethits.com/track.js">
</script>

Place this anywhere in your <body> — typically just before </body>. Replace YOUR_SITE_CODE with the site_code from signup.

Install — Backend API

Send page view events server-side, without any JavaScript on the page:

bash 
curl "https://collect.magnethits.com/count?s=YOUR_SITE_CODE&p=/my-page" \
  -H "Authorization: Bearer YOUR_COUNT_API_TOKEN"

Use your count_api_token for this. The count_api_token is safe to embed in frontend code — it can only send events, not read data.

Install — Static site (Hugo, Jekyll, etc.)

Add a partial or include that outputs the script tag. Example for Hugo:

html (layouts/partials/analytics.html) 
{{ if not .Site.IsServer }}
<script
  data-magnethits="{{ .Site.Params.magnethits_id }}"
  async
  src="//cdn.magnethits.com/track.js">
</script>
{{ end }}

Tokens

MagnetHits uses two distinct tokens per site:

count_api_token

Used to send page view events. Safe to expose in frontend JavaScript or embed in public scripts. Cannot read dashboard data.

owner_secret

Full admin access: read stats, update site settings, manage the site. Keep this secret. Store in environment variables, never in frontend code.

Verification

Verify that you control a domain before it shows on your dashboard. Two methods:

HTML file method

Upload a plain text file at your web root. The path and content are returned in verification_instructions from signup.

text 
# Upload to: https://example.com/magnethits-verify-mhv-abc123.txt
# Content of the file (the token itself):
mhv-abc123...

Meta tag method

Add a meta tag to the <head> of your site using the verification_token from signup:

html 
<meta name="magnethits-verification" content="mhv-YOUR_TOKEN" />

Then trigger the check: POST /api/v1/sites/{id}/verify/check with your owner_secret as Bearer token.

Examples — curl

bash 
# Create a site
curl -X POST https://api.magnethits.com/api/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"site_name": "My Site"}'

# Send a page view
curl "https://collect.magnethits.com/count?s=YOUR_SITE_CODE&p=/home" \
  -H "Authorization: Bearer YOUR_COUNT_API_TOKEN"

Examples — Node.js

javascript 
// Create a site
const res = await fetch('https://api.magnethits.com/api/v1/agent/signup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ site_name: 'My Site' })
});

const { site_id, site_code, count_api_token, embed_snippet } = await res.json();

// Track a page view server-side
await fetch(
  `https://collect.magnethits.com/count?s=YOUR_SITE_CODE&p=/home`,
  { headers: { Authorization: `Bearer ${count_api_token}` } }
);

Examples — Python

python 
import requests

# Create a site
res = requests.post(
    "https://api.magnethits.com/api/v1/agent/signup",
    json={"site_name": "My Site"}
)
data = res.json()

site_id     = data["site_id"]
count_api_token = data["count_api_token"]
snippet     = data["embed_snippet"]

# Track a page view server-side
requests.get(
    "https://collect.magnethits.com/count",
    params={"p": "/home"},
    headers={"Authorization": f"Bearer {count_api_token}"}
)
API reference → Open dashboard →