API reference

These pages describe every endpoint of PilotFox, one page per operation (a method and a path), with its parameters, request body, responses and their schemas, and who may call it. They are generated from openapi.json, the OpenAPI 3.1 document the API builds from its own request and response schemas and access rules, so they match the code they were built from. Each instance serves the same document for its own version at /api/docs/openapi.json (and /api/docs/openapi.yaml), and an interactive reference at /api/docs/.

Before you start, read the guides: Authentication (API keys), Permissions (which permission each endpoint needs), Errors, Rate limits, Pagination and Query parameters (time windows, filters, segments).

How the pages are groupedCopy Anchor Link

The sidebar has one section per tag of the OpenAPI document, in the document's order, and one page per operation in the section of its tag. A page is titled with the operation's summary, which the sidebar shows too, and shows its method and full path. Its address is made from the tag and the operation's operationId: GET /api/v1/sites/{siteId}/goals (listGoals, tag Goals) is at /docs/api/reference/goals/list-goals/.

A page's description ends with who may call the operation: the permission it needs, and whether share links, public sites or API keys limited to some sites are accepted. Permission per endpoint lists all of them in one place.

Integrations work with the sections from Organizations to Ingest, with an API key holding the permissions they list. The others serve other callers:

• System: the liveness and readiness probes and the instance's public configuration; no credential.
• Account: the signed-in person (GET /api/v1/me), their email report subscriptions and what deleting their account would do (GET /api/v1/me/deletion); a signed-in session only, never an API key.
• Tracker: what the tracking script loads and sends to. These endpoints live outside /api/v1 and take no credential.
• MCP: the MCP server at /api/mcp, and the /.well-known/ documents MCP clients read to sign in with OAuth.
• Auth: the dashboard's sign-in and account endpoints under /api/auth/ (sign-up, sign-in, sessions, two-factor authentication, organizations, members and invitations). One page per method covers every path. They are for the dashboard only: their requests and answers can change in any version, their errors have a shape of their own, and they take a session cookie, never an API key. MCP clients use the OAuth endpoints among them, described in Connect with OAuth.
• Admin: /api/v1/admin/, the usage, jobs and backups of an instance, for its system administrators (signed-in session only).

Conventions on these pagesCopy Anchor Link

• Paths use {name} for path parameters: {siteId} is a site's public id, {orgId} an organization's id, and {*} stands for the rest of the path.
• The server is https://pilotfox.app. A self-hosted instance is at its own PUBLIC_URL: in the document, the server URL is {protocol}://{host}, with host a variable that code generators let you set.
• Errors follow the error envelope on every /api/v1 endpoint.
• Analytics endpoints answer { data, meta }, most others { data }, and some a status with no body; see Responses.
• Each /api/v1 operation of the document also carries the access rule the API enforces, in the vendor extension x-pilotfox-access (kind, permission, and the flags behind the notes of Permission per endpoint), for tools that read the document.