All endpoints return JSON. Authentication uses Bearer tokens where required. The agent signup endpoint requires no auth — it's designed to be called by anyone, including AI agents.
Create a new tracking site. No authentication required. Returns credentials and a ready-to-use tracking snippet. Call this from agents, scripts, CI pipelines, or a browser.
All fields optional. Send an empty POST to get started immediately.
| Field | Type | Description |
|---|---|---|
| site_url | string | URL of the site to track (e.g. "https://myproject.com"). Optional. |
| site_name | string | Display name (e.g. "My Blog"). Optional. |
| string | Email for account recovery. Optional — not required to sign up. | |
| requested_verification_method | string | "meta", "file", or "dns". Defaults to "meta". |
| agent_name | string | Identifier for the agent or script creating this site. Optional. |
{
"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...\">"
}
| Field | Description |
|---|---|
| site_id | Numeric ID for this site. |
| site_code | Short slug for this site — used in your dashboard URL and tracking snippet. |
| count_api_token | Write-only token for sending events. Safe to embed in frontend code. |
| owner_secret | Full admin secret (prefix: mh_). Shown once — store it now. Never expose in frontend code. |
| recovery_codes | 8 one-time recovery codes — shown once. Store securely. |
| dashboard_url | Direct link to your stats dashboard. |
| embed_snippet | Ready-to-paste HTML script tag for your site. |
| verification_token / verification_instructions | Token and step-by-step instructions to verify site ownership. |
curl -X POST https://api.magnethits.com/api/v1/agent/signup \
-H "Content-Type: application/json" \
-d '{"site_url": "https://myproject.com", "site_name": "My Project"}'
const res = await fetch('https://api.magnethits.com/api/v1/agent/signup', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ site_url: 'https://myproject.com', site_name: 'My Project' })
});
const { site_id, site_code, count_api_token, owner_secret, embed_snippet } = await res.json();
import requests
res = requests.post(
"https://api.magnethits.com/api/v1/agent/signup",
json={"site_url": "https://myproject.com", "site_name": "My Project"}
)
data = res.json()
# data["site_id"], data["embed_snippet"], data["count_api_token"]
Record a page view or custom event. Used by the JavaScript snippet automatically. Can also be called server-side.
| Parameter | Required | Description |
|---|---|---|
| p | required | Page path or event name (e.g. /home, signup) |
| t | Page title | |
| r | Referrer URL | |
| q | Query string |
Auth: Authorization: Bearer <count_api_token> — or the JavaScript snippet handles this automatically via data-magnethits.
curl "https://collect.magnethits.com/count?s=YOUR_SITE_CODE&p=/home&t=Home+Page" \ -H "Authorization: Bearer YOUR_COUNT_API_TOKEN"
Retrieve hit stats. Requires your owner_secret (stats permission). Auth header: Authorization: Bearer mh_YOUR_OWNER_SECRET.
| Parameter | In | Description |
|---|---|---|
| start | query | Start date — 2006-01-02 |
| end | query | End date — 2006-01-02 |
curl "https://app.magnethits.com/api/v0/stats/hits?start=2026-03-01&end=2026-03-20" \ -H "Authorization: Bearer mh_YOUR_OWNER_SECRET"
application/json