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.

Updated All docs as one Markdown file

Authentication

Header
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
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": "…" }
FieldMeaning
transaction_idRequired. Your id for the payment; the same id again updates rather than duplicates.
amountRequired. A number in major units. Negative is not needed for a refund: send refunded: true instead.
currencyThree letters. Defaults to the website's currency.
visitor_id, session_idFrom attribution(). The direct match.
customer_id, email, nameWho paid. Email is the fallback match against identified visitors.
timestampISO 8601. Defaults to now.
renewaltrue for a subscription renewal, which the MRR figures treat differently from a first payment.
refundedtrue 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.

Body
{ "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.

deploy.yml
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.