PilotFox

API and MCP

Read your analytics with the PilotFox REST API and organization API keys, and connect AI assistants through the MCP server at pilotfox.app/api/mcp.

Everything the dashboard shows comes from a REST API, and the same API is open to your own code. An MCP server offers the main reports to AI assistants.

REST API

  • Base URL: https://pilotfox.app/api/v1. Requests and responses are JSON.
  • Reference: the interactive API reference lists every endpoint with its parameters and responses, generated from the API's own schemas. The OpenAPI document behind it is at https://pilotfox.app/api/docs/openapi.json.
  • Guides: the developer documentation explains authentication, permissions, errors, pagination and rate limits, with examples, and covers server-side events, the payments API and the MCP server in depth.
  • Responses are { "data": …, "meta": … }; errors are { "error": { "code", "message", "details" } } with a matching HTTP status. Large ids are strings.
  • Sites are addressed by their public id, the same value as the script tag's data-site.
  • Time windows: reports take last (for example last=7d, 24h or 30m, at most 400 days) or start and end dates, an optional time zone tz, and compare=previous or compare=year.
curl -H "Authorization: Bearer $PILOTFOX_API_KEY" \
  "https://pilotfox.app/api/v1/sites/SITE_ID/overview?last=7d"

API keys

Organization admins create keys in Organization settings → API keys. Each key:

  • acts for the organization, with the permissions chosen when it is created (for example read-only analytics), and can be limited to some sites;
  • can expire after 7, 30, 90 or 365 days, or never;
  • is shown once, when it is created. PilotFox stores only a hash of it; revoke a key you no longer need.

Send the key in an Authorization: Bearer header (as above) or an x-api-key header. Keep keys on your server: never put one in a web page or a mobile app. The API allows each key 600 reads and 60 writes a minute.

Two permissions exist only for API keys, never in a person's role, and only organization admins and owners can grant them:

  • ingest:write can send events from your server.
  • revenue:write can record payments from a billing system PilotFox does not connect to (Paddle, Lemon Squeezy, Gumroad, your own): POST /api/v1/sites/SITE_ID/payments and its refund and delete calls, each with its own budget of 300 requests a minute per key.

MCP server

The Model Context Protocol server lets an AI assistant read your analytics, for example "which pages brought the most signups last week?". It answers at:

https://pilotfox.app/api/mcp

It uses MCP's Streamable HTTP transport and accepts only protocol revision 2026-07-28: a client that speaks an earlier revision (one that starts with an initialize request) is refused. Its tools cover sites, overview, timeseries, breakdowns, pages, live visitors, countries and map points, events and event names, errors, web vitals, sessions, users, goals, funnels, journeys, retention, segments, annotations and revenue (summary and breakdown), and can create, change or delete goals, save or delete funnels and add annotations when the credential allows it. A segment can be applied to the analytics tools.

Two ways to connect:

  • API key: configure your MCP client to send Authorization: Bearer YOUR_KEY (or x-api-key). Works with any client that lets you set a header. The key's permissions and sites limit what the assistant can see.
  • Sign in with PilotFox (OAuth): clients that support MCP authorization can sign in with your PilotFox account instead. You choose the organization and approve the access; the assistant then acts within your role in that organization, limited to the permissions it asked for. PilotFox does not offer dynamic client registration: a client needs a client id that PilotFox can resolve, such as a Client ID Metadata Document URL. Signing out of PilotFox ends the access, and so does leaving the organization.

The MCP server allows 120 requests a minute per credential. What the tools return is your site's data: page titles, event names and properties come from your visitors' browsers, so assistants are told to treat it as data, not instructions.

Last updated · Markdown version