Collector reference

Base URL: https://analytics.bitgate.dev. OpenAPI document | Install the tracker

TypeScript examples run server-side in Node 20+: save a snippet as example.mts, set any referenced environment variables, then run npx tsx example.mts.

Routes

/events and /append are the same ingestion handler. Both default to type: "pageview"; the route name does not choose a row type. Set type: "event" for events and type: "append" for duration or scroll updates. There is no batch-array API.

Send JSON

The examples use a placeholder hostname. Replace it with your registered hostname; never use the public demo as a write target.

curl --fail-with-body --silent --show-error --max-time 20 \
  -X POST https://analytics.bitgate.dev/events \
  -H 'Content-Type: application/json' \
  --data '{"hostname":"your-domain.example","type":"event","event":"signup","metadata":{"plan":"pro"}}'

const hostname = process.env.EA_HOSTNAME;
if (!hostname) throw new Error("Set EA_HOSTNAME to your registered hostname");

const response = await fetch("https://analytics.bitgate.dev/events", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    hostname,
    type: "event",
    event: "signup",
    metadata: { plan: "pro" },
  }),
  signal: AbortSignal.timeout(20_000),
});
if (!response.ok) {
  throw new Error(`Collector ${response.status}: ${await response.text()}`);
}
console.log(await response.text());

A successful JSON request returns 200 with the literal body ok, not JSON. Send JSON text: application/json is recommended, and JSON sent as text/plain by sendBeacon is also accepted; the handler does not enforce Content-Type. Curl's default user agent is classified as a bot, so a curl test can succeed without appearing in reports. Server-side visitor attribution uses the sending request's IP and effective user agent, not an end user's identity supplied in JSON.

Append duration and scroll

Appends create additional rows; they do not update an existing pageview. Use the original pageview's id or page_id as original_id for correlation. The collector does not require that ID or check that a matching pageview exists.

curl --fail-with-body --silent --show-error --max-time 20 \
  -X POST https://analytics.bitgate.dev/append \
  -H 'Content-Type: application/json' \
  --data '{"hostname":"your-domain.example","type":"append","original_id":"pageview-id","duration":42,"scrolled":75}'

Duration is in seconds and scroll is a percentage. Appends are counted in their own ingestion-time range, not the original pageview's time. Overview averages are calculated per append row, not per pageview.

Payload fields

The same fields work as query parameters on the pixels and as properties of the single JSON body on either POST route. Query values are strings. In JSON, scalar strings, numbers and booleans are converted to strings before most field processing; use the types below for predictable results. Unrecognized fields are ignored.

Text limits below are truncation limits, not validation errors. Missing optional text defaults to an empty string unless noted. Numeric measurements are rounded to the nearest integer and clamped to the stated maximum; missing, non-finite or non-positive values become zero.

Required and routing fields

IDs and measurements

IDs do not provide deduplication or idempotency. Reusing an ID can create another row.

Client context

Flags

Flags are true for boolean true, number 1, string "true" or string "1"; other values are false. Defaults are false except https, which defaults to true when absent.

Campaign fields

For each field, a non-empty UTM value parsed from query takes precedence over the explicit top-level value. Other query parameters are stored within query but do not create report dimensions.

Server-derived fields

Row timestamps are assigned during ingestion. Country comes from the incoming request's network context. Visitor identifiers are derived from the UTC day, site, incoming IP and effective user agent, and rotate daily. Payload fields such as timestamp, ts, ip, country and visitor_id do not override them. The tracker's time cache-buster and sri field are also ignored by the collector.

Pixels and script

Pageview pixel

GET /simple.gif reads the payload fields from its query string. A valid request returns a 1×1 GIF, including for event, append or error types. An invalid payload returns a text error instead of an image.

curl --fail-with-body --silent --show-error --max-time 20 \
  --get https://analytics.bitgate.dev/simple.gif \
  --data-urlencode 'hostname=your-domain.example' \
  --data-urlencode 'type=pageview' \
  --data-urlencode 'path=/pricing' \
  --output /dev/null

For metadata on a pixel, send a URL-encoded JSON string rather than an object. A GET pixel is a collection request, not a read-only stats request.

No-JavaScript pixel

GET /noscript.gif has the same payload format and GIF response. When absent from the query, hostname, path, https and query are derived from the page URL in the Referer header. Explicit parameters take precedence, even when empty. type defaults to pageview.

The incoming Referer is the page being tracked, not that page's acquisition referrer. The collector does not infer the acquisition referrer field from it. Browser referrer policies may omit the header or reduce it to an origin; then the hostname must be supplied explicitly or the path may become /.

Browser script

GET /latest.js serves JavaScript with Cache-Control: public, max-age=86400, stale-while-revalidate=604800. Install it with the configuration described in Installation and use Events for browser event calls. Fetching the script itself does not record a pageview.

Receipt and filtering

A collector 200 acknowledges the handler's response, not a durable insert. Storage runs in the background; a later storage failure is not returned to the caller. Normally, unregistered hostnames are discarded. Registration lookup failures can bypass that check, so it is not an authorization boundary. Site caching can delay registration changes.

There is no idempotency guarantee. Do not automatically retry event or append requests after an ambiguous network failure: the first request may already have been processed. Inspect the response and reports separately when validating an integration.

If DNT: 1 or X-Do-Not-Track: 1 is present, collection is skipped and the normal success response is returned, unless collect-dnt is true. This check occurs before payload-field validation; POST bodies must still parse as JSON. The browser script also checks browser Do Not Track before sending.

Bot rows can be stored but are excluded from reports. Detection checks the bot flag and user-agent matches for bot, spider, crawl, monit, curl, wget, python-requests, node-fetch, axios or headless, case-insensitively.

Responses and CORS

An array is not processed as a batch: it ordinarily reaches hostname validation and returns hostname is required. Collector errors are plain text, not the product API's JSON error envelope. Pixel responses use image/gif and Cache-Control: no-store, no-cache, must-revalidate; JSON ingestion responses use text/plain; charset=utf-8 and Cache-Control: no-store.

Collector responses and OPTIONS preflights provide Access-Control-Allow-Origin: *, methods GET, POST, OPTIONS, allowed headers Content-Type, and a preflight max age of 86400 seconds. They do not allow credentials or arbitrary custom request headers. This does not enable cross-origin reads of /api/*.

GET /healthz returns ok without checking storage or database readiness, and its response has no collector CORS headers. Use it to check that the HTTP handler responds, not that events have been stored.