Send data

Events API

Send pageviews and events from your server, for things the browser can't see, like server-side payments or clients that don't run JavaScript.

Best for: Backend developers
Prerequisites: Your site ID and an API key from Integrations.

Endpoint

Send pageviews and events as JSON in a POST request.

Authenticate with your API key in the Authorization header, as Bearer followed by the key. Owners and admins can create keys under Integrations, then API keys. Keys are only shown once, so store yours securely.

HTTP

POST https://staging-script.pebbleanalytics.io/v1/events

Request body

type"page_view" or "event"Required: Pageview or event.
sitetextRequired: Your site ID, as in your snippet.
urltextRequired: URL of the page the visitor was on.
nametext: Event name. Required when type is event.
fieldsobject of text or numbers: Custom event properties. Can't contain personal data.
referrertext: Referrer URL, for pageviews.
visitor_iptextRequired: The visitor's IP address. Used to look up their country, then discarded.
user_agenttextRequired: The visitor's User-Agent. Used to filter bots and detect browser and device. Never stored in full.

Example request

Send a server-side payment as an event, forwarding the visitor's IP and User-Agent.

Shell

curl -X POST "https://staging-script.pebbleanalytics.io/v1/events" \
  -H "Authorization: Bearer YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event",
    "site": "YOUR-SITE-ID",
    "url": "https://fieldnotes.blog/checkout/done",
    "name": "payment confirmed",
    "fields": { "plan": "pro" },
    "visitor_ip": "203.0.113.24",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) AppleWebKit/605.1.15"
  }'

Responses

202Accepted: Received. Requests from bots are accepted but not counted.
400Bad Request: A required field is missing or invalid. The response names the field. Nothing is counted.
401Unauthorized: Missing or revoked API key. Nothing is counted.
403Forbidden: The key can't send data for this site, or the URL isn't on the site's domain. Nothing is counted.
404Not Found: No site with this ID. Nothing is counted.