Agent API

Auth

Every request:

Authorization: Bearer <key>

(x-api-key: <key> also works.) Mint keys at dashboard → gear icon → mcp tab. A key (ap_sk_…) belongs to your account, is shown once (stored hashed), and is scoped at creation — all your apps (new apps included automatically) or a selected list; edit the scope or revoke it there anytime. Every tool answers only within the scope: list_apps returns the scoped set, app: "all" aggregates exactly that set. Keys are read-only, distinct from the per-app ap_pk_ ingest key. Never commit or print one — use an environment variable.

REST

GET with query params, or POST with a JSON body of the same args, against https://activationpal.com/api/v1/<tool>:

curl -s "https://activationpal.com/api/v1/get_stats?app=myapp&range=7d" \
  -H "Authorization: Bearer $AP_KEY"

curl -s https://activationpal.com/api/v1/get_events \
  -H "Authorization: Bearer $AP_KEY" -H "Content-Type: application/json" \
  -d '{"app": "myapp", "name": "paywall_shown", "limit": 100}'

Responses: { "ok": true, ... } or { "ok": false, "error": "..." }. GET /api/v1 (authed) lists every tool with its JSON schema.

MCP

Streamable HTTP, stateless, same tools and key. The dashboard creates a setup prompt that an MCP-capable coding agent can follow. For manual setup, use:

Server name: activationpal
Transport: Streamable HTTP
URL: https://activationpal.com/api/mcp
Authorization header: Bearer <key>

Tools

list_apps

No params. Returns every tracked app: id (the app value in every other tool), display name, IANA timezone, App Store adam_id.

get_stats

The full analytics snapshot — the exact object the web dashboard renders.

Param	Type	Notes
app	string, required	App id from list_apps, or all
range	string	today, yesterday, week (calendar week, Mon-first), 7d (default), 14d, 30d, month, custom
from, to	string	YYYY-MM-DD, both required with range: custom, inclusive, at most 366 days
revenue	string	gross (default): what buyers paid, before refunds, VAT and store fees. net: what you receive, after refunds, VAT and store fees. Applies to every money field, like the dashboard toggle
tz	string	IANA override; default: the app's own timezone (apps.md) — every bucket and daily cut runs in it
users	boolean	Include the per-device rollup (long; default false)

Returns: headline installs / onboarded / devices / app-opens / purchases / ARPU / conversion + paywall-conversion rates (install-cohort) / average + median session length with previous-period values; gross and net revenue totals, refunds (rate, amount, per-app, breakdown), and mix (new subs / renewals / one-time); pricing-tier splits with per-country detail; time-bucketed chart series; cohort onboarding funnel (steps, answer splits, completion, paywall shown → plan → purchased with plan splits); paywall placements; acquisition (Apple Ads vs organic via AdServices); Apple Search Ads spend / taps / CPI; revenue-provider health (trials, conversions, churn reasons, by-product); geo by country and city; device / OS / app-version / language breakdowns; custom event counts; in all mode, per-app comparison rows (revenue, installs, ARPU, onboarded %, conversion %, paywall conv. %, trial churn %, refund rate %) for this and the previous period.

get_cohorts

Compare install cohorts across onboarding completion, paywall conversion, retention, trial starts, trial-to-paid conversion, and ARPU. Returns the same cohort snapshot as the dashboard.

Param	Type	Notes
app	string, required	App id from list_apps, or all for apps accessible to your key
granularity	string	day, week (default), or month
tz	string	IANA timezone override; defaults to the app's timezone

Cohorts group users by install date and compare outcomes across calendar periods since the cohort began. Trial conversion groups trials by their start date. Windows still in progress include events through now and are marked partial; future windows are null. Cohort ARPU is gross, linked to the cohort's own installs. The same app permissions and analytics usage limits apply as for get_stats.

get_events

Recent raw events, newest first. Each row: name, ts, device_id, user_id, country, city, source, env, props.

Param	Type	Notes
app	string, required	App id, or all
limit	number	1–500, default 50
name	string	Exact event name — paywall_shown, rc_renewal, any custom event
device_id	string	Only this device's events
source	string	sdk, revenuecat, or superwall
env	string	release, testflight, debug
since	string	ISO timestamp — only events at/after it

get_user

One device's full timeline for an app, oldest first: every SDK event it sent plus the revenue-provider events of every user id it reported — replays a single user's journey. Params, both required: app, device_id (from get_stats with users: true, or get_events).