Vantrex: deploy from git to a global edge

Base address and authentication

The service is at https://api.analytics.vantrex.cloud and every path starts with /v1. Responses are JSON.

For	Authenticate with
Sending events	A project key in `Authorization: Bearer vtxa_sk_…`. A publishable key may also go in the request body as `key`, which is how browsers send beacons. A secret key is refused in a body.
Managing projects and reading data	A Vantrex access token with the `analytics` scope, as `Authorization: Bearer vtx_…`. Create one under Account, Tokens.

Sending events

POST /v1/collect

Sends one event, or up to 100 in events, with a body of at most 64 KB.

curl https://api.analytics.vantrex.cloud/v1/collect \
  -H "Authorization: Bearer $VANTREX_ANALYTICS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "login",
    "status": "ok",
    "user_id": "u_123",
    "email": "ann@example.com",
    "ip": "203.0.113.9",
    "user_agent": "Mozilla/5.0 …",
    "duration_ms": 240
  }'

Field	Meaning
`type`	`login`, `signup`, `click`, `identify` or `heartbeat`.
`status`	`ok` (default) or `error`.
`error_code`	Why it failed, up to 64 characters.
`user_id`, `name`, `email`	The person. Only the fields the project collects are stored.
`visitor_id`	Links the person to the browser tab they have open (the `vtxa_vid` cookie).
`ip`, `user_agent`	The end user's address and browser, when you send from a server. Used for country, browser and device; the address is not stored.
`duration_ms`	How long the attempt took.
`ts`	When it happened, RFC 3339, up to 7 days in the past. Secret key only.
`deployment_id`	Which deployment was running, for linked projects.
`props`	Extra values: at most 20 keys and 2 KB.

The answer is 202 with {"accepted": n}. A publishable key can send only click and heartbeat; login, signup and identify need the secret key.

POST /v1/heartbeat

Says a visitor is on a page: {"visitor_id": "…", "path": "/pricing"}, or with "end": true when they leave. Answers 204. A visitor counts as online for two minutes after their last heartbeat.

POST /v1/identify

Secret key only. Sends user_id, optional name and email, and the visitor_id to attach them to. Answers 204.

Reading data

These need an access token with the analytics scope (read for reads, write for changes). Another account's projects answer 404.

Request	Returns
`GET /v1/projects`	Your analytics projects, with how many people are online now.
`POST /v1/projects`	Creates one from `name`, `url`, optional `collect_fields`, `allowed_origins` and `deploy_project_id`. The reply includes the `secret_key`, once.
`GET /v1/projects/{id}`	One project.
`PATCH /v1/projects/{id}`	Changes its name, address, collected fields, allowed origins or deploy link.
`DELETE /v1/projects/{id}`	Deletes it and its events.
`POST /v1/projects/{id}/keys/rotate`	Creates a new secret key; the old one works for 10 more minutes.
`GET /v1/stats/logins`, `/signups`, `/clicks`	Totals, a time series, countries, browsers, systems, devices and error codes. Query: `project` (omit for all), `range` (`24h`, `7d`, `30d`, `90d`), `status` (`ok` or `error`), `deployment` (one linked project only).
`GET /v1/active`	People online now, with country, browser, page and, if collected, name or email. Query: `project`.
`GET /v1/overview`	The numbers behind the dashboard home.
`GET /v1/projects/{id}/export`	Every stored event, as JSON lines or with `?format=csv`.

curl "https://api.analytics.vantrex.cloud/v1/stats/logins?range=7d&status=error" \
  -H "Authorization: Bearer $VTX_TOKEN"

Rate limits and errors

What	Limit
Browser events, per visitor address	240 a minute
Heartbeats, per visitor	60 a minute
Browser events, per project	3 000 a minute
Server events, per project	6 000 a minute
Events per request	100, in at most 64 KB
Analytics projects per account	20

Past a limit the answer is 429 with a Retry-After header in seconds. Other errors use the usual codes with a JSON body such as {"error": "invalid key"}: 400 for a bad request, 401 for a missing or wrong key, 403 for an event type the key may not send or an origin that is not allowed, 404 for something that is not yours.