Admaxxer Pixel API — Endpoints

All endpoints are mounted under /api/v1/pixel/. The caller workspace is always derived from the API key; no request body or query parameter can override it.

GET /pixel/websites

Lists all non-deleted pixel websites in the workspace. Returns at most 1,000 rows (hard cap).

Scope: pixel:read

curl https://admaxxer.com/api/v1/pixel/websites -H 'Authorization: Bearer $KEY'

{ "data": [{ "id": "admx_…", "domain": "example.com", "name": "Main site", "createdAt": "2026-04-17T00:00:00Z" }], "meta": { "request_id": "req_…" } }

GET /pixel/metrics/{pipe}

Server-side proxy to the named analytics pipeline. Returns pipe rows directly — no JWT minting, no second our analytics warehouse hop. Allowed pipes include the live-visitors feed, the top-pages report, the referrers report, the locations report, the devices report, the technology report, the languages report, the traffic-sources report, the funnel report, the funnel report, the goal-conversions report, the attributed-revenue report, the retention-cohort report, the sessions report, the visitor-profile report, the visitor-timeline report, the AI-traffic report, the events catalog, the tracking-health check, the metric-series report.

Scope: pixel:read · Query: website_id (optional — checked against the API-key workspace, then applied to the report), from_date, to_date (optional date range), plus any of the filters below to narrow results.

Filtering results

Narrow any report to a slice of your traffic by adding one or more of these filters to the query string. Combine as many as you like — each one further narrows the result.

Match modes — every filter supports three:

• Equals (default): ?country=US. Multiple values with a comma: ?country=US,CA.
• Exclude: ?country=is_not:US.
• Contains (substring): ?utm_campaign=contains:summer.

curl 'https://admaxxer.com/api/v1/pixel/metrics/the top-pages report?website_id=admx_xxxx&country=US&utm_source=google&from_date=2026-01-01&to_date=2026-01-31' \
  -H 'Authorization: Bearer wk_xxxx'

Unsupported filters return a 400 — never a silent, unfiltered response. If you request a filter we don't apply, the API tells you exactly what to use instead, so you never get broader data than you asked for:

curl 'https://admaxxer.com/api/v1/pixel/metrics/the top-pages report?website_id=admx_xxxx&region=California' \
  -H 'Authorization: Bearer wk_xxxx'

{ "status": "error", "error": {
  "code": "unsupported_filter",
  "message": "region is not tracked at the pageview level. Filter by `country` instead.",
  "details": { "filter": "region", "supported": ["country","device","browser","os","referrer","page","utm_source","utm_medium","utm_campaign","utm_term","utm_content"] }
} }

curl 'https://admaxxer.com/api/v1/pixel/metrics/the top-pages report?website_id=admx_123&from=2026-04-01&to=2026-04-17' \
  -H 'Authorization: Bearer $KEY'

{
  "status": "success",
  "data": {
    "data": [{ "path": "/pricing", "visitors": 1245, ... }, ...],
    "meta": [{ "name": "path", "type": "String" }, ...],
    "rows": 50,
    "statistics": { "elapsed": 0.018, "rows_read": 15234, "bytes_read": 482912 },
    "data_status": "ok"
  },
  "meta": { "request_id": "req_..." }
}

Breaking change history: previous versions of this endpoint returned a short-lived our analytics warehouse JWT ({ token, pipe, workspace_id }) and expected the caller to query our analytics warehouse directly. The JWT signing secret was never registered with our analytics warehouse workspace, so every token was rejected with 401 — meaning no working integration ever existed against the old contract. URLs are unchanged; only the response body differs.

GET /pixel/goals

Lists configured conversion goals (name, selector, created_at).

Scope: pixel:read

GET /pixel/alerts

Lists anomaly detection rules (metric, threshold, channel).

Scope: pixel:read

GET /pixel/reports

Lists scheduled email/Slack reports (cadence, recipients, last_sent_at).

Scope: pixel:read

GET /pixel/share-links

Lists public dashboard share links (token prefix, expires_at, password-protected flag). Raw tokens are never returned.

Scope: pixel:read

GET /pixel/visitors/{id}

Server-side-proxied query against the visitor-profile report. Returns the visitor’s session count, first/last seen, country, device, LLM engine, and recent events. Same response envelope as /pixel/metrics/{pipe}. (Earlier versions minted a JWT — same rationale as /pixel/metrics/{pipe} applies.)

Scope: pixel:read

POST /pixel/events

Ingests a single event server-to-server. Routes to the correct analytics datasets based on name: pageview → pageviews, custom → your custom-goals store, payment → visitor_payments.

Scope: pixel:write

curl -X POST https://admaxxer.com/api/v1/pixel/events \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "website_id": "admx_123",
    "name": "payment",
    "visitor_id": "v_abc",
    "amount": 99.00,
    "currency": "USD"
  }'

The response contains the visitor_id Admaxxer attached (either the one you supplied or a fresh UUID if omitted).

POST /pixel/identify

Attaches an external identifier (email, user_id) to a pixel visitor. The external id is SHA-256 hashed before being written to our analytics warehouse, so raw PII never lands in the analytics store.

Scope: pixel:write

curl -X POST https://admaxxer.com/api/v1/pixel/identify \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "website_id": "admx_123",
    "visitor_id": "v_abc",
    "external_id": "jane@example.com",
    "traits": { "plan": "pro" }
  }'

Response Envelope

Every response (success or error) includes a meta object with a request_id for support triage:

{ "data": …, "meta": { "request_id": "req_abc123" } }

Related

Overview · Auth · Errors · Rate Limits