Agent API

What is the agent registration API?

A single unauthenticated endpoint that lets an AI agent register any website for analytics from code. Call it once to receive a tracking snippet, a site key, and a read-only MCP token scoped to that site. A human can claim the site later to attach it to their StoreMetrics account and unlock the full dashboard.

How do I register a site?

curl -s -X POST https://YOUR_STOREMETRICS_HOST/api/agent/register \
  -H "Content-Type: application/json" \
  -d '{"website_url":"https://example.com"}'

201 response:

{
  "ok": true,
  "site": {
    "key": "sm_abc123",
    "host": "example.com"
  },
  "snippet": "<script defer src=\"https://YOUR_STOREMETRICS_HOST/tracker.js\" data-velora-key=\"sm_abc123\" data-velora-site-id=\"sm_abc123\" data-velora-stack=\"unknown\"></script>",
  "tracking": {
    "status": "awaiting_first_event",
    "probation_days": 7
  },
  "mcp": {
    "endpoint": "https://YOUR_STOREMETRICS_HOST/api/mcp",
    "token": "mcp_xxxxxxxxxxxxxxxxxxxx",
    "scope": "this site only, read-only"
  },
  "claim": {
    "url": "https://YOUR_STOREMETRICS_HOST/claim/sm_abc123",
    "note": "Share with the site owner to attach this site to their account."
  },
  "next_steps": [
    "Paste the snippet before </head> on every public page.",
    "Deploy and fire a real page view.",
    "Call GET /api/mcp with the token to confirm data is flowing.",
    "Share the claim URL with the human owner to unlock the full dashboard and start the 20-day free trial."
  ]
}

What do I do with the response?

1. Copy the snippet string verbatim from the response. Do not edit attribute names or values.
2. Paste it before </head> in the global HTML template -- the file that wraps every public page (layout.tsx, _document.tsx, base.html, header.php, or equivalent for the stack).
3. Deploy the change and load any page on the site in a browser to fire the first event.
4. Present claim.url to the human owner. That URL lets them attach the site to their StoreMetrics account, start the 20-day free trial (no card), and access the full dashboard.

The snippet must appear on every public page, not just the homepage. One page view is enough to pass probation.

How do I read analytics with the returned token?

Use the mcp.token from the registration response as a bearer token against the MCP endpoint:

curl -s -X POST https://YOUR_STOREMETRICS_HOST/api/mcp \
  -H "Authorization: Bearer mcp_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_live","arguments":{"site_handle":"example.com"}}}'

The Accept: application/json, text/event-stream header is required. Without it the server returns 406.

Or add it to your agent's MCP config:

{
  "mcpServers": {
    "storemetrics": {
      "url": "https://YOUR_STOREMETRICS_HOST/api/mcp",
      "headers": {
        "Authorization": "Bearer mcp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Available tools with this token: list_sites (returns only this site), get_overview, get_live, get_pages, get_traffic_sources, get_geo, get_audience, get_funnel, get_site_context. Requests for any other site return a scope error, never data.

What are the limits?

Limit	Value
Probation period	7 days -- site is deleted if no event arrives
Rate limit	5 registrations per IP per day
Token scope	Read-only, this one site only
Unclaimed site	No dashboard, no owner account -- data still collects

What happens when the human claims?

The human opens claim.url, signs in (or creates a free account), and the site is attached to their StoreMetrics account. This starts the 20-day free trial with no card required. After trial, $19/month. All data collected before claiming is preserved -- nothing is re-counted or reset.

Prompt

Copy this prompt as-is into any coding agent. Replace YOUR_DOMAIN with the site you are working on.

Add StoreMetrics analytics to this project.

Step 1 -- Register the site:
Call POST https://storemetrics.pl/api/agent/register with body:
  {"website_url":"https://YOUR_DOMAIN"}

Step 2 -- Install the snippet:
Take the "snippet" string from the 201 response exactly as returned.
Paste it before </head> in the global layout file -- the file that wraps every public page.
Do not rename, modify, or invent any data-velora-* attributes.
If this is a Next.js App Router project, place it in app/layout.tsx using next/script with strategy="afterInteractive".

Step 3 -- Deploy:
Commit and deploy the change. Confirm the snippet appears in the live HTML:
  curl -s https://YOUR_DOMAIN | grep tracker.js

Step 4 -- Fire a first event:
Open https://YOUR_DOMAIN in a browser (or use curl -A "Mozilla/5.0" https://YOUR_DOMAIN) to fire the first page view and pass the 7-day probation check.

Step 5 -- Verify via MCP:
Using the "mcp.token" and "mcp.endpoint" from the registration response, call get_live:
  curl -s <mcp.endpoint> \
    -H "Authorization: Bearer <mcp.token>" \
    -H "Content-Type: application/json" \
    -d '{"method":"tools/call","params":{"name":"get_live","arguments":{"site_handle":"YOUR_DOMAIN"}}}'
Confirm at least one visitor appears in the response.

Step 6 -- Present the claim URL:
Show the human the "claim.url" from the registration response with this message:
"Your StoreMetrics tracking is live. Open this URL to attach the site to your account and start your free trial: <claim.url>"

Do not skip any step. Do not invent a site key -- always use the key from the registration response.