Admaxxer Pixel API — Overview

The Admaxxer Pixel API is a small, opinionated REST surface that exposes the same analytics data powering the in-app dashboards. Everything is scoped to a single workspace by API key — there are no account-wide superuser endpoints.

Base URL

https://admaxxer.com/api/v1/

What the API Does

Mint Tinybird JWTs for any of the 20 allowlisted analytics pipes (realtime visitors, funnels, retention, LLM traffic, geo, devices, and so on). Tokens are scoped to your workspace and expire in 120 seconds.
List your pixel websites, goals, alert rules, scheduled reports, and share links.
Look up a visitor profile by ID — useful for customer support tooling and CDP-style integrations.
Ingest events server-to-server from any backend (mobile apps, SSR commerce checkouts, job runners).
Identify visitors by attaching an external ID (hashed on the way in) to a pixel visitor ID.

What the API Deliberately Does Not Do (v1)

Create, update, or delete goals / alerts / reports / share links. These remain UI-only to keep the blast radius small.
Return raw visitor PII. Emails and phone numbers are SHA-256 hashed before storage.
Cross-workspace queries. An API key is always bound to exactly one workspace.

Quickstart (curl)

1. Create an API key in Settings › API Keys with the pixel:read scope. Copy the value — it is shown exactly once.

2. Verify the key works:

curl https://admaxxer.com/api/v1/me \
  -H 'Authorization: Bearer YOUR_KEY'

3. List your pixel websites:

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

4. Mint a Tinybird JWT for realtime visitors, then query Tinybird directly from the browser or a worker:

curl 'https://admaxxer.com/api/v1/pixel/metrics/p_realtime_visitors?website_id=admx_123' \
  -H 'Authorization: Bearer YOUR_KEY'
# → { "data": { "token": "eyJ...", "pipe": "p_realtime_visitors" }, ... }

5. Ship a server-to-server event (requires pixel:write):

curl -X POST https://admaxxer.com/api/v1/pixel/events \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"website_id":"admx_123","name":"pageview","path":"/pricing"}'

Design Notes

JWT-mint, then query. Rather than proxying every Tinybird query through our API, we mint a short-lived JWT and let the client query Tinybird directly. This keeps latency low and avoids doubling your egress costs.
Fixed params. Tokens have workspace_id and (optionally) website_id + visitor_id baked in as Tinybird fixed params. Clients cannot rewrite them on the wire.
No side-channel mutations. A compromised read key can only read; it cannot create, rename, delete, or change a goal.

Versioning & Stability

The API version lives in the path: /api/v1/. Breaking changes bump the major version. Additive, backwards-compatible changes (new fields, new endpoints) ship on v1. Deprecations are announced with at least 90 days of notice in the changelog and via the Deprecation response header.

OpenAPI

A hand-written OpenAPI 3.1 spec is maintained at server/openapi/pixel.yaml in the Admaxxer repository. We publish a copy at /api/v1/openapi.yaml so you can generate clients with your preferred tool (openapi-typescript, openapi-generator, Speakeasy, etc.).

Support

Email support@admaxxer.com with the request_id from the response meta block. Every response carries one.

Authentication · Endpoints · Errors · Rate Limits