Agents and API
Server-to-server API
Four endpoints, authenticated with the website's key as a bearer token. The key is on the API and MCP keys step of the website, and can be rotated there.
Authentication
Authorization: Bearer <site-key>One key per website, scoped to that website alone. The same key is what the MCP server takes. Reading reports is done through the MCP server rather than through these endpoints; see the MCP page.
POST /api/v1/payments
A payment from any provider that has no built-in integration. The amount is in major units, 29.99 rather than 2999; the currency defaults to the website's. Send visitor_id and session_id from window.geckostats.attribution() for a direct match; without them the payment is matched by email against identified visitors, and held if nothing matches yet.
curl -X POST https://geckostats.com/api/v1/payments \
-H "Authorization: Bearer <site-key>" -H "Content-Type: application/json" \
-d '{
"transaction_id": "ord_8x2k",
"amount": 29.99,
"currency": "USD",
"visitor_id": "<ml_visitor_id>",
"session_id": "<ml_session_id>",
"email": "buyer@example.com",
"renewal": false
}'
{ "ok": true, "attributed": true, "visitor_id": "…" }| Field | Meaning |
|---|---|
| transaction_id | Required. Your id for the payment; the same id again updates rather than duplicates. |
| amount | Required. A number in major units. Negative is not needed for a refund: send refunded: true instead. |
| currency | Three letters. Defaults to the website's currency. |
| visitor_id, session_id | From attribution(). The direct match. |
| customer_id, email, name | Who paid. Email is the fallback match against identified visitors. |
| timestamp | ISO 8601. Defaults to now. |
| renewal | true for a subscription renewal, which the MRR figures treat differently from a first payment. |
| refunded | true to record a refund of the same transaction_id. |
POST /api/v1/goals
A goal reached on your server, such as a signup that completes in a backend job. It is attached to the visitor's latest session; a visitor the website has never seen answers 404.
{ "visitor_id": "<ml_visitor_id>", "name": "signup_completed", "props": { "plan": "pro" } }POST /api/v1/deploys
A release marker: a line on the chart with the release beside it, so a drop in revenue or Core Web Vitals can be read against what shipped. One curl at the end of your pipeline.
curl -X POST https://geckostats.com/api/v1/deploys \
-H "Authorization: Bearer <site-key>" -H "Content-Type: application/json" \
-d '{ "name": "v2.4.0", "sha": "'$GITHUB_SHA'", "url": "https://github.com/you/repo/releases/v2.4.0" }'Fields: name or version, sha, url, and an ISO timestamp that defaults to now. The reply is { ok, id, ts }.
POST /api/v1/crawls
Which AI crawlers read your pages, from your own server logs: GPTBot, ClaudeBot and the rest, classified by whether they came to train, to index, or to answer a question somebody was asking right then. One hit as { ua, path, ts, status }, or a batch as { hits: [ … ] } of up to 500. Unknown agents are counted as skipped rather than stored, and the reply says how many were recorded and how many skipped.