{"openapi":"3.2.0","info":{"title":"PilotFox API","version":"0.1.0"},"components":{"securitySchemes":{"affiliateToken":{"type":"apiKey","in":"header","name":"x-affiliate-token","description":"An affiliate portal token, minted by `POST /api/v1/sites/{siteId}/affiliates/{id}/share`: one affiliate's own report, nothing else."},"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"An organization API key (`ak_…`), with the permissions and the sites it was created with. For servers and scripts: no cookie and no Origin check. Also accepted as `Authorization: Bearer ak_…` (`apiKeyBearer`). A request carries one credential: a key sent with a share token or a live session cookie is 400 (`details.reason`: `ambiguous_credentials`)."},"apiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"ak_…","description":"The same organization API key, sent as `Authorization: Bearer ak_…`."},"mcpAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"An OAuth access token for `/api/mcp`, issued by this instance to an MCP client and bound to one organization and its scopes (a DPoP-bound one as `Authorization: DPoP <token>` with its `DPoP` proof). Clients find the authorization server through the protected resource metadata that a 401's `WWW-Authenticate` challenge names (RFC 9728). Only while MCP is on and `PUBLIC_URL` is https (or http on a loopback host); otherwise MCP takes API keys only."},"session":{"type":"apiKey","in":"cookie","name":"__Secure-pilotfox.session_token","description":"The web app's sign-in session, acting with the user's role; named `pilotfox.session_token` on an instance whose `PUBLIC_URL` is plain http. Under `/api/v1`, a POST, PUT, PATCH or DELETE carrying a cookie must come from the instance's own origin (`Origin`: `PUBLIC_URL` or a `DASHBOARD_ORIGINS` entry; else 403), and a body it carries must be JSON or multipart (else 415)."},"shareToken":{"type":"apiKey","in":"header","name":"x-share-token","description":"A share link's token (the end of its `/share/<token>` URL): read access to one site with the link's scopes."},"shareTokenQuery":{"type":"apiKey","in":"query","name":"share","description":"The share link token as the `share` query parameter, where no header can be set."}},"schemas":{}},"paths":{"/.well-known/{*}":{"get":{"operationId":"getWellKnown","summary":"Get an OAuth discovery document","tags":["MCP"],"description":"Discovery documents that the OAuth authorization server answers while MCP OAuth is on (MCP on, and an https or loopback http `PUBLIC_URL`), which MCP clients read to authorize: the protected resource metadata (`/.well-known/oauth-protected-resource`, and `/.well-known/oauth-protected-resource/api/mcp`, which a 401 from `/api/mcp` names; RFC 9728) and the authorization server's (`/.well-known/oauth-authorization-server/api/auth`; RFC 8414). 404 for any other path.","security":[],"parameters":[{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"The metadata document","content":{"application/json":{"schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The metadata document"}}}}}}},"/api/auth/{*}":{"get":{"operationId":"authGet","summary":"Sign-in and account GET endpoints","tags":["Auth"],"description":"The web app's sign-in and account endpoints, one operation per method for every path under `/api/auth/` (`{*}`): sign-up and sign-in with email and password, sign-in with an emailed code (existing accounts only) and with GitHub or Google where the instance configures them, sessions, two-factor authentication, deleting one's own account, organizations, members, invitations and teams, administration and, with MCP OAuth on, the OAuth authorization server. They are for the web app only: their requests and answers follow its needs and can change in any version. Integrations use `/api/v1` with an API key (keys are managed under `/api/v1/orgs/{orgId}/api-keys`, not here). The exception is the OAuth authorization server of MCP clients: its standard endpoints are the ones its metadata names (`/.well-known/oauth-authorization-server/api/auth`, RFC 8414): `/api/auth/oauth2/authorize`, `POST /api/auth/oauth2/token`, `POST /api/auth/oauth2/revoke` and `GET /api/auth/jwks`; a system administrator registers a client with `POST /api/auth/oauth2/create-client`. The endpoints apply their own CSRF, Origin and rate limit checks.","security":[{"session":[]},{}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"The endpoint's answer, whose shape depends on the path","content":{"application/json":{"schema":{"description":"The endpoint's answer, whose shape depends on the path"}}}}}},"post":{"operationId":"authPost","summary":"Sign-in and account POST endpoints","tags":["Auth"],"description":"The web app's sign-in and account endpoints, one operation per method for every path under `/api/auth/` (`{*}`): sign-up and sign-in with email and password, sign-in with an emailed code (existing accounts only) and with GitHub or Google where the instance configures them, sessions, two-factor authentication, deleting one's own account, organizations, members, invitations and teams, administration and, with MCP OAuth on, the OAuth authorization server. They are for the web app only: their requests and answers follow its needs and can change in any version. Integrations use `/api/v1` with an API key (keys are managed under `/api/v1/orgs/{orgId}/api-keys`, not here). The exception is the OAuth authorization server of MCP clients: its standard endpoints are the ones its metadata names (`/.well-known/oauth-authorization-server/api/auth`, RFC 8414): `/api/auth/oauth2/authorize`, `POST /api/auth/oauth2/token`, `POST /api/auth/oauth2/revoke` and `GET /api/auth/jwks`; a system administrator registers a client with `POST /api/auth/oauth2/create-client`. The endpoints apply their own CSRF, Origin and rate limit checks.","security":[{"session":[]},{}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"The endpoint's answer, whose shape depends on the path","content":{"application/json":{"schema":{"description":"The endpoint's answer, whose shape depends on the path"}}}}}},"delete":{"operationId":"authDelete","summary":"Sign-in and account DELETE endpoints","tags":["Auth"],"description":"The web app's sign-in and account endpoints, one operation per method for every path under `/api/auth/` (`{*}`): sign-up and sign-in with email and password, sign-in with an emailed code (existing accounts only) and with GitHub or Google where the instance configures them, sessions, two-factor authentication, deleting one's own account, organizations, members, invitations and teams, administration and, with MCP OAuth on, the OAuth authorization server. They are for the web app only: their requests and answers follow its needs and can change in any version. Integrations use `/api/v1` with an API key (keys are managed under `/api/v1/orgs/{orgId}/api-keys`, not here). The exception is the OAuth authorization server of MCP clients: its standard endpoints are the ones its metadata names (`/.well-known/oauth-authorization-server/api/auth`, RFC 8414): `/api/auth/oauth2/authorize`, `POST /api/auth/oauth2/token`, `POST /api/auth/oauth2/revoke` and `GET /api/auth/jwks`; a system administrator registers a client with `POST /api/auth/oauth2/create-client`. The endpoints apply their own CSRF, Origin and rate limit checks.","security":[{"session":[]},{}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"The endpoint's answer, whose shape depends on the path","content":{"application/json":{"schema":{"description":"The endpoint's answer, whose shape depends on the path"}}}}}},"patch":{"operationId":"authPatch","summary":"Sign-in and account PATCH endpoints","tags":["Auth"],"description":"The web app's sign-in and account endpoints, one operation per method for every path under `/api/auth/` (`{*}`): sign-up and sign-in with email and password, sign-in with an emailed code (existing accounts only) and with GitHub or Google where the instance configures them, sessions, two-factor authentication, deleting one's own account, organizations, members, invitations and teams, administration and, with MCP OAuth on, the OAuth authorization server. They are for the web app only: their requests and answers follow its needs and can change in any version. Integrations use `/api/v1` with an API key (keys are managed under `/api/v1/orgs/{orgId}/api-keys`, not here). The exception is the OAuth authorization server of MCP clients: its standard endpoints are the ones its metadata names (`/.well-known/oauth-authorization-server/api/auth`, RFC 8414): `/api/auth/oauth2/authorize`, `POST /api/auth/oauth2/token`, `POST /api/auth/oauth2/revoke` and `GET /api/auth/jwks`; a system administrator registers a client with `POST /api/auth/oauth2/create-client`. The endpoints apply their own CSRF, Origin and rate limit checks.","security":[{"session":[]},{}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"The endpoint's answer, whose shape depends on the path","content":{"application/json":{"schema":{"description":"The endpoint's answer, whose shape depends on the path"}}}}}}},"/api/c/{publicId}":{"get":{"operationId":"getTrackerConfig","summary":"Get the tracker's site configuration","tags":["Tracker"],"description":"What the tracker reads on each page load: the site's tracking settings (what to capture and how), the session replay settings, and whether to honor Global Privacy Control. No credential; cacheable for 60 seconds. 404 for an unknown site, 429 past its own per-client rate limit.","security":[],"parameters":[{"schema":{"type":"string"},"in":"path","name":"publicId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"object","properties":{"initialPageview":{"default":true,"type":"boolean"},"spa":{"default":true,"type":"boolean"},"hashRouting":{"default":false,"type":"boolean"},"querystring":{"default":true,"type":"boolean"},"outbound":{"default":true,"type":"boolean"},"clicks":{"default":false,"type":"boolean"},"forms":{"default":false,"type":"boolean"},"copy":{"default":false,"type":"boolean"},"inputs":{"default":false,"type":"boolean"},"errors":{"default":false,"type":"boolean"},"vitals":{"default":false,"type":"boolean"},"paymentLinks":{"default":true,"type":"boolean"}},"required":["initialPageview","spa","hashRouting","querystring","outbound","clicks","forms","copy","inputs","errors","vitals","paymentLinks"],"additionalProperties":false},"replay":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Replay on and somewhere to store it"},"sampleRate":{"type":"number","description":"Percent of browser tabs that record, 0-100: a tab draws once (on every page load when sessionStorage is unavailable)"},"maskAllInputs":{"type":"boolean"},"maskTextSelector":{"type":["string","null"]},"blockSelector":{"type":["string","null"]},"excludedPaths":{"description":"With replay on: path globs whose pages never record","type":"array","items":{"type":"string"}},"allowedHostnames":{"description":"With replay on: the hostnames that may record (`.example.com`: any subdomain); empty for any","type":"array","items":{"type":"string"}}},"required":["enabled","sampleRate","maskAllInputs","maskTextSelector","blockSelector"],"additionalProperties":false},"respectGpc":{"type":"boolean"},"persistentId":{"type":"boolean","enum":[false]}},"required":["tracking","replay","respectGpc","persistentId"],"additionalProperties":false}}}}}}},"/api/e":{"post":{"operationId":"trackEvent","summary":"Record a tracker event","tags":["Tracker"],"description":"What the tracker sends for each pageview, custom event, autocaptured interaction, error and web vital. No credential: the body names the site, and the visitor is derived from the request's IP address and User-Agent (behind a first-party proxy, from the `X-PilotFox-IP` its proxy secret vouches for), never from a cookie. 204 whether the event was stored or dropped; 400 for a malformed body or proxy secret, 404 for an unknown site, 413 past the size limit (`INGEST_MAX_BODY_BYTES`), 429 past the per-client rate limit. Server-side code sends `POST /api/v1/ingest/events` with an API key instead.","requestBody":{"required":true,"content":{"text/plain":{"schema":{"type":"object","properties":{"site":{"type":"string","minLength":1},"type":{"type":"string","enum":["pageview","event","outbound","click","form","input","copy","error","vital"]},"url":{"type":"string","minLength":1},"ref":{"type":"string"},"title":{"type":"string"},"name":{"type":"string"},"props":{},"sw":{"type":"number"},"sh":{"type":"number"},"lang":{"type":"string"},"uid":{"type":"string"},"tag":{"type":"string"},"vitals":{"type":"object","properties":{"lcp":{"type":"number"},"cls":{"type":"number"},"inp":{"type":"number"},"fcp":{"type":"number"},"ttfb":{"type":"number"}}},"err":{"type":"object","properties":{"message":{"type":"string"},"stack":{"type":"string"},"file":{"type":"string"},"line":{"type":"number"},"col":{"type":"number"}}},"bs":{"type":"number"},"bm":{"type":"number"},"aid":{"type":"string"}},"required":["site","type","url"]}},"application/json":{"schema":{"type":"object","properties":{"site":{"type":"string","minLength":1},"type":{"type":"string","enum":["pageview","event","outbound","click","form","input","copy","error","vital"]},"url":{"type":"string","minLength":1},"ref":{"type":"string"},"title":{"type":"string"},"name":{"type":"string"},"props":{},"sw":{"type":"number"},"sh":{"type":"number"},"lang":{"type":"string"},"uid":{"type":"string"},"tag":{"type":"string"},"vitals":{"type":"object","properties":{"lcp":{"type":"number"},"cls":{"type":"number"},"inp":{"type":"number"},"fcp":{"type":"number"},"ttfb":{"type":"number"}}},"err":{"type":"object","properties":{"message":{"type":"string"},"stack":{"type":"string"},"file":{"type":"string"},"line":{"type":"number"},"col":{"type":"number"}}},"bs":{"type":"number"},"bm":{"type":"number"},"aid":{"type":"string"}},"required":["site","type","url"]}}}},"security":[],"responses":{"204":{"description":"Taken, or dropped by the site's exclusions or bot rules: ingest never says which"}}}},"/api/i":{"post":{"operationId":"trackIdentify","summary":"Identify the tracker's visitor","tags":["Tracker"],"description":"What the tracker's `identify()` sends: links the visitor making the request (its IP address and User-Agent, as for events) to the user id `uid`, with optional traits. No credential; 8 KB at most (413 past it), and the event rate limit (429). 204 whether it was stored or dropped by the site's exclusions or bot rules; 400 for a malformed body, 404 for an unknown site.","requestBody":{"required":true,"content":{"text/plain":{"schema":{"type":"object","properties":{"site":{"type":"string","minLength":1},"uid":{"type":"string"},"traits":{},"bs":{"type":"number"},"bm":{"type":"number"}},"required":["site","uid"]}},"application/json":{"schema":{"type":"object","properties":{"site":{"type":"string","minLength":1},"uid":{"type":"string"},"traits":{},"bs":{"type":"number"},"bm":{"type":"number"}},"required":["site","uid"]}}}},"security":[],"responses":{"204":{"description":"Taken, or dropped by the site's exclusions or bot rules: ingest never says which"}}}},"/api/mcp":{"get":{"operationId":"openMcpStream","summary":"Open an MCP stream (not supported)","tags":["MCP"],"description":"405 with `Allow: POST`: the server is stateless, so it opens no server-sent event stream and keeps no session to end.","security":[],"responses":{"405":{"description":"A JSON-RPC error: method not allowed","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]}},"required":["jsonrpc"],"additionalProperties":{},"description":"A JSON-RPC error: method not allowed"}}}}}},"post":{"operationId":"callMcp","summary":"Call the MCP server","tags":["MCP"],"description":"The Model Context Protocol server (Streamable HTTP, stateless; the 2026-07-28 protocol revision only, every other revision is refused): one JSON-RPC request per POST, one JSON answer. Its tools read the same reports as the REST API, with the caller's permissions. The credential is an organization API key, or, when the instance's `PUBLIC_URL` is https (or http on a loopback host), an OAuth access token issued to the MCP client for one organization; a session cookie never counts. An `Origin` header, when sent, must be the instance's own (`PUBLIC_URL` or a `DASHBOARD_ORIGINS` entry; else 403). 120 requests a minute per API key, or per user and MCP client for an OAuth token (429). Every refusal is a JSON-RPC error that keeps its HTTP status; a 401 carries the OAuth challenge (`WWW-Authenticate`) while OAuth is on.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]}},"required":["jsonrpc"],"additionalProperties":{}}}}},"security":[{"apiKey":[]},{"apiKeyBearer":[]},{"mcpAccessToken":[]}],"responses":{"200":{"description":"The JSON-RPC answer","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]}},"required":["jsonrpc"],"additionalProperties":{},"description":"The JSON-RPC answer"}}}}}},"delete":{"operationId":"endMcpSession","summary":"End an MCP session (not supported)","tags":["MCP"],"description":"405 with `Allow: POST`: the server is stateless, so it opens no server-sent event stream and keeps no session to end.","security":[],"responses":{"405":{"description":"A JSON-RPC error: method not allowed","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]}},"required":["jsonrpc"],"additionalProperties":{},"description":"A JSON-RPC error: method not allowed"}}}}}}},"/api/r.js":{"get":{"operationId":"getReplayScript","summary":"Get the replay recorder script","tags":["Tracker"],"description":"The session replay recorder, which the tracker loads in the browser tabs the site's replay settings sample (or that call `startReplay()`). Cached for a day (`ETag`, 304 on a match); 503 when it was never built.","security":[],"responses":{"200":{"description":"The replay recorder bundle","content":{"application/javascript":{"schema":{"type":"string"}}}},"304":{"description":"Not Modified: the `If-None-Match` tag is current"}}}},"/api/rec/{publicId}":{"post":{"operationId":"trackReplayChunk","summary":"Record a session replay chunk","tags":["Tracker"],"description":"What the replay recorder (`/api/r.js`) sends: one chunk of rrweb events of the visitor's current session, gzipped (`Content-Encoding: gzip`) or, for the last flush of a page, plain JSON as `text/plain`. No credential: the visitor is derived from the request, as for events. 204 whether the chunk was stored or dropped (replay off, no live session, a bot, the session's caps reached); 400 for a malformed chunk, 404 for an unknown site, 413 past the size limits, 415 for another content type, 429 past the per-client rate limit, 503 when busy or storage is unavailable.","security":[],"parameters":[{"schema":{"type":"string"},"in":"path","name":"publicId","required":true}],"responses":{"204":{"description":"Stored, or dropped without saying why"}}}},"/api/s.js":{"get":{"operationId":"getTrackerScript","summary":"Get the tracker script","tags":["Tracker"],"description":"The browser tracker, loaded by the site's snippet (`<script defer src=\".../api/s.js\" data-site=\"SITE_ID\">`). Cached for an hour (`ETag`, 304 on a match); 503 when the instance's tracker was never built.","security":[],"responses":{"200":{"description":"The tracker bundle","content":{"application/javascript":{"schema":{"type":"string"}}}},"304":{"description":"Not Modified: the `If-None-Match` tag is current"}}}},"/api/v1/admin/backups":{"get":{"operationId":"getBackupStatus","summary":"Get the backup status","tags":["Admin"],"description":"The R2 bucket, the schedule and the next run, the last success and failure, the run in progress, the ClickHouse copies a drill or restore left behind, and the Postgres client's compatibility.\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"r2":{"anyOf":[{"type":"object","properties":{"bucket":{"type":"string"},"endpoint":{"type":"string"}},"required":["bucket","endpoint"],"additionalProperties":false},{"type":"null"}]},"retentionDays":{"type":["number","null"]},"timeoutSeconds":{"type":["number","null"]},"configError":{"type":["string","null"]},"schedule":{"type":"object","properties":{"schedule":{"type":"string","enum":["off","every12h","daily","weekly"]},"hour":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"weekday":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"updatedAt":{"type":["string","null"]},"updatedBy":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["id","email"],"additionalProperties":false},{"type":"null"}]}},"required":["schedule","hour","weekday","updatedAt","updatedBy"],"additionalProperties":false},"nextRunAt":{"type":["string","null"]},"lastSuccess":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["backup","drill","restore"]},"trigger":{"type":"string","enum":["manual","schedule"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"name":{"type":["string","null"]},"parentRunId":{"type":["string","null"]},"scheduledFor":{"type":["string","null"]},"queuedAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"postgres":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["key","bytes"],"additionalProperties":false},{"type":"null"}]},"clickhouse":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["prefix","bytes"],"additionalProperties":false},{"type":"null"}]},"error":{"type":["string","null"]},"details":{"type":"object","properties":{"retention":{"type":"string","enum":["applied","forbidden","error"]},"drill":{"type":"object","properties":{"postgres":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"live":{"type":"number"},"restored":{"type":["number","null"]}},"required":["table","live","restored"],"additionalProperties":false}},"clickhouse":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"before":{"type":["number","null"]},"restored":{"type":["number","null"]},"after":{"type":["number","null"]}},"required":["table","before","restored","after"],"additionalProperties":false}},"problems":{"type":"array","items":{"type":"string"}}},"required":["postgres","clickhouse","problems"],"additionalProperties":false},"safetyBackup":{"type":"string"},"preRestoreDatabase":{"type":"string"},"pgMigrationsApplied":{"type":"number"},"chMigrationsApplied":{"type":"array","items":{"type":"string"}},"pgCommitted":{"type":"boolean"}},"additionalProperties":false},"triggeredBy":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["id","email"],"additionalProperties":false},{"type":"null"}]}},"required":["id","kind","trigger","status","name","parentRunId","scheduledFor","queuedAt","startedAt","finishedAt","postgres","clickhouse","error","details","triggeredBy"],"additionalProperties":false},{"type":"null"}]},"lastFailure":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["backup","drill","restore"]},"trigger":{"type":"string","enum":["manual","schedule"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"name":{"type":["string","null"]},"parentRunId":{"type":["string","null"]},"scheduledFor":{"type":["string","null"]},"queuedAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"postgres":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["key","bytes"],"additionalProperties":false},{"type":"null"}]},"clickhouse":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["prefix","bytes"],"additionalProperties":false},{"type":"null"}]},"error":{"type":["string","null"]},"details":{"type":"object","properties":{"retention":{"type":"string","enum":["applied","forbidden","error"]},"drill":{"type":"object","properties":{"postgres":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"live":{"type":"number"},"restored":{"type":["number","null"]}},"required":["table","live","restored"],"additionalProperties":false}},"clickhouse":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"before":{"type":["number","null"]},"restored":{"type":["number","null"]},"after":{"type":["number","null"]}},"required":["table","before","restored","after"],"additionalProperties":false}},"problems":{"type":"array","items":{"type":"string"}}},"required":["postgres","clickhouse","problems"],"additionalProperties":false},"safetyBackup":{"type":"string"},"preRestoreDatabase":{"type":"string"},"pgMigrationsApplied":{"type":"number"},"chMigrationsApplied":{"type":"array","items":{"type":"string"}},"pgCommitted":{"type":"boolean"}},"additionalProperties":false},"triggeredBy":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["id","email"],"additionalProperties":false},{"type":"null"}]}},"required":["id","kind","trigger","status","name","parentRunId","scheduledFor","queuedAt","startedAt","finishedAt","postgres","clickhouse","error","details","triggeredBy"],"additionalProperties":false},{"type":"null"}]},"active":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["backup","drill","restore"]},"trigger":{"type":"string","enum":["manual","schedule"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"name":{"type":["string","null"]},"parentRunId":{"type":["string","null"]},"scheduledFor":{"type":["string","null"]},"queuedAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"postgres":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["key","bytes"],"additionalProperties":false},{"type":"null"}]},"clickhouse":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["prefix","bytes"],"additionalProperties":false},{"type":"null"}]},"error":{"type":["string","null"]},"details":{"type":"object","properties":{"retention":{"type":"string","enum":["applied","forbidden","error"]},"drill":{"type":"object","properties":{"postgres":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"live":{"type":"number"},"restored":{"type":["number","null"]}},"required":["table","live","restored"],"additionalProperties":false}},"clickhouse":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"before":{"type":["number","null"]},"restored":{"type":["number","null"]},"after":{"type":["number","null"]}},"required":["table","before","restored","after"],"additionalProperties":false}},"problems":{"type":"array","items":{"type":"string"}}},"required":["postgres","clickhouse","problems"],"additionalProperties":false},"safetyBackup":{"type":"string"},"preRestoreDatabase":{"type":"string"},"pgMigrationsApplied":{"type":"number"},"chMigrationsApplied":{"type":"array","items":{"type":"string"}},"pgCommitted":{"type":"boolean"}},"additionalProperties":false},"triggeredBy":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["id","email"],"additionalProperties":false},{"type":"null"}]}},"required":["id","kind","trigger","status","name","parentRunId","scheduledFor","queuedAt","startedAt","finishedAt","postgres","clickhouse","error","details","triggeredBy"],"additionalProperties":false},{"type":"null"}]},"leftovers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"reason":{"type":"string"}},"required":["name","reason"],"additionalProperties":false}},"postgresClient":{"type":"object","properties":{"version":{"type":["string","null"]},"serverMajor":{"type":["number","null"]},"compatible":{"type":["boolean","null"]},"error":{"type":["string","null"]}},"required":["version","serverMajor","compatible","error"],"additionalProperties":false}},"required":["r2","retentionDays","timeoutSeconds","configError","schedule","nextRunAt","lastSuccess","lastFailure","active","leftovers","postgresClient"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/admin/backups/copies/{name}":{"delete":{"operationId":"deleteBackupCopy","summary":"Drop a leftover copy","tags":["Admin"],"description":"Drops a ClickHouse database that a drill or restore left behind (never the live one); 404 for any other name.\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_]{1,200}$"},"in":"path","name":"name","required":true}],"security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/admin/backups/remote":{"get":{"operationId":"listRemoteBackups","summary":"List stored backups","tags":["Admin"],"description":"The backups found in R2, and whether each one is complete enough to restore; 503 when R2 is not configured or cannot be read.\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["backup","drill"]},"takenAt":{"type":"string"},"postgres":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"bytes":{"type":"number"},"lastModified":{"type":["string","null"]}},"required":["key","bytes","lastModified"],"additionalProperties":false},{"type":"null"}]},"clickhouse":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"complete":{"type":"boolean"}},"required":["prefix","complete"],"additionalProperties":false},{"type":"null"}]},"restorable":{"type":"boolean"}},"required":["name","kind","takenAt","postgres","clickhouse","restorable"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/admin/backups/restore":{"post":{"operationId":"restoreBackup","summary":"Restore a backup","tags":["Admin"],"description":"Replaces the instance's data with a backup from R2, named twice: `confirm` must equal `name` (400 otherwise). Queued imports hold a restore off unless `cancelQueuedImports` cancels them. 404 for an unknown backup; 409 for an incomplete one, or while something else holds it off (another run, a copy left by an earlier restore, a pending erase, purge or import); 503 when R2 is not configured.\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":64},"confirm":{"type":"string","maxLength":64},"cancelQueuedImports":{"type":"boolean"}},"required":["name","confirm"],"additionalProperties":false}}}},"security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["backup","drill","restore"]},"trigger":{"type":"string","enum":["manual","schedule"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"name":{"type":["string","null"]},"parentRunId":{"type":["string","null"]},"scheduledFor":{"type":["string","null"]},"queuedAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"postgres":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["key","bytes"],"additionalProperties":false},{"type":"null"}]},"clickhouse":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["prefix","bytes"],"additionalProperties":false},{"type":"null"}]},"error":{"type":["string","null"]},"details":{"type":"object","properties":{"retention":{"type":"string","enum":["applied","forbidden","error"]},"drill":{"type":"object","properties":{"postgres":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"live":{"type":"number"},"restored":{"type":["number","null"]}},"required":["table","live","restored"],"additionalProperties":false}},"clickhouse":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"before":{"type":["number","null"]},"restored":{"type":["number","null"]},"after":{"type":["number","null"]}},"required":["table","before","restored","after"],"additionalProperties":false}},"problems":{"type":"array","items":{"type":"string"}}},"required":["postgres","clickhouse","problems"],"additionalProperties":false},"safetyBackup":{"type":"string"},"preRestoreDatabase":{"type":"string"},"pgMigrationsApplied":{"type":"number"},"chMigrationsApplied":{"type":"array","items":{"type":"string"}},"pgCommitted":{"type":"boolean"}},"additionalProperties":false},"triggeredBy":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["id","email"],"additionalProperties":false},{"type":"null"}]}},"required":["id","kind","trigger","status","name","parentRunId","scheduledFor","queuedAt","startedAt","finishedAt","postgres","clickhouse","error","details","triggeredBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/admin/backups/runs":{"get":{"operationId":"listBackupRuns","summary":"List backup runs","tags":["Admin"],"description":"Backups, drills and restores, newest first, a page at a time (`meta.nextCursor`).\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","parameters":[{"schema":{"type":"string","maxLength":2200},"in":"query","name":"cursor","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false}],"security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["backup","drill","restore"]},"trigger":{"type":"string","enum":["manual","schedule"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"name":{"type":["string","null"]},"parentRunId":{"type":["string","null"]},"scheduledFor":{"type":["string","null"]},"queuedAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"postgres":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["key","bytes"],"additionalProperties":false},{"type":"null"}]},"clickhouse":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["prefix","bytes"],"additionalProperties":false},{"type":"null"}]},"error":{"type":["string","null"]},"details":{"type":"object","properties":{"retention":{"type":"string","enum":["applied","forbidden","error"]},"drill":{"type":"object","properties":{"postgres":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"live":{"type":"number"},"restored":{"type":["number","null"]}},"required":["table","live","restored"],"additionalProperties":false}},"clickhouse":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"before":{"type":["number","null"]},"restored":{"type":["number","null"]},"after":{"type":["number","null"]}},"required":["table","before","restored","after"],"additionalProperties":false}},"problems":{"type":"array","items":{"type":"string"}}},"required":["postgres","clickhouse","problems"],"additionalProperties":false},"safetyBackup":{"type":"string"},"preRestoreDatabase":{"type":"string"},"pgMigrationsApplied":{"type":"number"},"chMigrationsApplied":{"type":"array","items":{"type":"string"}},"pgCommitted":{"type":"boolean"}},"additionalProperties":false},"triggeredBy":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["id","email"],"additionalProperties":false},{"type":"null"}]}},"required":["id","kind","trigger","status","name","parentRunId","scheduledFor","queuedAt","startedAt","finishedAt","postgres","clickhouse","error","details","triggeredBy"],"additionalProperties":false}},"meta":{"type":"object","properties":{"nextCursor":{"type":["string","null"]}},"required":["nextCursor"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"post":{"operationId":"startBackupRun","summary":"Start a backup or drill","tags":["Admin"],"description":"Queues a `backup`, or a `drill`: a backup restored into a scratch copy whose row counts are compared with the live data. 409 while another run is queued or running, or while the `BACKUP_*` settings are invalid; 503 when R2 is not configured.\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["backup","drill"]}},"required":["kind"],"additionalProperties":false}}}},"security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["backup","drill","restore"]},"trigger":{"type":"string","enum":["manual","schedule"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"name":{"type":["string","null"]},"parentRunId":{"type":["string","null"]},"scheduledFor":{"type":["string","null"]},"queuedAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"postgres":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["key","bytes"],"additionalProperties":false},{"type":"null"}]},"clickhouse":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"bytes":{"type":["number","null"]}},"required":["prefix","bytes"],"additionalProperties":false},{"type":"null"}]},"error":{"type":["string","null"]},"details":{"type":"object","properties":{"retention":{"type":"string","enum":["applied","forbidden","error"]},"drill":{"type":"object","properties":{"postgres":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"live":{"type":"number"},"restored":{"type":["number","null"]}},"required":["table","live","restored"],"additionalProperties":false}},"clickhouse":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"before":{"type":["number","null"]},"restored":{"type":["number","null"]},"after":{"type":["number","null"]}},"required":["table","before","restored","after"],"additionalProperties":false}},"problems":{"type":"array","items":{"type":"string"}}},"required":["postgres","clickhouse","problems"],"additionalProperties":false},"safetyBackup":{"type":"string"},"preRestoreDatabase":{"type":"string"},"pgMigrationsApplied":{"type":"number"},"chMigrationsApplied":{"type":"array","items":{"type":"string"}},"pgCommitted":{"type":"boolean"}},"additionalProperties":false},"triggeredBy":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["id","email"],"additionalProperties":false},{"type":"null"}]}},"required":["id","kind","trigger","status","name","parentRunId","scheduledFor","queuedAt","startedAt","finishedAt","postgres","clickhouse","error","details","triggeredBy"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/admin/backups/schedule":{"put":{"operationId":"setBackupSchedule","summary":"Set the backup schedule","tags":["Admin"],"description":"`schedule`: `off`, `every12h` (at `hour` and 12 hours later), `daily` (at `hour`) or `weekly` (on `weekday`, 0 = Sunday, at `hour`); `hour` is in UTC. Answers the saved schedule and the next run.\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"type":"string","enum":["off","every12h","daily","weekly"]},"hour":{"type":"integer","minimum":0,"maximum":23},"weekday":{"default":0,"type":"integer","minimum":0,"maximum":6}},"required":["schedule","hour"],"additionalProperties":false}}}},"security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schedule":{"type":"object","properties":{"schedule":{"type":"string","enum":["off","every12h","daily","weekly"]},"hour":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"weekday":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"updatedAt":{"type":["string","null"]},"updatedBy":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["id","email"],"additionalProperties":false},{"type":"null"}]}},"required":["schedule","hour","weekday","updatedAt","updatedBy"],"additionalProperties":false},"nextRunAt":{"type":["string","null"]}},"required":["schedule","nextRunAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/admin/jobs":{"get":{"operationId":"listAdminJobs","summary":"List job queues","tags":["Admin"],"description":"Each background job queue with its queued, active, failed, deferred and total counts, and the cron schedules.\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"queues":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"policy":{"type":"string"},"queuedCount":{"type":"number"},"activeCount":{"type":"number"},"failedCount":{"type":"number"},"deferredCount":{"type":"number"},"totalCount":{"type":"number"}},"required":["name","policy","queuedCount","activeCount","failedCount","deferredCount","totalCount"],"additionalProperties":false}},"schedules":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"cron":{"type":"string"},"timezone":{"type":"string"}},"required":["name","cron","timezone"],"additionalProperties":false}}},"required":["queues","schedules"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/admin/orgs":{"get":{"operationId":"listAdminOrgs","summary":"List all organizations","tags":["Admin"],"description":"Every organization of the instance with its member and live site counts, newest first, a page at a time (`meta.nextCursor`); `search` matches part of the name or slug, ignoring case.\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"search","required":false},{"schema":{"type":"string","maxLength":2200},"in":"query","name":"cursor","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false}],"security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"createdAt":{"type":"string"},"members":{"type":"number"},"sites":{"type":"number"}},"required":["id","name","slug","createdAt","members","sites"],"additionalProperties":false}},"meta":{"type":"object","properties":{"nextCursor":{"type":["string","null"]}},"required":["nextCursor"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/admin/sites":{"get":{"operationId":"listAdminSites","summary":"List all sites","tags":["Admin"],"description":"Every site of the instance with its organization, newest first, a page at a time (`meta.nextCursor`); `search` matches part of the name, domain or id, ignoring case, and `deleted=true` adds deleted sites.\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"search","required":false},{"schema":{"type":"string","maxLength":2200},"in":"query","name":"cursor","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"deleted","required":false}],"security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"orgId":{"type":"string"},"orgName":{"type":"string"},"createdAt":{"type":"string"},"deletedAt":{"type":["string","null"]}},"required":["id","name","domain","orgId","orgName","createdAt","deletedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"nextCursor":{"type":["string","null"]}},"required":["nextCursor"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/admin/stats":{"get":{"operationId":"getAdminStats","summary":"Get instance statistics","tags":["Admin"],"description":"This process's counters since it started (ingest, the event writer, replay; `meta.instance` names the replica that answered) and the size of each ClickHouse table.\n\nRequires a signed-in system administrator (session cookie). API keys and share links: 401; other signed-in users: 403.","security":[{"session":[]}],"x-pilotfox-access":{"kind":"systemAdmin"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"uptimeSeconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ingest":{"type":"object","properties":{"accepted":{"type":"number"},"ignored":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"invalid":{"type":"number"},"unknownSite":{"type":"number"},"rateLimited":{"type":"number"},"forbiddenSite":{"type":"number"},"tsOutOfRange":{"type":"number"},"bots":{"type":"object","properties":{"observed":{"type":"number"},"blocked":{"type":"number"},"byLayer":{"type":"object","properties":{"ua":{"type":"number"},"headers":{"type":"number"},"client":{"type":"number"},"asn":{"type":"number"},"rate":{"type":"number"}},"required":["ua","headers","client","asn","rate"],"additionalProperties":false}},"required":["observed","blocked","byLayer"],"additionalProperties":false}},"required":["accepted","ignored","invalid","unknownSite","rateLimited","forbiddenSite","tsOutOfRange","bots"],"additionalProperties":false},"writer":{"type":"object","properties":{"buffered":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"inflight":{"type":"number"},"inserted":{"type":"number"},"retries":{"type":"number"},"spooledRows":{"type":"number"},"replayedRows":{"type":"number"},"droppedRows":{"type":"number"},"spoolFiles":{"type":"number"},"spoolRows":{"type":"number"},"failedFiles":{"type":"number"},"degraded":{"type":"boolean"}},"required":["buffered","inflight","inserted","retries","spooledRows","replayedRows","droppedRows","spoolFiles","spoolRows","failedFiles","degraded"],"additionalProperties":false},"replay":{"type":"object","properties":{"accepted":{"type":"number"},"dropped":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"decode":{"type":"object","properties":{"timeouts":{"type":"number"},"outOfMemory":{"type":"number"}},"required":["timeouts","outOfMemory"],"additionalProperties":false}},"required":["accepted","dropped","decode"],"additionalProperties":false},"clickhouse":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"rows":{"type":"number"},"bytes":{"type":"number"}},"required":["table","rows","bytes"],"additionalProperties":false}}},"required":["uptimeSeconds","ingest","writer","replay","clickhouse"],"additionalProperties":false},"meta":{"type":"object","properties":{"instance":{"type":"string"}},"required":["instance"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/affiliate-portal":{"get":{"operationId":"getAffiliatePortal","summary":"Get the affiliate portal","tags":["Affiliates"],"description":"An affiliate's own aggregates, opened by the token in the `x-affiliate-token` header (minted by `POST /sites/{siteId}/affiliates/{id}/share`; no cookie or other credential is read). Window parameters as everywhere, the last 30 days when none is given. 401 for an unknown or revoked token; refused tokens count against the client's credential budget like share tokens (429 once spent). Money is in the site's currency. 60 requests a minute per client.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false}],"security":[{"affiliateToken":[]}],"x-pilotfox-access":{"kind":"public"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affiliate":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"commission_percent":{"type":"number"}},"required":["name","slug","commission_percent"],"additionalProperties":false},"site":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"}},"required":["name","domain"],"additionalProperties":false},"link":{"type":"string"},"currency":{"type":"string"},"totals":{"type":"object","properties":{"visits":{"type":"number"},"visitors":{"type":"number"},"payments":{"type":["number","null"]},"revenue":{"type":["number","null"]},"commission":{"type":["number","null"]},"conversion_rate":{"type":["number","null"]}},"required":["visits","visitors","payments","revenue","commission","conversion_rate"],"additionalProperties":false},"series":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"visits":{"type":"number"},"visitors":{"type":"number"},"payments":{"type":["number","null"]},"revenue":{"type":["number","null"]}},"required":["t","visits","visitors","payments","revenue"],"additionalProperties":false}},"landing_pages":{"type":"array","items":{"type":"object","properties":{"pathname":{"type":"string"},"visits":{"type":"number"}},"required":["pathname","visits"],"additionalProperties":false}}},"required":["affiliate","site","link","currency","totals","series","landing_pages"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/config":{"get":{"operationId":"getConfig","summary":"Get the instance configuration","tags":["System"],"description":"What the web app needs before sign-in: the sign-up policy, the social sign-in providers, whether MCP (and its OAuth) and session replay are available, the map settings and the version.\n\nPublic: no credential needed.","security":[],"x-pilotfox-access":{"kind":"public"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"signupPolicy":{"type":"string","enum":["invite_only","open"]},"socialProviders":{"type":"array","items":{"type":"string"}},"mcpEnabled":{"type":"boolean"},"mcpOAuth":{"type":"boolean"},"replayAvailable":{"type":"boolean"},"maps":{"type":"object","properties":{"defaultProvider":{"type":"string","enum":["maplibre","mapbox"]},"providers":{"type":"object","properties":{"maplibre":{"type":"object","properties":{"styleUrl":{"type":"string"},"styleUrlDark":{"type":"string"},"attributions":{"type":"array","items":{"type":"string"}}},"required":["styleUrl","styleUrlDark","attributions"],"additionalProperties":false},"mapbox":{"type":"object","properties":{"accessToken":{"type":"string"},"styleUrl":{"type":"string"},"attributions":{"type":"array","items":{"type":"string"}}},"required":["accessToken","styleUrl","attributions"],"additionalProperties":false}},"required":["maplibre"],"additionalProperties":false},"boundaries":{"anyOf":[{"type":"object","properties":{"tiles":{"type":"array","prefixItems":[{"type":"string"}],"items":false,"minItems":1,"maxItems":1},"minzoom":{"type":"number"},"maxzoom":{"type":"number"},"sourceLayers":{"type":"object","properties":{"countries":{"type":"string","enum":["countries"]},"regions":{"type":"string","enum":["regions"]}},"required":["countries","regions"],"additionalProperties":false},"promoteId":{"type":"string","enum":["code"]}},"required":["tiles","minzoom","maxzoom","sourceLayers","promoteId"],"additionalProperties":false},{"type":"null"}]},"attributions":{"type":"array","items":{"type":"string"}}},"required":["defaultProvider","providers","boundaries","attributions"],"additionalProperties":false},"version":{"type":"string"}},"required":["signupPolicy","socialProviders","mcpEnabled","mcpOAuth","replayAvailable","maps","version"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/health":{"get":{"operationId":"getHealth","summary":"Check liveness","tags":["System"],"description":"Answers `{ \"data\": { \"ok\": true } }` while the process serves requests: it checks no dependency and has no rate limit, for load balancers and orchestrators.\n\nPublic: no credential needed.","security":[],"x-pilotfox-access":{"kind":"public"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/ingest/events":{"post":{"operationId":"ingestEvents","summary":"Send events","tags":["Ingest"],"description":"Records a batch of 1 to 500 events from a server, through the same pipeline as the tracker's (400 when the body is not `{ events: [...] }` of that size). Each event names its site (a site of the key's organization within its sites) and may carry the visitor's `ip` (else the request's address), `user_agent` (never the request's own) or `anonymous_id`, and `ts` (7 days back to 5 minutes ahead; default now). The answer counts the events taken and lists the refused ones by index: `invalid`, `forbidden_site` or `ts_out_of_range`; excluded or bot events count as taken, never saying why.\n\nRequires an API key holding `ingest:write`. Session cookies and share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"site":{"type":"string","minLength":1},"type":{"type":"string","enum":["pageview","event","outbound","click","form","input","copy","error","vital"]},"url":{"description":"Absolute; the site's home page when absent","type":"string","minLength":1},"ref":{"type":"string"},"title":{"type":"string"},"name":{"type":"string"},"props":{},"sw":{"type":"number"},"sh":{"type":"number"},"lang":{"type":"string"},"uid":{"type":"string"},"tag":{"type":"string"},"vitals":{"type":"object","properties":{"lcp":{"type":"number"},"cls":{"type":"number"},"inp":{"type":"number"},"fcp":{"type":"number"},"ttfb":{"type":"number"}}},"err":{"type":"object","properties":{"message":{"type":"string"},"stack":{"type":"string"},"file":{"type":"string"},"line":{"type":"number"},"col":{"type":"number"}}},"bs":{"type":"number"},"bm":{"type":"number"},"aid":{"type":"string"},"ip":{"type":"string"},"user_agent":{"type":"string"},"anonymous_id":{"type":"string"},"ts":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["site","type"]}}},"required":["events"]}}}},"security":[{"apiKey":["ingest:write"]},{"apiKeyBearer":["ingest:write"]}],"x-pilotfox-access":{"kind":"apiKeyOnly","permission":"ingest:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"accepted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rejected":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string","enum":["invalid","forbidden_site","ts_out_of_range"]}},"required":["index","code"],"additionalProperties":false}}},"required":["accepted","rejected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/ingest/identify":{"post":{"operationId":"ingestIdentify","summary":"Identify a visitor from a server","tags":["Ingest"],"description":"Links a visitor, named by `anonymous_id` or by the `ip` and `user_agent` its browser events carry (400 without either), to the user id `uid`, with optional traits; an `email` trait sent here can link payments to the user. 404 for a site the key cannot write to; 204 also when the site's exclusions or bot rules drop it.\n\nRequires an API key holding `ingest:write`. Session cookies and share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"string","minLength":1},"uid":{"type":"string"},"traits":{},"bs":{"type":"number"},"bm":{"type":"number"},"ip":{"type":"string"},"user_agent":{"type":"string"},"anonymous_id":{"type":"string"}},"required":["site","uid"]}}}},"security":[{"apiKey":["ingest:write"]},{"apiKeyBearer":["ingest:write"]}],"x-pilotfox-access":{"kind":"apiKeyOnly","permission":"ingest:write"},"responses":{"204":{"description":"No Content"}}}},"/api/v1/me":{"get":{"operationId":"getMe","summary":"Get the signed-in user","tags":["Account"],"description":"The user, whether they are a system administrator and may create one more organization, their active organization, and each membership with its role and site access.\n\nRequires a signed-in user (session cookie). API keys and share links: 401.","security":[{"session":[]}],"x-pilotfox-access":{"kind":"authenticated"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"emailVerified":{"type":"boolean"},"twoFactorEnabled":{"type":"boolean"}},"required":["id","email","name","emailVerified","twoFactorEnabled"],"additionalProperties":false},"isSystemAdmin":{"type":"boolean"},"canCreateOrganization":{"type":"boolean"},"activeOrganizationId":{"type":["string","null"]},"memberships":{"type":"array","items":{"type":"object","properties":{"orgId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"type":"string","enum":["owner","admin","editor","member","viewer"]},"siteAccess":{"type":"string","enum":["all","restricted"]}},"required":["orgId","name","slug","role","siteAccess"],"additionalProperties":false}}},"required":["user","isSystemAdmin","canCreateOrganization","activeOrganizationId","memberships"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/me/deletion":{"get":{"operationId":"getAccountDeletion","summary":"Get what deleting the account would do","tags":["Account"],"description":"Read-only. The organizations deleted with the account (its only member), with their site count; those that block it (other members, and the user is the only owner); those the user leaves; whether the user is the instance's last administrator or an administrator signed in as the user (both block it); and what confirms it: the password, or for an account without one a sign-in in the last 10 minutes.\n\nRequires a signed-in user (session cookie). API keys and share links: 401.","security":[{"session":[]}],"x-pilotfox-access":{"kind":"authenticated"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"allowed":{"type":"boolean","description":"Nothing stops it: not an impersonation session, not the last administrator, no organization blocks it"},"impersonated":{"type":"boolean","description":"An administrator is signed in as the user: never allowed"},"lastAdmin":{"type":"boolean","description":"The user is the instance's only system administrator: never allowed"},"confirmation":{"type":"string","enum":["password","recentSignIn"],"description":"What confirms it: the account's password, or for an account without one a recent sign-in"},"recentSignInUntil":{"description":"recentSignIn: until when this session may delete the account (ISO 8601); null for password","type":["string","null"]},"signInAgain":{"type":"boolean","description":"recentSignIn, and that time has passed: sign in again first"},"organizations":{"type":"object","properties":{"deleted":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"sites":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Its sites, not counting those being deleted"}},"required":["id","name","slug","sites"],"additionalProperties":false},"description":"The user is their only member: deleted with the account, with their sites and data"},"blocking":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"],"additionalProperties":false},"description":"Other members, and the user is the only owner: another member must become an owner first"},"left":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"],"additionalProperties":false},"description":"The user's membership is removed"}},"required":["deleted","blocking","left"],"additionalProperties":false}},"required":["allowed","impersonated","lastAdmin","confirmation","recentSignInUntil","signInAgain","organizations"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/me/reports":{"get":{"operationId":"listMyReportSubscriptions","summary":"List my email report subscriptions","tags":["Account"],"description":"Every site the signed-in user may read, with whether they get its weekly and monthly email reports.\n\nRequires a signed-in user (session cookie). API keys and share links: 401.","security":[{"session":[]}],"x-pilotfox-access":{"kind":"authenticated"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"siteId":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"organization":{"type":"string"},"weekly":{"type":"boolean"},"monthly":{"type":"boolean"}},"required":["siteId","name","domain","organization","weekly","monthly"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/orgs/{orgId}/api-keys":{"get":{"operationId":"listApiKeys","summary":"List API keys","tags":["API keys"],"description":"Every key of the organization, newest first, with its permissions, sites (`siteIds` null: every site) and dates; never the key itself (`start` is its first characters). `lastUsedAt` can lag by up to a minute.\n\nRequires `apiKey:read` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true}],"security":[{"apiKey":["apiKey:read"]},{"apiKeyBearer":["apiKey:read"]},{"session":["apiKey:read"]}],"x-pilotfox-access":{"kind":"org","permission":"apiKey:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"start":{"type":["string","null"]},"permissions":{"type":"object","propertyNames":{"type":"string","enum":["organization","member","invitation","team","ac","site","analytics","sessions","users","replay","goals","funnels","segments","annotations","imports","exports","shareLink","apiKey","ingest","revenue","affiliates","searchConsole"]},"additionalProperties":{"readOnly":true,"type":"array","items":{"type":"string"}}},"siteIds":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","start","permissions","siteIds","createdAt","lastUsedAt","expiresAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"operationId":"createApiKey","summary":"Create an API key","tags":["API keys"],"description":"Only a signed-in member can create a key: an API key gets 403 here whatever it holds (keys never create keys), so the `apiKey:create` below must come from the member's role. The new key holds the requested `permissions` that role can grant (admins and owners may also grant the API-key-only `ingest:write` and `revenue:write`; 400 when none can be granted), on the sites in `siteIds` (400 for an id that is not a live site of the organization), or on every site of the organization when it is absent. `expiresInDays` (1 to 3650) sets an expiry; none by default. This answer is the only one that carries `key`. 409 once the organization has its maximum of active keys (`API_KEY_MAX_PER_ORG`, 50 by default).\n\nRequires `apiKey:create` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"permissions":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"siteIds":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string"}},"expiresInDays":{"type":"integer","minimum":1,"maximum":3650}},"required":["name","permissions"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true}],"security":[{"apiKey":["apiKey:create"]},{"apiKeyBearer":["apiKey:create"]},{"session":["apiKey:create"]}],"x-pilotfox-access":{"kind":"org","permission":"apiKey:create"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"start":{"type":["string","null"]},"permissions":{"type":"object","propertyNames":{"type":"string","enum":["organization","member","invitation","team","ac","site","analytics","sessions","users","replay","goals","funnels","segments","annotations","imports","exports","shareLink","apiKey","ingest","revenue","affiliates","searchConsole"]},"additionalProperties":{"readOnly":true,"type":"array","items":{"type":"string"}}},"siteIds":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","key","start","permissions","siteIds","expiresAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/orgs/{orgId}/api-keys/{keyId}":{"delete":{"operationId":"deleteApiKey","summary":"Delete an API key","tags":["API keys"],"description":"Deletes the key: it is refused from then on, though a verification already cached can let it through for up to 60 seconds. 404 when the organization has no such key.\n\nRequires `apiKey:delete` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true},{"schema":{"type":"string"},"in":"path","name":"keyId","required":true}],"security":[{"apiKey":["apiKey:delete"]},{"apiKeyBearer":["apiKey:delete"]},{"session":["apiKey:delete"]}],"x-pilotfox-access":{"kind":"org","permission":"apiKey:delete"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/orgs/{orgId}/members/{memberId}/site-access":{"get":{"operationId":"getMemberSiteAccess","summary":"Get a member's site access","tags":["Organizations"],"description":"`all` or `restricted` (owners and admins always read `all`), and the member's own site grants on live sites. `memberId` is the id of the person's membership in the organization (its member record), not their user id.\n\nRequires `member:update` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true},{"schema":{"type":"string"},"in":"path","name":"memberId","required":true}],"security":[{"apiKey":["member:update"]},{"apiKeyBearer":["member:update"]},{"session":["member:update"]}],"x-pilotfox-access":{"kind":"org","permission":"member:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"siteAccess":{"type":"string","enum":["all","restricted"]},"grants":{"type":"array","items":{"type":"object","properties":{"siteId":{"type":"string"},"role":{"type":"string","enum":["editor","member","viewer"]}},"required":["siteId","role"],"additionalProperties":false}}},"required":["siteAccess","grants"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"put":{"operationId":"setMemberSiteAccess","summary":"Set a member's site access","tags":["Organizations"],"description":"`all`: every site of the organization, with the higher of the member's role and a grant; `restricted`: only the sites granted to them (in `grants`, or through a team), each with the highest role granted. Replaces the member's own grants. 400 for restricting an owner or admin, or for a site named twice or not a live site of the organization.\n\nRequires `member:update` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"siteAccess":{"type":"string","enum":["all","restricted"]},"grants":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"siteId":{"type":"string"},"role":{"type":"string","enum":["editor","member","viewer"]}},"required":["siteId","role"],"additionalProperties":false}}},"required":["siteAccess","grants"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true},{"schema":{"type":"string"},"in":"path","name":"memberId","required":true}],"security":[{"apiKey":["member:update"]},{"apiKeyBearer":["member:update"]},{"session":["member:update"]}],"x-pilotfox-access":{"kind":"org","permission":"member:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"siteAccess":{"type":"string","enum":["all","restricted"]},"grants":{"type":"array","items":{"type":"object","properties":{"siteId":{"type":"string"},"role":{"type":"string","enum":["editor","member","viewer"]}},"required":["siteId","role"],"additionalProperties":false}}},"required":["siteAccess","grants"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/orgs/{orgId}/overview":{"get":{"operationId":"getOrgOverview","summary":"Get the organization overview","tags":["Organizations"],"description":"One card per site the caller sees, most visitors first, with its visitors, sessions and a visitors sparkline, and the totals over those sites (each visitor counted once). Window keys only (no filters or comparison); days and buckets are in UTC unless `tz` names another time zone.\n\nRequires `analytics:read` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: allowed, and see only those sites. Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string"},"in":"path","name":"orgId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]}],"x-pilotfox-access":{"kind":"org","permission":"analytics:read","siteScopedKeys":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The site's public id"},"name":{"type":"string"},"domain":{"type":"string"},"visitors":{"type":"number"},"sessions":{"type":"number"},"series":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"visitors":{"type":"number"}},"required":["t","visitors"],"additionalProperties":false}}},"required":["id","name","domain","visitors","sessions","series"],"additionalProperties":false}},"totals":{"type":"object","properties":{"visitors":{"type":"number"},"sessions":{"type":"number"}},"required":["visitors","sessions"],"additionalProperties":false}},"required":["sites","totals"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/orgs/{orgId}/search-console":{"get":{"operationId":"getOrgSearchConsole","summary":"Get the organization's Search Console connections","tags":["Search Console"],"description":"Whether Google OAuth is configured on the instance, the redirect URI and scope to register with Google, and the organization's Google connections.\n\nRequires `organization:update` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true}],"security":[{"apiKey":["organization:update"]},{"apiKeyBearer":["organization:update"]},{"session":["organization:update"]}],"x-pilotfox-access":{"kind":"org","permission":"organization:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"configured":{"type":"boolean"},"source":{"anyOf":[{"type":"string","enum":["dedicated","sign-in"]},{"type":"null"}],"description":"which OAuth client env vars are in use"},"redirectUri":{"type":"string"},"scope":{"type":"string"},"connections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"googleEmail":{"type":"string"},"status":{"type":"string","enum":["active","needs_reconnect"]},"lastError":{"type":["string","null"]},"lastErrorAt":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"createdBy":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}},"required":["name","email"],"additionalProperties":false},{"type":"null"}]},"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["id","googleEmail","status","lastError","lastErrorAt","scopes","createdAt","createdBy","sites"],"additionalProperties":false}}},"required":["configured","source","redirectUri","scope","connections"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/orgs/{orgId}/search-console/connect":{"post":{"operationId":"connectSearchConsole","summary":"Start a Search Console connection","tags":["Search Console"],"description":"Starts Google's OAuth consent for a new connection and answers the URL to send the browser to; Google then returns to the OAuth callback, which sends the browser on to `returnTo` (a path of the web app). Signed-in users only (403 for API keys and MCP tokens); 503 when Google OAuth is not configured.\n\nRequires `organization:update` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"returnTo":{"type":"string","maxLength":512}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true}],"security":[{"apiKey":["organization:update"]},{"apiKeyBearer":["organization:update"]},{"session":["organization:update"]}],"x-pilotfox-access":{"kind":"org","permission":"organization:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string","description":"Google's consent page; send the browser there"}},"required":["url"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/orgs/{orgId}/search-console/connections/{connectionId}":{"delete":{"operationId":"deleteSearchConsoleConnection","summary":"Delete a Search Console connection","tags":["Search Console"],"description":"Deletes the connection and, when no other connection uses the same Google account, revokes its grant at Google (`revoked`).\n\nRequires `organization:update` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true},{"schema":{"type":"string"},"in":"path","name":"connectionId","required":true}],"security":[{"apiKey":["organization:update"]},{"apiKeyBearer":["organization:update"]},{"session":["organization:update"]}],"x-pilotfox-access":{"kind":"org","permission":"organization:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"revoked":{"type":"boolean"}},"required":["deleted","revoked"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/orgs/{orgId}/sites":{"get":{"operationId":"listSites","summary":"List sites","tags":["Sites"],"description":"The organization's sites the caller sees: a user the sites they have a role on, an API key the sites it is limited to (all when it is not), each with the caller's role and permissions there.\n\nRequires `site:read` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: allowed, and see only those sites. Share links: 401.","security":[{"apiKey":["site:read"]},{"apiKeyBearer":["site:read"]},{"session":["site:read"]}],"x-pilotfox-access":{"kind":"org","permission":"site:read","siteScopedKeys":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"timezone":{"type":"string"},"kind":{"type":"string","enum":["web","app"]},"settings":{"type":"object","properties":{"tracking":{"type":"object","properties":{"initialPageview":{"default":true,"type":"boolean"},"spa":{"default":true,"type":"boolean"},"hashRouting":{"default":false,"type":"boolean"},"querystring":{"default":true,"type":"boolean"},"outbound":{"default":true,"type":"boolean"},"clicks":{"default":false,"type":"boolean"},"forms":{"default":false,"type":"boolean"},"copy":{"default":false,"type":"boolean"},"inputs":{"default":false,"type":"boolean"},"errors":{"default":false,"type":"boolean"},"vitals":{"default":false,"type":"boolean"},"paymentLinks":{"default":true,"type":"boolean"}},"required":["initialPageview","spa","hashRouting","querystring","outbound","clicks","forms","copy","inputs","errors","vitals","paymentLinks"],"additionalProperties":false},"replay":{"type":"object","properties":{"enabled":{"default":false,"type":"boolean"},"sampleRate":{"default":100,"type":"number","minimum":0,"maximum":100},"maskAllInputs":{"default":true,"type":"boolean"},"maskTextSelector":{"default":null,"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"blockSelector":{"default":null,"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"minDurationSeconds":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["enabled","sampleRate","maskAllInputs","maskTextSelector","blockSelector","minDurationSeconds"],"additionalProperties":false},"identity":{"type":"object","properties":{"mode":{"default":"stable","type":"string","enum":["stable","daily"]}},"required":["mode"],"additionalProperties":false},"privacy":{"type":"object","properties":{"storeQuerystringParams":{"default":"all","type":"string","enum":["all","utm_only","none"]},"stripParams":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"respectGpc":{"default":true,"type":"boolean"}},"required":["storeQuerystringParams","stripParams","respectGpc"],"additionalProperties":false},"allowedHostnames":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","maxLength":253,"pattern":"^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$"}},"exclusions":{"type":"object","properties":{"ips":{"default":[],"maxItems":200,"type":"array","items":{"type":"string"}},"countries":{"default":[],"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"paths":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":512}},"userAgents":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":256}},"asns":{"default":[],"maxItems":100,"type":"array","items":{"type":"integer","minimum":1,"maximum":4294967295}}},"required":["ips","countries","paths","userAgents","asns"],"additionalProperties":false},"bots":{"type":"object","properties":{"block":{"default":true,"type":"boolean"}},"required":["block"],"additionalProperties":false},"revenue":{"type":"object","properties":{"currency":{"default":"usd","type":"string","pattern":"^[a-z]{3}$"},"storeCustomerEmail":{"default":false,"type":"boolean"},"attributionModel":{"default":"last_non_direct","type":"string","enum":["last_non_direct","first_visit","last_visit"]},"attributionWindowDays":{"default":90,"type":"integer","minimum":1,"maximum":365}},"required":["currency","storeCustomerEmail","attributionModel","attributionWindowDays"],"additionalProperties":false},"affiliates":{"type":"object","properties":{"params":{"default":["ref"],"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,32}$"}},"windowDays":{"default":30,"type":"integer","minimum":1,"maximum":365}},"required":["params","windowDays"],"additionalProperties":false},"public":{"default":false,"type":"boolean"},"primaryGoalId":{"default":null,"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["tracking","replay","identity","privacy","allowedHostnames","exclusions","bots","revenue","affiliates","public","primaryGoalId"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"role":{"anyOf":[{"type":"string","enum":["owner","admin","editor","member","viewer"]},{"type":"null"}]},"permissions":{"type":"object","propertyNames":{"type":"string","enum":["organization","member","invitation","team","ac","site","analytics","sessions","users","replay","goals","funnels","segments","annotations","imports","exports","shareLink","apiKey","ingest","revenue","affiliates","searchConsole"]},"additionalProperties":{"readOnly":true,"type":"array","items":{"type":"string"}}}},"required":["id","name","domain","timezone","kind","settings","createdAt","role","permissions"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"operationId":"createSite","summary":"Create a site","tags":["Sites"],"description":"A new site of the organization. `domain` is stored as its host (and port, if any): scheme, path and query dropped, lowercased, an international name as punycode. `timezone` is an IANA name (`UTC` by default), `kind` is `web` (default) or `app`, and `settings` is applied over the defaults. Creating it public (`settings.public: true`) also needs the caller's own `analytics:read` (403 otherwise, and nothing is created). Answers the site as `GET /sites/{siteId}` shows it to the caller.\n\nRequires `site:create` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"domain":{"type":"string"},"kind":{"type":"string","enum":["web","app"]},"timezone":{"type":"string"},"settings":{"type":"object","properties":{"tracking":{"type":"object","properties":{"initialPageview":{"type":"boolean"},"spa":{"type":"boolean"},"hashRouting":{"type":"boolean"},"querystring":{"type":"boolean"},"outbound":{"type":"boolean"},"clicks":{"type":"boolean"},"forms":{"type":"boolean"},"copy":{"type":"boolean"},"inputs":{"type":"boolean"},"errors":{"type":"boolean"},"vitals":{"type":"boolean"},"paymentLinks":{"type":"boolean"}},"additionalProperties":false},"replay":{"type":"object","properties":{"enabled":{"type":"boolean"},"sampleRate":{"type":"number","minimum":0,"maximum":100},"maskAllInputs":{"type":"boolean"},"maskTextSelector":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"blockSelector":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"minDurationSeconds":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false},"identity":{"type":"object","properties":{"mode":{"type":"string","enum":["stable","daily"]}},"additionalProperties":false},"privacy":{"type":"object","properties":{"storeQuerystringParams":{"type":"string","enum":["all","utm_only","none"]},"stripParams":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"respectGpc":{"type":"boolean"}},"additionalProperties":false},"allowedHostnames":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":253,"pattern":"^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$"}},"exclusions":{"type":"object","properties":{"ips":{"maxItems":200,"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"paths":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":512}},"userAgents":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":256}},"asns":{"maxItems":100,"type":"array","items":{"type":"integer","minimum":1,"maximum":4294967295}}},"additionalProperties":false},"bots":{"type":"object","properties":{"block":{"type":"boolean"}},"additionalProperties":false},"revenue":{"type":"object","properties":{"currency":{"type":"string","pattern":"^[a-z]{3}$"},"storeCustomerEmail":{"type":"boolean"},"attributionModel":{"type":"string","enum":["last_non_direct","first_visit","last_visit"]},"attributionWindowDays":{"type":"integer","minimum":1,"maximum":365}},"additionalProperties":false},"affiliates":{"type":"object","properties":{"params":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,32}$"}},"windowDays":{"type":"integer","minimum":1,"maximum":365}},"additionalProperties":false},"public":{"type":"boolean"},"primaryGoalId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"additionalProperties":false}},"required":["name","domain"],"additionalProperties":false}}}},"security":[{"apiKey":["site:create"]},{"apiKeyBearer":["site:create"]},{"session":["site:create"]}],"x-pilotfox-access":{"kind":"org","permission":"site:create"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"timezone":{"type":"string"},"kind":{"type":"string","enum":["web","app"]},"settings":{"type":"object","properties":{"tracking":{"type":"object","properties":{"initialPageview":{"default":true,"type":"boolean"},"spa":{"default":true,"type":"boolean"},"hashRouting":{"default":false,"type":"boolean"},"querystring":{"default":true,"type":"boolean"},"outbound":{"default":true,"type":"boolean"},"clicks":{"default":false,"type":"boolean"},"forms":{"default":false,"type":"boolean"},"copy":{"default":false,"type":"boolean"},"inputs":{"default":false,"type":"boolean"},"errors":{"default":false,"type":"boolean"},"vitals":{"default":false,"type":"boolean"},"paymentLinks":{"default":true,"type":"boolean"}},"required":["initialPageview","spa","hashRouting","querystring","outbound","clicks","forms","copy","inputs","errors","vitals","paymentLinks"],"additionalProperties":false},"replay":{"type":"object","properties":{"enabled":{"default":false,"type":"boolean"},"sampleRate":{"default":100,"type":"number","minimum":0,"maximum":100},"maskAllInputs":{"default":true,"type":"boolean"},"maskTextSelector":{"default":null,"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"blockSelector":{"default":null,"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"minDurationSeconds":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["enabled","sampleRate","maskAllInputs","maskTextSelector","blockSelector","minDurationSeconds"],"additionalProperties":false},"identity":{"type":"object","properties":{"mode":{"default":"stable","type":"string","enum":["stable","daily"]}},"required":["mode"],"additionalProperties":false},"privacy":{"type":"object","properties":{"storeQuerystringParams":{"default":"all","type":"string","enum":["all","utm_only","none"]},"stripParams":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"respectGpc":{"default":true,"type":"boolean"}},"required":["storeQuerystringParams","stripParams","respectGpc"],"additionalProperties":false},"allowedHostnames":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","maxLength":253,"pattern":"^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$"}},"exclusions":{"type":"object","properties":{"ips":{"default":[],"maxItems":200,"type":"array","items":{"type":"string"}},"countries":{"default":[],"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"paths":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":512}},"userAgents":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":256}},"asns":{"default":[],"maxItems":100,"type":"array","items":{"type":"integer","minimum":1,"maximum":4294967295}}},"required":["ips","countries","paths","userAgents","asns"],"additionalProperties":false},"bots":{"type":"object","properties":{"block":{"default":true,"type":"boolean"}},"required":["block"],"additionalProperties":false},"revenue":{"type":"object","properties":{"currency":{"default":"usd","type":"string","pattern":"^[a-z]{3}$"},"storeCustomerEmail":{"default":false,"type":"boolean"},"attributionModel":{"default":"last_non_direct","type":"string","enum":["last_non_direct","first_visit","last_visit"]},"attributionWindowDays":{"default":90,"type":"integer","minimum":1,"maximum":365}},"required":["currency","storeCustomerEmail","attributionModel","attributionWindowDays"],"additionalProperties":false},"affiliates":{"type":"object","properties":{"params":{"default":["ref"],"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,32}$"}},"windowDays":{"default":30,"type":"integer","minimum":1,"maximum":365}},"required":["params","windowDays"],"additionalProperties":false},"public":{"default":false,"type":"boolean"},"primaryGoalId":{"default":null,"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["tracking","replay","identity","privacy","allowedHostnames","exclusions","bots","revenue","affiliates","public","primaryGoalId"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"role":{"anyOf":[{"type":"string","enum":["owner","admin","editor","member","viewer"]},{"type":"null"}]},"permissions":{"type":"object","propertyNames":{"type":"string","enum":["organization","member","invitation","team","ac","site","analytics","sessions","users","replay","goals","funnels","segments","annotations","imports","exports","shareLink","apiKey","ingest","revenue","affiliates","searchConsole"]},"additionalProperties":{"readOnly":true,"type":"array","items":{"type":"string"}}}},"required":["id","name","domain","timezone","kind","settings","createdAt","role","permissions"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"timezone":{"type":"string"}},"required":["id","name","domain","timezone"],"additionalProperties":false}]}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/orgs/{orgId}/teams/{teamId}/sites":{"get":{"operationId":"getTeamSiteAccess","summary":"Get a team's site grants","tags":["Organizations"],"description":"The sites the team grants, each with its role, and the user ids of the team's members.\n\nRequires `team:update` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true},{"schema":{"type":"string"},"in":"path","name":"teamId","required":true}],"security":[{"apiKey":["team:update"]},{"apiKeyBearer":["team:update"]},{"session":["team:update"]}],"x-pilotfox-access":{"kind":"org","permission":"team:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"object","properties":{"siteId":{"type":"string"},"role":{"type":"string","enum":["editor","member","viewer"]}},"required":["siteId","role"],"additionalProperties":false}},"members":{"type":"array","items":{"type":"string"}}},"required":["grants","members"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"put":{"operationId":"setTeamSiteAccess","summary":"Set a team's site grants","tags":["Organizations"],"description":"Replaces the sites the team grants its members, each with its role; 400 for a site named twice or not a live site of the organization.\n\nRequires `team:update` in the organization (an API key, or a signed-in member's role; a member restricted to some sites holds a viewer's permissions here). API keys limited to some sites: 403. Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"grants":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"siteId":{"type":"string"},"role":{"type":"string","enum":["editor","member","viewer"]}},"required":["siteId","role"],"additionalProperties":false}}},"required":["grants"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orgId","required":true},{"schema":{"type":"string"},"in":"path","name":"teamId","required":true}],"security":[{"apiKey":["team:update"]},{"apiKeyBearer":["team:update"]},{"session":["team:update"]}],"x-pilotfox-access":{"kind":"org","permission":"team:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"object","properties":{"siteId":{"type":"string"},"role":{"type":"string","enum":["editor","member","viewer"]}},"required":["siteId","role"],"additionalProperties":false}}},"required":["grants"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/ready":{"get":{"operationId":"getReadiness","summary":"Check readiness","tags":["System"],"description":"Runs every dependency check (2 seconds each at most): 200 with `status: ok` when all pass, 503 with `status: degraded` otherwise, with each check's result. The GeoIP and event writer fields (`geoip`, `geoFallback`, `spoolRows`, `failedFiles`, `degraded`) inform but never fail readiness.\n\nPublic: no credential needed.","security":[],"x-pilotfox-access":{"kind":"public"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"checks":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"geoip":{"type":"string","enum":["ok","missing","error"]},"geoFallback":{"type":"string","enum":["off","cloudflare"]},"spoolRows":{"type":"number"},"failedFiles":{"type":"number"},"degraded":{"type":"boolean"}},"required":["status","checks"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"checks":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"geoip":{"type":"string","enum":["ok","missing","error"]},"geoFallback":{"type":"string","enum":["off","cloudflare"]},"spoolRows":{"type":"number"},"failedFiles":{"type":"number"},"degraded":{"type":"boolean"}},"required":["status","checks"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/reports/unsubscribe":{"get":{"operationId":"getReportUnsubscribe","summary":"Check an unsubscribe link","tags":["Notifications"],"description":"What the unsubscribe link of a report email (`token`) unsubscribes from: the site, the period, and whether it is still subscribed. 404 for an unknown token.\n\nPublic: no credential needed.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256},"in":"query","name":"token","required":true}],"security":[],"x-pilotfox-access":{"kind":"public"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"siteName":{"type":"string"},"period":{"type":"string","enum":["weekly","monthly"]},"subscribed":{"type":"boolean"}},"required":["siteName","period","subscribed"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"post":{"operationId":"unsubscribeReport","summary":"Unsubscribe from an email report","tags":["Notifications"],"description":"RFC 8058 one-click unsubscribe: the token in the URL is the whole authorization; the form body mail clients send (`List-Unsubscribe=One-Click`) is read and ignored. 400 for an invalid link.\n\nPublic: no credential needed.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256},"in":"query","name":"token","required":true}],"security":[],"x-pilotfox-access":{"kind":"public"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"unsubscribed":{"type":"boolean"}},"required":["unsubscribed"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/search-console/oauth/callback":{"get":{"operationId":"searchConsoleOAuthCallback","summary":"Complete a Search Console connection","tags":["Search Console"],"description":"Where Google sends the browser back after consent. It checks that the same signed-in user started the flow and may still manage the organization, stores the connection, and redirects (303) to the web app with `?searchConsole=connected`, or `error` and a `reason`. Never JSON.","parameters":[{"schema":{"type":"string","maxLength":200},"in":"query","name":"state","required":false},{"schema":{"type":"string","maxLength":2048},"in":"query","name":"code","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"error","required":false}],"security":[{"session":[]}],"x-pilotfox-access":{"kind":"public"},"responses":{"303":{"description":"See Other: back to the web app, `?searchConsole=connected` or `=error&reason=…`"}}}},"/api/v1/share":{"get":{"operationId":"getSharedSite","summary":"Get what a share link opens","tags":["Share links"],"description":"The site (id, name, domain, time zone), scopes and expiry of the share link whose token the request carries (`x-share-token` or `?share=`); 401 without one.","security":[{"shareToken":[]},{"shareTokenQuery":[]}],"x-pilotfox-access":{"kind":"public"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"timezone":{"type":"string"}},"required":["id","name","domain","timezone"],"additionalProperties":false},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["site","scopes","expiresAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}":{"get":{"operationId":"getSite","summary":"Get a site","tags":["Sites"],"description":"Members and API keys holding `site:read` get the whole site (kind, settings, creation date, their role and permissions); everyone else (share links, the public on a public site) gets its id, name, domain and time zone only.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"timezone":{"type":"string"},"kind":{"type":"string","enum":["web","app"]},"settings":{"type":"object","properties":{"tracking":{"type":"object","properties":{"initialPageview":{"default":true,"type":"boolean"},"spa":{"default":true,"type":"boolean"},"hashRouting":{"default":false,"type":"boolean"},"querystring":{"default":true,"type":"boolean"},"outbound":{"default":true,"type":"boolean"},"clicks":{"default":false,"type":"boolean"},"forms":{"default":false,"type":"boolean"},"copy":{"default":false,"type":"boolean"},"inputs":{"default":false,"type":"boolean"},"errors":{"default":false,"type":"boolean"},"vitals":{"default":false,"type":"boolean"},"paymentLinks":{"default":true,"type":"boolean"}},"required":["initialPageview","spa","hashRouting","querystring","outbound","clicks","forms","copy","inputs","errors","vitals","paymentLinks"],"additionalProperties":false},"replay":{"type":"object","properties":{"enabled":{"default":false,"type":"boolean"},"sampleRate":{"default":100,"type":"number","minimum":0,"maximum":100},"maskAllInputs":{"default":true,"type":"boolean"},"maskTextSelector":{"default":null,"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"blockSelector":{"default":null,"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"minDurationSeconds":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["enabled","sampleRate","maskAllInputs","maskTextSelector","blockSelector","minDurationSeconds"],"additionalProperties":false},"identity":{"type":"object","properties":{"mode":{"default":"stable","type":"string","enum":["stable","daily"]}},"required":["mode"],"additionalProperties":false},"privacy":{"type":"object","properties":{"storeQuerystringParams":{"default":"all","type":"string","enum":["all","utm_only","none"]},"stripParams":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"respectGpc":{"default":true,"type":"boolean"}},"required":["storeQuerystringParams","stripParams","respectGpc"],"additionalProperties":false},"allowedHostnames":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","maxLength":253,"pattern":"^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$"}},"exclusions":{"type":"object","properties":{"ips":{"default":[],"maxItems":200,"type":"array","items":{"type":"string"}},"countries":{"default":[],"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"paths":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":512}},"userAgents":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":256}},"asns":{"default":[],"maxItems":100,"type":"array","items":{"type":"integer","minimum":1,"maximum":4294967295}}},"required":["ips","countries","paths","userAgents","asns"],"additionalProperties":false},"bots":{"type":"object","properties":{"block":{"default":true,"type":"boolean"}},"required":["block"],"additionalProperties":false},"revenue":{"type":"object","properties":{"currency":{"default":"usd","type":"string","pattern":"^[a-z]{3}$"},"storeCustomerEmail":{"default":false,"type":"boolean"},"attributionModel":{"default":"last_non_direct","type":"string","enum":["last_non_direct","first_visit","last_visit"]},"attributionWindowDays":{"default":90,"type":"integer","minimum":1,"maximum":365}},"required":["currency","storeCustomerEmail","attributionModel","attributionWindowDays"],"additionalProperties":false},"affiliates":{"type":"object","properties":{"params":{"default":["ref"],"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,32}$"}},"windowDays":{"default":30,"type":"integer","minimum":1,"maximum":365}},"required":["params","windowDays"],"additionalProperties":false},"public":{"default":false,"type":"boolean"},"primaryGoalId":{"default":null,"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["tracking","replay","identity","privacy","allowedHostnames","exclusions","bots","revenue","affiliates","public","primaryGoalId"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"role":{"anyOf":[{"type":"string","enum":["owner","admin","editor","member","viewer"]},{"type":"null"}]},"permissions":{"type":"object","propertyNames":{"type":"string","enum":["organization","member","invitation","team","ac","site","analytics","sessions","users","replay","goals","funnels","segments","annotations","imports","exports","shareLink","apiKey","ingest","revenue","affiliates","searchConsole"]},"additionalProperties":{"readOnly":true,"type":"array","items":{"type":"string"}}}},"required":["id","name","domain","timezone","kind","settings","createdAt","role","permissions"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"timezone":{"type":"string"}},"required":["id","name","domain","timezone"],"additionalProperties":false}]}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteSite","summary":"Delete a site","tags":["Sites"],"description":"The site disappears at once (202), and a job (`jobId`) erases its data a minute later; 503, with nothing changed, when background jobs are unavailable.\n\nRequires `site:delete` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:delete"]},{"apiKeyBearer":["site:delete"]},{"session":["site:delete"]}],"x-pilotfox-access":{"kind":"site","permission":"site:delete"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"jobId":{"type":"string"}},"required":["deleted","jobId"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"patch":{"operationId":"updateSite","summary":"Update a site","tags":["Sites"],"description":"Changes the fields sent; `settings` is merged into the current settings section by section (a field sent replaces that field, an array as a whole). Making the site public (`settings.public: true`) also needs the caller's own `analytics:read` on it (403 otherwise).\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"domain":{"type":"string"},"kind":{"type":"string","enum":["web","app"]},"timezone":{"type":"string"},"settings":{"type":"object","properties":{"tracking":{"type":"object","properties":{"initialPageview":{"type":"boolean"},"spa":{"type":"boolean"},"hashRouting":{"type":"boolean"},"querystring":{"type":"boolean"},"outbound":{"type":"boolean"},"clicks":{"type":"boolean"},"forms":{"type":"boolean"},"copy":{"type":"boolean"},"inputs":{"type":"boolean"},"errors":{"type":"boolean"},"vitals":{"type":"boolean"},"paymentLinks":{"type":"boolean"}},"additionalProperties":false},"replay":{"type":"object","properties":{"enabled":{"type":"boolean"},"sampleRate":{"type":"number","minimum":0,"maximum":100},"maskAllInputs":{"type":"boolean"},"maskTextSelector":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"blockSelector":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"minDurationSeconds":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false},"identity":{"type":"object","properties":{"mode":{"type":"string","enum":["stable","daily"]}},"additionalProperties":false},"privacy":{"type":"object","properties":{"storeQuerystringParams":{"type":"string","enum":["all","utm_only","none"]},"stripParams":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"respectGpc":{"type":"boolean"}},"additionalProperties":false},"allowedHostnames":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":253,"pattern":"^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$"}},"exclusions":{"type":"object","properties":{"ips":{"maxItems":200,"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"paths":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":512}},"userAgents":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":256}},"asns":{"maxItems":100,"type":"array","items":{"type":"integer","minimum":1,"maximum":4294967295}}},"additionalProperties":false},"bots":{"type":"object","properties":{"block":{"type":"boolean"}},"additionalProperties":false},"revenue":{"type":"object","properties":{"currency":{"type":"string","pattern":"^[a-z]{3}$"},"storeCustomerEmail":{"type":"boolean"},"attributionModel":{"type":"string","enum":["last_non_direct","first_visit","last_visit"]},"attributionWindowDays":{"type":"integer","minimum":1,"maximum":365}},"additionalProperties":false},"affiliates":{"type":"object","properties":{"params":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,32}$"}},"windowDays":{"type":"integer","minimum":1,"maximum":365}},"additionalProperties":false},"public":{"type":"boolean"},"primaryGoalId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"additionalProperties":false}},"additionalProperties":false}}}},"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"timezone":{"type":"string"},"kind":{"type":"string","enum":["web","app"]},"settings":{"type":"object","properties":{"tracking":{"type":"object","properties":{"initialPageview":{"default":true,"type":"boolean"},"spa":{"default":true,"type":"boolean"},"hashRouting":{"default":false,"type":"boolean"},"querystring":{"default":true,"type":"boolean"},"outbound":{"default":true,"type":"boolean"},"clicks":{"default":false,"type":"boolean"},"forms":{"default":false,"type":"boolean"},"copy":{"default":false,"type":"boolean"},"inputs":{"default":false,"type":"boolean"},"errors":{"default":false,"type":"boolean"},"vitals":{"default":false,"type":"boolean"},"paymentLinks":{"default":true,"type":"boolean"}},"required":["initialPageview","spa","hashRouting","querystring","outbound","clicks","forms","copy","inputs","errors","vitals","paymentLinks"],"additionalProperties":false},"replay":{"type":"object","properties":{"enabled":{"default":false,"type":"boolean"},"sampleRate":{"default":100,"type":"number","minimum":0,"maximum":100},"maskAllInputs":{"default":true,"type":"boolean"},"maskTextSelector":{"default":null,"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"blockSelector":{"default":null,"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"null"}]},"minDurationSeconds":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["enabled","sampleRate","maskAllInputs","maskTextSelector","blockSelector","minDurationSeconds"],"additionalProperties":false},"identity":{"type":"object","properties":{"mode":{"default":"stable","type":"string","enum":["stable","daily"]}},"required":["mode"],"additionalProperties":false},"privacy":{"type":"object","properties":{"storeQuerystringParams":{"default":"all","type":"string","enum":["all","utm_only","none"]},"stripParams":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":128}},"respectGpc":{"default":true,"type":"boolean"}},"required":["storeQuerystringParams","stripParams","respectGpc"],"additionalProperties":false},"allowedHostnames":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","maxLength":253,"pattern":"^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$"}},"exclusions":{"type":"object","properties":{"ips":{"default":[],"maxItems":200,"type":"array","items":{"type":"string"}},"countries":{"default":[],"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"paths":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":512}},"userAgents":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":256}},"asns":{"default":[],"maxItems":100,"type":"array","items":{"type":"integer","minimum":1,"maximum":4294967295}}},"required":["ips","countries","paths","userAgents","asns"],"additionalProperties":false},"bots":{"type":"object","properties":{"block":{"default":true,"type":"boolean"}},"required":["block"],"additionalProperties":false},"revenue":{"type":"object","properties":{"currency":{"default":"usd","type":"string","pattern":"^[a-z]{3}$"},"storeCustomerEmail":{"default":false,"type":"boolean"},"attributionModel":{"default":"last_non_direct","type":"string","enum":["last_non_direct","first_visit","last_visit"]},"attributionWindowDays":{"default":90,"type":"integer","minimum":1,"maximum":365}},"required":["currency","storeCustomerEmail","attributionModel","attributionWindowDays"],"additionalProperties":false},"affiliates":{"type":"object","properties":{"params":{"default":["ref"],"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,32}$"}},"windowDays":{"default":30,"type":"integer","minimum":1,"maximum":365}},"required":["params","windowDays"],"additionalProperties":false},"public":{"default":false,"type":"boolean"},"primaryGoalId":{"default":null,"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["tracking","replay","identity","privacy","allowedHostnames","exclusions","bots","revenue","affiliates","public","primaryGoalId"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"role":{"anyOf":[{"type":"string","enum":["owner","admin","editor","member","viewer"]},{"type":"null"}]},"permissions":{"type":"object","propertyNames":{"type":"string","enum":["organization","member","invitation","team","ac","site","analytics","sessions","users","replay","goals","funnels","segments","annotations","imports","exports","shareLink","apiKey","ingest","revenue","affiliates","searchConsole"]},"additionalProperties":{"readOnly":true,"type":"array","items":{"type":"string"}}}},"required":["id","name","domain","timezone","kind","settings","createdAt","role","permissions"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"timezone":{"type":"string"}},"required":["id","name","domain","timezone"],"additionalProperties":false}]}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/affiliates":{"get":{"operationId":"listAffiliates","summary":"List affiliates","tags":["Affiliates"],"description":"The site's affiliates, with whether each has a portal link (`shareEnabled`).\n\nRequires `affiliates:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["affiliates:read"]},{"apiKeyBearer":["affiliates:read"]},{"session":["affiliates:read"]}],"x-pilotfox-access":{"kind":"site","permission":"affiliates:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"commissionPercent":{"type":"number"},"shareEnabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","slug","commissionPercent","shareEnabled","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"operationId":"createAffiliate","summary":"Create an affiliate","tags":["Affiliates"],"description":"A named affiliate: visits whose landing URL carries its `slug` in one of the site's affiliate parameters (`settings.affiliates.params`) are its own; `commissionPercent` (0 to 100, two decimals at most; 0 by default) sets its share of their revenue. 400 for a slug with nothing left once normalized, 409 for a slug the site already has.\n\nRequires `affiliates:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"slug":{"type":"string","maxLength":256,"description":"Normalized as ingest normalizes the link's value: lowercased, only a-z 0-9 _ - kept, cut to 64"},"commissionPercent":{"type":"number","minimum":0,"maximum":100}},"required":["name","slug"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["affiliates:write"]},{"apiKeyBearer":["affiliates:write"]},{"session":["affiliates:write"]}],"x-pilotfox-access":{"kind":"site","permission":"affiliates:write"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"commissionPercent":{"type":"number"},"shareEnabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","slug","commissionPercent","shareEnabled","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/affiliates/stats":{"get":{"operationId":"getAffiliateStats","summary":"Get affiliate stats","tags":["Affiliates"],"description":"Visits, visitors, payments, revenue, commission and conversion rate per affiliate in the window (slugs seen without a registered affiliate included), with totals, in the site's currency. The money fields are null without `revenue:read`.\n\nRequires `affiliates:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["affiliates:read"]},{"apiKeyBearer":["affiliates:read"]},{"session":["affiliates:read"]}],"x-pilotfox-access":{"kind":"site","permission":"affiliates:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"currency":{"type":"string"},"totals":{"type":"object","properties":{"visits":{"type":"number"},"visitors":{"type":"number"},"payments":{"type":["number","null"]},"revenue":{"type":["number","null"]},"commission":{"type":["number","null"]},"conversion_rate":{"type":["number","null"]}},"required":["visits","visitors","payments","revenue","commission","conversion_rate"],"additionalProperties":false},"affiliates":{"type":"array","items":{"type":"object","properties":{"id":{"type":["string","null"]},"slug":{"type":"string"},"name":{"type":["string","null"]},"commission_percent":{"type":["number","null"]},"visits":{"type":"number"},"visitors":{"type":"number"},"payments":{"type":["number","null"]},"revenue":{"type":["number","null"]},"commission":{"type":["number","null"]},"conversion_rate":{"type":["number","null"]}},"required":["id","slug","name","commission_percent","visits","visitors","payments","revenue","commission","conversion_rate"],"additionalProperties":false}}},"required":["currency","totals","affiliates"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/affiliates/{id}":{"delete":{"operationId":"deleteAffiliate","summary":"Delete an affiliate","tags":["Affiliates"],"description":"Requires `affiliates:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["affiliates:write"]},{"apiKeyBearer":["affiliates:write"]},{"session":["affiliates:write"]}],"x-pilotfox-access":{"kind":"site","permission":"affiliates:write"},"responses":{"204":{"description":"No Content"}}},"patch":{"operationId":"updateAffiliate","summary":"Update an affiliate","tags":["Affiliates"],"description":"Changes the fields sent, with the rules of creating one (409 for a slug the site already has).\n\nRequires `affiliates:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"slug":{"type":"string","maxLength":256,"description":"Normalized as ingest normalizes the link's value: lowercased, only a-z 0-9 _ - kept, cut to 64"},"commissionPercent":{"type":"number","minimum":0,"maximum":100}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["affiliates:write"]},{"apiKeyBearer":["affiliates:write"]},{"session":["affiliates:write"]}],"x-pilotfox-access":{"kind":"site","permission":"affiliates:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"commissionPercent":{"type":"number"},"shareEnabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","slug","commissionPercent","shareEnabled","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/affiliates/{id}/report":{"get":{"operationId":"getAffiliateReport","summary":"Get an affiliate's report","tags":["Affiliates"],"description":"One affiliate's totals, time series, landing pages, referrers and countries in the window, and its link. Revenue, commission and recent payments need `revenue:read` too.\n\nRequires `affiliates:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["affiliates:read"]},{"apiKeyBearer":["affiliates:read"]},{"session":["affiliates:read"]}],"x-pilotfox-access":{"kind":"site","permission":"affiliates:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affiliate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"commissionPercent":{"type":"number"},"shareEnabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","slug","commissionPercent","shareEnabled","createdAt","updatedAt"],"additionalProperties":false},"currency":{"type":"string"},"link":{"type":"string"},"totals":{"type":"object","properties":{"visits":{"type":"number"},"visitors":{"type":"number"},"payments":{"type":["number","null"]},"revenue":{"type":["number","null"]},"commission":{"type":["number","null"]},"conversion_rate":{"type":["number","null"]}},"required":["visits","visitors","payments","revenue","commission","conversion_rate"],"additionalProperties":false},"series":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"visits":{"type":"number"},"visitors":{"type":"number"},"payments":{"type":["number","null"]},"revenue":{"type":["number","null"]}},"required":["t","visits","visitors","payments","revenue"],"additionalProperties":false}},"landing_pages":{"type":"array","items":{"type":"object","properties":{"pathname":{"type":"string"},"visits":{"type":"number"}},"required":["pathname","visits"],"additionalProperties":false}},"referrers":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"visits":{"type":"number"}},"required":["value","visits"],"additionalProperties":false}},"countries":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"visits":{"type":"number"}},"required":["value","visits"],"additionalProperties":false}},"recent_payments":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string"}},"required":["ts","amount","currency","status"],"additionalProperties":false}}},"required":["affiliate","currency","link","totals","series","landing_pages","referrers","countries","recent_payments"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/affiliates/{id}/share":{"post":{"operationId":"createAffiliatePortalToken","summary":"Create an affiliate portal link","tags":["Affiliates"],"description":"A new portal token for the affiliate (replacing any previous one) and its portal URL (`<PUBLIC_URL>/a/<token>`): this answer is the only one that carries it. Needs `revenue:read` too (the portal shows revenue and commission), and not with an MCP OAuth token (403).\n\nRequires `affiliates:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["affiliates:write"]},{"apiKeyBearer":["affiliates:write"]},{"session":["affiliates:write"]}],"x-pilotfox-access":{"kind":"site","permission":"affiliates:write"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string"},"url":{"type":"string"}},"required":["token","url"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"revokeAffiliatePortalToken","summary":"Revoke an affiliate portal link","tags":["Affiliates"],"description":"The portal token stops working at once.\n\nRequires `affiliates:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["affiliates:write"]},{"apiKeyBearer":["affiliates:write"]},{"session":["affiliates:write"]}],"x-pilotfox-access":{"kind":"site","permission":"affiliates:write"},"responses":{"204":{"description":"No Content"}}}},"/api/v1/sites/{siteId}/annotations":{"get":{"operationId":"listAnnotations","summary":"List annotations","tags":["Annotations"],"description":"The annotations of the site and the organization-wide ones that overlap the window, earliest first. Share links, public-site visitors and API keys without `annotations:read` see the public ones only, without `createdBy` null.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"startsAt":{"type":"string"},"endsAt":{"type":["string","null"]},"color":{"anyOf":[{"type":"string","enum":["blue","salmon","green","amber","red","violet","gray"]},{"type":"null"}]},"icon":{"type":["string","null"]},"isPublic":{"type":"boolean"},"scope":{"type":"string","enum":["site","org"]},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","description","startsAt","endsAt","color","icon","isPublic","scope","createdBy","createdAt","updatedAt"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"post":{"operationId":"createAnnotation","summary":"Create an annotation","tags":["Annotations"],"description":"A dated note, or a date range, on this site's charts or on every site of the organization (`scope: org`: for unrestricted members whose organization role grants `annotations:write`, and API keys not limited to some sites), private to members or public. An MCP tool may not make one public or organization-wide (403).\n\nRequires `annotations:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"startsAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"endsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"color":{"anyOf":[{"type":"string","enum":["blue","salmon","green","amber","red","violet","gray"]},{"type":"null"}]},"icon":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}]},"isPublic":{"default":false,"type":"boolean"},"scope":{"default":"site","type":"string","enum":["site","org"]}},"required":["title","startsAt"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["annotations:write"]},{"apiKeyBearer":["annotations:write"]},{"session":["annotations:write"]}],"x-pilotfox-access":{"kind":"site","permission":"annotations:write"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"startsAt":{"type":"string"},"endsAt":{"type":["string","null"]},"color":{"anyOf":[{"type":"string","enum":["blue","salmon","green","amber","red","violet","gray"]},{"type":"null"}]},"icon":{"type":["string","null"]},"isPublic":{"type":"boolean"},"scope":{"type":"string","enum":["site","org"]},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","description","startsAt","endsAt","color","icon","isPublic","scope","createdBy","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/annotations/{id}":{"delete":{"operationId":"deleteAnnotation","summary":"Delete an annotation","tags":["Annotations"],"description":"Deleting an organization-wide annotation needs the reach creating one takes (403 otherwise).\n\nRequires `annotations:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["annotations:write"]},{"apiKeyBearer":["annotations:write"]},{"session":["annotations:write"]}],"x-pilotfox-access":{"kind":"site","permission":"annotations:write"},"responses":{"204":{"description":"No Content"}}},"patch":{"operationId":"updateAnnotation","summary":"Update an annotation","tags":["Annotations"],"description":"Changes the fields sent. Editing an organization-wide annotation, or moving one to `scope: org`, needs the reach creating one takes (403 otherwise); an MCP tool may not make one public or organization-wide (403).\n\nRequires `annotations:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"startsAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"endsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"color":{"anyOf":[{"type":"string","enum":["blue","salmon","green","amber","red","violet","gray"]},{"type":"null"}]},"icon":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}]},"isPublic":{"type":"boolean"},"scope":{"type":"string","enum":["site","org"]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["annotations:write"]},{"apiKeyBearer":["annotations:write"]},{"session":["annotations:write"]}],"x-pilotfox-access":{"kind":"site","permission":"annotations:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"startsAt":{"type":"string"},"endsAt":{"type":["string","null"]},"color":{"anyOf":[{"type":"string","enum":["blue","salmon","green","amber","red","violet","gray"]},{"type":"null"}]},"icon":{"type":["string","null"]},"isPublic":{"type":"boolean"},"scope":{"type":"string","enum":["site","org"]},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","description","startsAt","endsAt","color","icon","isPublic","scope","createdBy","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/bots/ai":{"get":{"operationId":"getBotAiReport","summary":"Get the AI crawler report","tags":["Bots"],"description":"Per AI operator: crawler and assistant requests, the visits its AI assistants referred, and crawls per referral.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"operator":{"type":"string"},"crawls":{"type":"number","description":"AI crawler plus AI assistant requests"},"ai_crawler_requests":{"type":"number"},"ai_assistant_requests":{"type":"number"},"referrals":{"type":"number","description":"Sessions arriving from the operator's AI assistants (channel AI)"},"crawls_per_referral":{"description":"crawls / referrals; null without a referral","type":["number","null"]}},"required":["operator","crawls","ai_crawler_requests","ai_assistant_requests","referrals","crawls_per_referral"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/bots/breakdown":{"get":{"operationId":"getBotBreakdown","summary":"Get a bot breakdown","tags":["Bots"],"description":"Bot requests and visitors per value of one dimension (`dim`), with their share of all bot requests.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["bot_name","bot_operator","bot_category","asn_org","pathname","country","layer"]},"in":"query","name":"dim","required":true},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"number"},"visitors":{"type":"number"},"percentage":{"type":"number","description":"Of all bot requests in the window; for dim=layer, of all (request, layer) pairs"},"category":{"description":"dim=bot_name: the bot's category","type":"string"},"user_agent":{"description":"dim=bot_name: the user agent of its latest request","type":"string"}},"required":["value","count","visitors","percentage"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/bots/overview":{"get":{"operationId":"getBotOverview","summary":"Get the bot overview","tags":["Bots"],"description":"Bot requests against human events in the window, the bot share, what each detection layer flagged, and AI crawler and AI assistant requests.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"bot_requests":{"type":"number"},"human_events":{"type":"number","description":"Events in `events` not marked as bots (device_type != 'bot')"},"bot_share":{"type":"number","description":"bot_requests / (bot_requests + human_events) × 100; 0 when both are 0"},"by_layer":{"type":"object","properties":{"ua":{"type":"number"},"headers":{"type":"number"},"client":{"type":"number"},"asn":{"type":"number"},"rate":{"type":"number"}},"required":["ua","headers","client","asn","rate"],"additionalProperties":false,"description":"Requests each detection layer flagged; a request flagged by two layers counts in both"},"ai_crawler_requests":{"type":"number"},"ai_assistant_requests":{"type":"number"}},"required":["bot_requests","human_events","bot_share","by_layer","ai_crawler_requests","ai_assistant_requests"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/bots/timeseries":{"get":{"operationId":"getBotTimeseries","summary":"Get bot time series","tags":["Bots"],"description":"Requests per time bucket of the top `limit` keys of one dimension (`dim`, the bot category by default), optionally of one `category` only.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"default":"bot_category","type":"string","enum":["bot_name","bot_operator","bot_category","asn_org","pathname","country","layer"]},"in":"query","name":"dim","required":false},{"schema":{"type":"string","enum":["search","ai_crawler","ai_assistant","seo","monitoring","social_preview","scraper","automation","unknown"]},"in":"query","name":"category","required":false,"description":"Only bot requests of this category"},{"schema":{"default":5,"type":"integer","minimum":1,"maximum":20},"in":"query","name":"limit","required":false,"description":"The top keys by requests in the window"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"total":{"type":"number","description":"Requests of the key in the window"},"series":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"count":{"type":"number"}},"required":["t","count"],"additionalProperties":false}}},"required":["key","total","series"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/breakdown":{"get":{"operationId":"getBreakdown","summary":"Get a breakdown","tags":["Analytics"],"description":"The top values of one dimension ranked by `metric`, with conversions when `goal` is given, a page at a time (`limit` and `offset`; `meta.totalCount` counts the values). `dim` is one of: entry_page, exit_page, referrer, referrer_domain, channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, affiliate, country, city, continent, browser, browser_version, os, os_version, device_type, screen, language, timezone, tag, region, asn.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"query","name":"dim","required":true},{"schema":{"default":"visitors","type":"string","enum":["visitors","sessions","pageviews","bounce_rate","avg_session_duration"]},"in":"query","name":"metric","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"goal","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"region_name":{"type":"string"},"visitors":{"type":"number"},"sessions":{"type":"number"},"pageviews":{"type":"number"},"bounce_rate":{"type":"number"},"avg_session_duration":{"type":"number"},"conversions":{"type":"number"},"percentage":{"type":"number"}},"required":["value","visitors","sessions","pageviews","bounce_rate","avg_session_duration","percentage"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/errors":{"get":{"operationId":"listErrors","summary":"List errors","tags":["Errors"],"description":"JavaScript errors grouped by fingerprint, most frequent first, with the latest message, counts, first and last time seen and a per-bucket trend, a page at a time (`limit` and `offset`; `meta.totalCount` counts the groups). Without `sessions:read`, the URLs in messages lose their query and fragment.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"fingerprint":{"type":"string"},"name":{"type":"string"},"message":{"type":"string"},"count":{"type":"number"},"sessions":{"type":"number"},"visitors":{"type":"number"},"first_seen":{"type":"string"},"last_seen":{"type":"string"},"trend":{"type":"array","items":{"type":"number"},"description":"Errors per window bucket, oldest first; aligned with /timeseries"}},"required":["fingerprint","name","message","count","sessions","visitors","first_seen","last_seen","trend"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/errors/summary":{"get":{"operationId":"getErrorsSummary","summary":"Get the errors summary","tags":["Errors"],"description":"Occurrences, sessions, visitors and distinct fingerprints in the window, and occurrences per time bucket.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"number"},"sessions":{"type":"number"},"visitors":{"type":"number"},"distinct":{"type":"number","description":"Distinct fingerprints"},"timeseries":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"count":{"type":"number"}},"required":["t","count"],"additionalProperties":false},"description":"Errors per window bucket, oldest first; aligned with /timeseries"}},"required":["count","sessions","visitors","distinct","timeseries"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/errors/{fingerprint}":{"get":{"operationId":"getError","summary":"Get an error","tags":["Errors"],"description":"One error group: its totals, time series, top 10 pages and browsers, and the latest stack (the URLs in the message and stack lose their query and fragment without `sessions:read`). 404 when it did not occur in the window.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"fingerprint","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fingerprint":{"type":"string"},"name":{"type":"string"},"message":{"type":"string"},"count":{"type":"number"},"sessions":{"type":"number"},"visitors":{"type":"number"},"first_seen":{"type":"string"},"last_seen":{"type":"string"},"timeseries":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"count":{"type":"number"}},"required":["t","count"],"additionalProperties":false},"description":"Errors per window bucket, oldest first; aligned with /timeseries"},"top_pages":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"number"}},"required":["value","count"],"additionalProperties":false}},"browsers":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"number"}},"required":["value","count"],"additionalProperties":false}},"sample_stack":{"description":"The latest occurrence's stack; null when it has none","type":["string","null"]}},"required":["fingerprint","name","message","count","sessions","visitors","first_seen","last_seen","timeseries","top_pages","browsers","sample_stack"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/errors/{fingerprint}/occurrences":{"get":{"operationId":"listErrorOccurrences","summary":"List an error's occurrences","tags":["Errors"],"description":"Each occurrence of one error, newest first, with its session and page, a page at a time (`meta.nextCursor`).\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `sessions:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`meta.nextCursor` of the previous page"},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"fingerprint","required":true}],"security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]},{"shareToken":["sessions:read"]},{"shareTokenQuery":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"string"},"session_id":{"type":"string"},"visitor_id":{"type":"string"},"user_id":{"type":"string","description":"The identified user id; '' when anonymous"},"pathname":{"type":"string"},"browser":{"type":"string"},"browser_version":{"type":"string"},"os":{"type":"string"},"device_type":{"type":"string"},"country":{"type":"string"},"message":{"type":"string"},"stack":{"type":"string"},"file":{"type":"string"},"line":{"type":["number","null"]},"col":{"type":["number","null"]}},"required":["ts","session_id","visitor_id","user_id","pathname","browser","browser_version","os","device_type","country","message","stack","file","line","col"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/events":{"get":{"operationId":"listEvents","summary":"List events","tags":["Events"],"description":"The window's raw events (web vitals aside), newest first, a page at a time (`meta.nextCursor`); or, with `since`, up to 500 of the events since then (24 hours back at most), for a live feed.\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `sessions:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"in":"query","name":"since","required":false,"description":"Realtime tail: events in [since, now), at most 24 hours back; no window keys, no cursor"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`meta.nextCursor` of the previous page"},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":500},"in":"query","name":"limit","required":false,"description":"List mode; a tail returns up to 500 rows"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]},{"shareToken":["sessions:read"]},{"shareTokenQuery":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"string"},"type":{"type":"string"},"event_name":{"type":"string"},"session_id":{"type":"string"},"visitor_id":{"type":"string"},"user_id":{"type":"string","description":"The identified user id; '' when anonymous"},"hostname":{"type":"string"},"pathname":{"type":"string"},"querystring":{"type":"string"},"page_title":{"type":"string"},"referrer":{"type":"string"},"channel":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"city":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"device_type":{"type":"string"},"props":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean"]}}},"required":["ts","type","event_name","session_id","visitor_id","user_id","hostname","pathname","querystring","page_title","referrer","channel","country","region","city","browser","os","device_type","props"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/events/autocapture":{"get":{"operationId":"listAutocapturedValues","summary":"List autocaptured values","tags":["Events"],"description":"The most frequent values of one kind (`type`) of autocaptured interaction, with counts, visitors and last time seen: `outbound` links by URL, `click`s by the element's text, `form` submissions by the form's name, id or action, and `copy` events by the element's tag.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","enum":["outbound","click","form","copy"]},"in":"query","name":"type","required":true},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"number"},"visitors":{"type":"number"},"last_seen":{"type":"string"}},"required":["value","count","visitors","last_seen"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/events/names":{"get":{"operationId":"listEventNames","summary":"List event names","tags":["Events"],"description":"Each custom event name with its count, visitors, last time seen and a per-bucket trend, most frequent first, a page at a time (`limit` and `offset`; `meta.totalCount` counts the names).\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"count":{"type":"number"},"visitors":{"type":"number"},"last_seen":{"type":"string"},"trend":{"type":"array","items":{"type":"number"},"description":"Events per window bucket, oldest first; aligned with /timeseries"}},"required":["name","count","visitors","last_seen","trend"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/events/properties":{"get":{"operationId":"listEventProperties","summary":"List event properties","tags":["Events"],"description":"The most frequent property key and value pairs (500 at most) of the custom event `name`. The `checkout` event's `ref` stays out for callers without `sessions:read`.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"name","required":true},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"count":{"type":"number"}},"required":["key","value","count"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/events/summary":{"get":{"operationId":"getEventsSummary","summary":"Get the events summary","tags":["Events"],"description":"Events (custom events and autocaptured interactions), the visitors who sent one, and the distinct custom event names in the window.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"events":{"type":"number"},"visitors_with_events":{"type":"number"},"unique_names":{"type":"number"}},"required":["events","visitors_with_events","unique_names"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/events/timeseries":{"get":{"operationId":"getEventsTimeseries","summary":"Get event time series","tags":["Events"],"description":"Counts per time bucket of each custom event in `names` (a JSON array of up to 10 names), or of the 5 most frequent: one row per bucket and name.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"names","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"name":{"type":"string"},"count":{"type":"number"}},"required":["t","name","count"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/export":{"get":{"operationId":"exportEvents","summary":"Export raw events","tags":["Exports"],"description":"The site's raw events in the window (`format=jsonl` is required), one JSON object per line (`application/x-ndjson`, sent as an attachment), in the format a `native_jsonl` import reads: every event column except `site_id` and `import_id`. Events only: identity aliases (manual identify) and session replay data are not exported. Rows come in no particular order. Needs `exports:read` and `sessions:read` (rows carry visitor ids, user ids and coordinates). The window is required (`all=true` is refused) and at most 400 days. A failure after the first bytes breaks the transfer instead of ending the body (no trailer); every complete line before it is a valid row. The body carries no completion marker, so a client must treat any transport error (a reset, a truncated chunked body, a proxy closing early) as an incomplete export. A client that stops reading is cut off within about a minute, and an export ends after about 10 minutes whatever its progress. A few exports run at once per server (two by default), one more answering 503, and fewer per organization (one by default), one more answering 429.\n\nRequires `exports:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","enum":["jsonl"]},"in":"query","name":"format","required":true},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["exports:read"]},{"apiKeyBearer":["exports:read"]},{"session":["exports:read"]}],"x-pilotfox-access":{"kind":"site","permission":"exports:read"},"responses":{"200":{"description":"One event per line","content":{"application/x-ndjson":{"schema":{"type":"string"}}}}}}},"/api/v1/sites/{siteId}/favicons/{domain}":{"get":{"operationId":"getFavicon","summary":"Get a referrer's favicon","tags":["Analytics"],"description":"The icon of a domain that referred visitors to the site in the last 90 days (`https://<domain>/favicon.ico`, named in lowercase ASCII, punycode for an international name), fetched and cached by the server so the browser never contacts that domain. 404 for any other domain, or when it has none. 60 a minute per caller.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"domain","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"The icon: ICO, PNG, GIF, JPEG or WebP, typed by its content","content":{"image/*":{"schema":{"type":"string"}}}}}}},"/api/v1/sites/{siteId}/funnels":{"get":{"operationId":"listFunnels","summary":"List funnels","tags":["Funnels"],"description":"The site's saved funnels, oldest first.\n\nRequires `funnels:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["funnels:read"]},{"apiKeyBearer":["funnels:read"]},{"session":["funnels:read"]}],"x-pilotfox-access":{"kind":"site","permission":"funnels:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"steps":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind"],"additionalProperties":false}]}},"windowSeconds":{"type":["number","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","steps","windowSeconds","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"operationId":"createFunnel","summary":"Create a funnel","tags":["Funnels"],"description":"A named sequence of 2 to 10 steps (conditions), optionally to be completed within `windowSeconds` (90 days at most), which makes its report count users across sessions instead of single sessions.\n\nRequires `funnels:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"steps":{"minItems":2,"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind"],"additionalProperties":false}]}},"windowSeconds":{"anyOf":[{"type":"integer","minimum":1,"maximum":7776000},{"type":"null"}]}},"required":["name","steps"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["funnels:write"]},{"apiKeyBearer":["funnels:write"]},{"session":["funnels:write"]}],"x-pilotfox-access":{"kind":"site","permission":"funnels:write"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"steps":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind"],"additionalProperties":false}]}},"windowSeconds":{"type":["number","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","steps","windowSeconds","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/funnels/analyze":{"post":{"operationId":"analyzeFunnel","summary":"Analyze an unsaved funnel","tags":["Funnels"],"description":"The report of the funnel in the body without saving it: the same answer as a saved funnel's report.\n\nRequires `funnels:read` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"steps":{"minItems":2,"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind"],"additionalProperties":false}]}},"windowSeconds":{"anyOf":[{"type":"integer","minimum":1,"maximum":7776000},{"type":"null"}]}},"required":["steps"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["funnels:read"]},{"apiKeyBearer":["funnels:read"]},{"session":["funnels:read"]}],"x-pilotfox-access":{"kind":"site","permission":"funnels:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"unit":{"type":"string","enum":["sessions","users"]},"windowSeconds":{"type":["number","null"]},"steps":{"type":"array","items":{"type":"object","properties":{"step":{"type":"number"},"label":{"type":["string","null"]},"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253}},"required":["kind"],"additionalProperties":false}]},"count":{"type":"number"},"conversion":{"type":"number"},"dropoff":{"type":["number","null"]},"median_seconds":{"type":["number","null"]}},"required":["step","label","condition","count","conversion","dropoff","median_seconds"],"additionalProperties":false}}},"required":["unit","windowSeconds","steps"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/funnels/{id}":{"get":{"operationId":"getFunnel","summary":"Get a funnel","tags":["Funnels"],"description":"Requires `funnels:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["funnels:read"]},{"apiKeyBearer":["funnels:read"]},{"session":["funnels:read"]}],"x-pilotfox-access":{"kind":"site","permission":"funnels:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"steps":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind"],"additionalProperties":false}]}},"windowSeconds":{"type":["number","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","steps","windowSeconds","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteFunnel","summary":"Delete a funnel","tags":["Funnels"],"description":"Requires `funnels:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["funnels:write"]},{"apiKeyBearer":["funnels:write"]},{"session":["funnels:write"]}],"x-pilotfox-access":{"kind":"site","permission":"funnels:write"},"responses":{"204":{"description":"No Content"}}},"patch":{"operationId":"updateFunnel","summary":"Update a funnel","tags":["Funnels"],"description":"Changes the fields sent; `windowSeconds: null` removes the window.\n\nRequires `funnels:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"steps":{"minItems":2,"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind"],"additionalProperties":false}]}},"windowSeconds":{"anyOf":[{"type":"integer","minimum":1,"maximum":7776000},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["funnels:write"]},{"apiKeyBearer":["funnels:write"]},{"session":["funnels:write"]}],"x-pilotfox-access":{"kind":"site","permission":"funnels:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"steps":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"label":{"type":"string","minLength":1,"maxLength":100}},"required":["kind"],"additionalProperties":false}]}},"windowSeconds":{"type":["number","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","steps","windowSeconds","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/funnels/{id}/report":{"get":{"operationId":"getFunnelReport","summary":"Get a funnel's report","tags":["Funnels"],"description":"How many sessions (users, when the funnel has a `windowSeconds`) reached each step in order in the window, with conversion (percent of step 1), drop-off (percent of the previous step) and median time from the previous step.\n\nRequires `funnels:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["funnels:read"]},{"apiKeyBearer":["funnels:read"]},{"session":["funnels:read"]}],"x-pilotfox-access":{"kind":"site","permission":"funnels:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"unit":{"type":"string","enum":["sessions","users"]},"windowSeconds":{"type":["number","null"]},"steps":{"type":"array","items":{"type":"object","properties":{"step":{"type":"number"},"label":{"type":["string","null"]},"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253}},"required":["kind"],"additionalProperties":false}]},"count":{"type":"number"},"conversion":{"type":"number"},"dropoff":{"type":["number","null"]},"median_seconds":{"type":["number","null"]}},"required":["step","label","condition","count","conversion","dropoff","median_seconds"],"additionalProperties":false}}},"required":["unit","windowSeconds","steps"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/funnels/{id}/sessions":{"get":{"operationId":"listFunnelStepSessions","summary":"List a funnel step's sessions","tags":["Funnels"],"description":"The sessions that reached step `step` (`mode=reached`) or reached it and went no further (`mode=dropped`; 400 for the last step), a page at a time (`meta.nextCursor`).\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `sessions:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"integer","minimum":1,"maximum":10},"in":"query","name":"step","required":true},{"schema":{"default":"reached","type":"string","enum":["reached","dropped"]},"in":"query","name":"mode","required":false},{"schema":{"type":"string","maxLength":512},"in":"query","name":"cursor","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]},{"shareToken":["sessions:read"]},{"shareTokenQuery":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"session_id":{"type":"string"},"visitor_id":{"type":"string"},"user_id":{"type":"string"},"started_at":{"type":"string"},"ended_at":{"type":"string"},"duration":{"type":"number"},"pageviews":{"type":"number"},"events":{"type":"number"},"entry_page":{"type":"string"},"exit_page":{"type":"string"},"referrer_domain":{"type":"string"},"channel":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"device_type":{"type":"string"}},"required":["session_id","visitor_id","user_id","started_at","ended_at","duration","pageviews","events","entry_page","exit_page","referrer_domain","channel","country","city","browser","os","device_type"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/geo/cities":{"get":{"operationId":"listCities","summary":"List cities","tags":["Geography"],"description":"Visitors and sessions per city, with its region and country and, when known, its coordinates; ranked by visitors. `country` and `region` narrow the list, and `goal` adds conversions.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":100,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"goal","required":false},{"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"in":"query","name":"country","required":false},{"schema":{"type":"string","pattern":"^[A-Z]{2}-[A-Z0-9]{1,3}$"},"in":"query","name":"region","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"city":{"type":"string"},"region":{"type":"string"},"region_name":{"type":"string"},"country":{"type":"string"},"lat":{"type":["number","null"]},"lon":{"type":["number","null"]},"visitors":{"type":"number"},"sessions":{"type":"number"},"conversions":{"type":"number"}},"required":["city","region","region_name","country","lat","lon","visitors","sessions"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/geo/countries":{"get":{"operationId":"listCountries","summary":"List countries","tags":["Geography"],"description":"Visitors, sessions and pageviews per country (ISO 3166-1 code and name), ranked by visitors, as `/breakdown?dim=country` counts them; with `goal`, each country's conversions.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":1000,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"goal","required":false},{"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"in":"query","name":"country","required":false},{"schema":{"type":"string","pattern":"^[A-Z]{2}-[A-Z0-9]{1,3}$"},"in":"query","name":"region","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"visitors":{"type":"number"},"sessions":{"type":"number"},"pageviews":{"type":"number"},"percentage":{"type":"number"},"conversions":{"type":"number"}},"required":["code","name","visitors","sessions","pageviews","percentage"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/geo/live":{"get":{"operationId":"getLiveGeo","summary":"Get live visitor locations","tags":["Live"],"description":"The visitors seen in the last `minutes` (5 by default, 30 at most), most recent first, with their approximate location and when they were last seen. 503 when live presence cannot be read.\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"default":5,"type":"integer","minimum":1,"maximum":30},"in":"query","name":"minutes","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"visitor_id":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"country":{"type":"string"},"city":{"type":"string"},"last_seen_ms":{"type":"number"}},"required":["visitor_id","lat","lon","country","city","last_seen_ms"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/geo/points":{"get":{"operationId":"getGeoPoints","summary":"Get map points","tags":["Geography"],"description":"Visitors and sessions binned into H3 cells (`bin=h3`, resolution `res`) or a latitude/longitude grid (`bin=grid`, `precision` decimals), with each cell's center; `meta.truncated` when there were more than `limit`.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":"h3","type":"string","enum":["h3","grid"]},"in":"query","name":"bin","required":false},{"schema":{"default":4,"type":"integer","minimum":2,"maximum":7},"in":"query","name":"res","required":false},{"schema":{"default":1,"type":"integer","minimum":0,"maximum":2},"in":"query","name":"precision","required":false},{"schema":{"default":20000,"type":"integer","minimum":1,"maximum":20000},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"cell":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"visitors":{"type":"number"},"sessions":{"type":"number"}},"required":["cell","lat","lon","visitors","sessions"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/geo/regions":{"get":{"operationId":"listRegions","summary":"List regions","tags":["Geography"],"description":"Visitors, sessions and pageviews per region (ISO 3166-2 code, name and country), ranked by visitors, as `/breakdown?dim=region` counts them; `country` narrows to one country, and `goal` adds conversions.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":1000,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"goal","required":false},{"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"in":"query","name":"country","required":false},{"schema":{"type":"string","pattern":"^[A-Z]{2}-[A-Z0-9]{1,3}$"},"in":"query","name":"region","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"visitors":{"type":"number"},"sessions":{"type":"number"},"pageviews":{"type":"number"},"percentage":{"type":"number"},"conversions":{"type":"number"},"country":{"type":"string"}},"required":["code","name","visitors","sessions","pageviews","percentage","country"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/geo/timeline":{"get":{"operationId":"getGeoTimeline","summary":"Get the session map timeline","tags":["Geography"],"description":"Each session of the window with its location, start and end (columnar arrays: index `i` of each is one session), and a histogram of active sessions, to replay the window on a map. `meta.truncated` when there were more than `limit`.\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":100000,"type":"integer","minimum":1,"maximum":100000},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"session_id":{"type":"array","items":{"type":"string"}},"lat":{"type":"array","items":{"type":"number"}},"lon":{"type":"array","items":{"type":"number"}},"start_ms":{"type":"array","items":{"type":"number"}},"end_ms":{"type":"array","items":{"type":"number"}},"histogram":{"type":"object","properties":{"bucket_ms":{"type":"number"},"active":{"type":"array","items":{"type":"number"}}},"required":["bucket_ms","active"],"additionalProperties":false}},"required":["session_id","lat","lon","start_ms","end_ms","histogram"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/goals":{"get":{"operationId":"listGoals","summary":"List goals","tags":["Goals"],"description":"The site's goals, oldest first.\n\nRequires `goals:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["goals:read"]},{"apiKeyBearer":["goals:read"]},{"session":["goals:read"]}],"x-pilotfox-access":{"kind":"site","permission":"goals:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253}},"required":["kind"],"additionalProperties":false}]},"icon":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","condition","icon","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"operationId":"createGoal","summary":"Create a goal","tags":["Goals"],"description":"A named condition (a page, an event or an autocaptured interaction) whose sessions count as conversions. 409 once the site has 100 goals.\n\nRequires `goals:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253}},"required":["kind"],"additionalProperties":false}]},"icon":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}]}},"required":["name","condition"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["goals:write"]},{"apiKeyBearer":["goals:write"]},{"session":["goals:write"]}],"x-pilotfox-access":{"kind":"site","permission":"goals:write"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253}},"required":["kind"],"additionalProperties":false}]},"icon":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","condition","icon","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/goals/preview":{"post":{"operationId":"previewGoal","summary":"Preview a goal","tags":["Goals"],"description":"What an unsaved condition would count in the window: sessions, conversions, rate and conversions per time bucket. Never cached.\n\nRequires `goals:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253}},"required":["kind"],"additionalProperties":false}]}},"required":["condition"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["goals:write"]},{"apiKeyBearer":["goals:write"]},{"session":["goals:write"]}],"x-pilotfox-access":{"kind":"site","permission":"goals:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sessions":{"type":"number"},"conversions":{"type":"number"},"rate":{"type":"number"},"series":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"conversions":{"type":"number"}},"required":["t","conversions"],"additionalProperties":false}}},"required":["sessions","conversions","rate","series"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/goals/stats":{"get":{"operationId":"getGoalStats","summary":"Get goal stats","tags":["Goals"],"description":"Each goal's conversions (sessions that converted) and conversion rate over the window's sessions, most conversions first; with a comparison window, the same figures for it under `previous`.\n\nRequires `goals:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["goals:read"]},{"apiKeyBearer":["goals:read"]},{"session":["goals:read"]}],"x-pilotfox-access":{"kind":"site","permission":"goals:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sessions":{"type":"number"},"goals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"icon":{"type":["string","null"]},"conversions":{"type":"number"},"rate":{"type":"number"},"previous":{"type":"object","properties":{"conversions":{"type":"number"},"rate":{"type":"number"}},"required":["conversions","rate"],"additionalProperties":false}},"required":["id","name","icon","conversions","rate"],"additionalProperties":false}},"previous":{"type":"object","properties":{"sessions":{"type":"number"}},"required":["sessions"],"additionalProperties":false}},"required":["sessions","goals"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/goals/{id}":{"get":{"operationId":"getGoal","summary":"Get a goal","tags":["Goals"],"description":"Requires `goals:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["goals:read"]},{"apiKeyBearer":["goals:read"]},{"session":["goals:read"]}],"x-pilotfox-access":{"kind":"site","permission":"goals:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253}},"required":["kind"],"additionalProperties":false}]},"icon":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","condition","icon","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteGoal","summary":"Delete a goal","tags":["Goals"],"description":"Requires `goals:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["goals:write"]},{"apiKeyBearer":["goals:write"]},{"session":["goals:write"]}],"x-pilotfox-access":{"kind":"site","permission":"goals:write"},"responses":{"204":{"description":"No Content"}}},"patch":{"operationId":"updateGoal","summary":"Update a goal","tags":["Goals"],"description":"Requires `goals:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253}},"required":["kind"],"additionalProperties":false}]},"icon":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["goals:write"]},{"apiKeyBearer":["goals:write"]},{"session":["goals:write"]}],"x-pilotfox-access":{"kind":"site","permission":"goals:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"path":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","path"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"name":{"type":"string","minLength":1,"maxLength":128},"hostname":{"type":"string","minLength":1,"maxLength":253},"props":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64},"op":{"type":"string","enum":["eq","neq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":512},{"type":"number"},{"type":"boolean"}]}},"required":["key","op","value"],"additionalProperties":false}}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["outbound","click","form","copy"]},"match":{"type":"string","minLength":1,"maxLength":1024},"hostname":{"type":"string","minLength":1,"maxLength":253}},"required":["kind"],"additionalProperties":false}]},"icon":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","condition","icon","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/goals/{id}/conversions":{"get":{"operationId":"listGoalConversions","summary":"List a goal's conversions","tags":["Goals"],"description":"The window's sessions that converted on the goal, newest conversion first, with who converted, how many sessions they had and how long converting took from their first session; a page at a time (`meta.nextCursor`; `meta.totalCount`). `search` matches part of the user id or, with `users:read`, of a profile's `name` or `email` trait. Never cached.\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `sessions:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"search","required":false},{"schema":{"type":"string","maxLength":512},"in":"query","name":"cursor","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]},{"shareToken":["sessions:read"]},{"shareTokenQuery":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"session_id":{"type":"string"},"visitor_id":{"type":"string"},"user_id":{"type":"string","description":"the effective user key: a uid, an alias, else the visitor id"},"identified":{"type":"boolean"},"name":{"description":"the profile's `name` trait; null without users:read","type":["string","null"]},"country":{"type":"string"},"device_type":{"type":"string"},"os":{"type":"string"},"browser":{"type":"string"},"referrer_domain":{"type":"string"},"pageviews":{"type":"number"},"sessions":{"type":"number","description":"the user's qualified sessions in the window"},"time_to_convert":{"type":"number","description":"seconds from the user's first qualified session to the conversion"},"converted_at":{"type":"string"}},"required":["session_id","visitor_id","user_id","identified","name","country","device_type","os","browser","referrer_domain","pageviews","sessions","time_to_convert","converted_at"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/goals/{id}/timeseries":{"get":{"operationId":"getGoalTimeseries","summary":"Get a goal's time series","tags":["Goals"],"description":"Sessions, conversions and conversion rate per time bucket for one goal.\n\nRequires `goals:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["goals:read"]},{"apiKeyBearer":["goals:read"]},{"session":["goals:read"]}],"x-pilotfox-access":{"kind":"site","permission":"goals:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"sessions":{"type":"number"},"conversions":{"type":"number"},"rate":{"type":"number"}},"required":["t","sessions","conversions","rate"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/heatmap":{"get":{"operationId":"getHeatmap","summary":"Get the weekly heatmap","tags":["Analytics"],"description":"Visitors and pageviews per weekday and hour, in the window's time zone (`tz`, else the site's).\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"dow":{"type":"number","description":"Local weekday: Monday = 1 … Sunday = 7"},"hour":{"type":"number","description":"Local hour, 0-23"},"visitors":{"type":"number"},"pageviews":{"type":"number"}},"required":["dow","hour","visitors","pageviews"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/imports":{"get":{"operationId":"listImports","summary":"List imports","tags":["Imports"],"description":"The site's latest 100 imports, newest first.\n\nRequires `imports:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["imports:read"]},{"apiKeyBearer":["imports:read"]},{"session":["imports:read"]}],"x-pilotfox-access":{"kind":"site","permission":"imports:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["umami","plausible","simple_analytics","native_jsonl"]},"status":{"type":"string","enum":["uploaded","running","completed","failed","cancelled"]},"fileName":{"type":"string"},"fileBytes":{"type":"number"},"rowsRead":{"type":"number"},"rowsImported":{"type":"number"},"rowsSkipped":{"type":"number"},"rowsInvalid":{"type":"number"},"approximate":{"type":"boolean","description":"Plausible imports are synthesized from aggregates"},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","source","status","fileName","fileBytes","rowsRead","rowsImported","rowsSkipped","rowsInvalid","approximate","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"operationId":"createImport","summary":"Upload an import","tags":["Imports"],"description":"Uploads a file to import as `multipart/form-data`: first the `source` field (`umami`: an Umami CSV export; `plausible`: Plausible's CSV export ZIP; `simple_analytics`: a Simple Analytics raw CSV export; `native_jsonl`: a PilotFox NDJSON export), then the `file` (2 GiB at most). The file is stored and imported in the background: 202 with the import, whose `status` its GET follows. 409 while the organization has too many imports queued or running, 429 while it has too many uploads streaming; 413 past the size limit, 415 for another body type; 503 when busy or when storage or background jobs are unavailable.\n\nRequires `imports:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["imports:write"]},{"apiKeyBearer":["imports:write"]},{"session":["imports:write"]}],"x-pilotfox-access":{"kind":"site","permission":"imports:write"},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["umami","plausible","simple_analytics","native_jsonl"]},"status":{"type":"string","enum":["uploaded","running","completed","failed","cancelled"]},"fileName":{"type":"string"},"fileBytes":{"type":"number"},"rowsRead":{"type":"number"},"rowsImported":{"type":"number"},"rowsSkipped":{"type":"number"},"rowsInvalid":{"type":"number"},"approximate":{"type":"boolean","description":"Plausible imports are synthesized from aggregates"},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","source","status","fileName","fileBytes","rowsRead","rowsImported","rowsSkipped","rowsInvalid","approximate","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/imports/{id}":{"get":{"operationId":"getImport","summary":"Get an import","tags":["Imports"],"description":"One import with its status and how many rows were read, imported, skipped and invalid.\n\nRequires `imports:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["imports:read"]},{"apiKeyBearer":["imports:read"]},{"session":["imports:read"]}],"x-pilotfox-access":{"kind":"site","permission":"imports:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["umami","plausible","simple_analytics","native_jsonl"]},"status":{"type":"string","enum":["uploaded","running","completed","failed","cancelled"]},"fileName":{"type":"string"},"fileBytes":{"type":"number"},"rowsRead":{"type":"number"},"rowsImported":{"type":"number"},"rowsSkipped":{"type":"number"},"rowsInvalid":{"type":"number"},"approximate":{"type":"boolean","description":"Plausible imports are synthesized from aggregates"},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","source","status","fileName","fileBytes","rowsRead","rowsImported","rowsSkipped","rowsInvalid","approximate","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteImport","summary":"Delete an import","tags":["Imports"],"description":"Deletes the events the import brought in, then the import itself (cancelling it when it is queued or running); 503, with nothing deleted, when ClickHouse is unavailable.\n\nRequires `imports:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["imports:write"]},{"apiKeyBearer":["imports:write"]},{"session":["imports:write"]}],"x-pilotfox-access":{"kind":"site","permission":"imports:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/imports/{id}/cancel":{"post":{"operationId":"cancelImport","summary":"Cancel an import","tags":["Imports"],"description":"Cancels an import that is queued or running; 409 once it has finished.\n\nRequires `imports:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["imports:write"]},{"apiKeyBearer":["imports:write"]},{"session":["imports:write"]}],"x-pilotfox-access":{"kind":"site","permission":"imports:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["umami","plausible","simple_analytics","native_jsonl"]},"status":{"type":"string","enum":["uploaded","running","completed","failed","cancelled"]},"fileName":{"type":"string"},"fileBytes":{"type":"number"},"rowsRead":{"type":"number"},"rowsImported":{"type":"number"},"rowsSkipped":{"type":"number"},"rowsInvalid":{"type":"number"},"approximate":{"type":"boolean","description":"Plausible imports are synthesized from aggregates"},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","source","status","fileName","fileBytes","rowsRead","rowsImported","rowsSkipped","rowsInvalid","approximate","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/integrations/dodo":{"get":{"operationId":"getDodoConnection","summary":"Get the Dodo Payments connection","tags":["Payment providers"],"description":"The connection's state: key hint, live or test mode, account, sync status, last sync and last error; never the key.\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"provider":{"type":"string","enum":["stripe","dodo","polar"]},"connected":{"type":"boolean"},"keyHint":{"description":"A non-secret type prefix when the provider has one and the last four characters, e.g. rk_live_…wxyz","type":["string","null"]},"livemode":{"description":"Live/production (true) or test/sandbox (false)","type":["boolean","null"]},"accountName":{"type":["string","null"]},"status":{"anyOf":[{"type":"string","enum":["ok","syncing","error"]},{"type":"null"}]},"lastSyncAt":{"type":["string","null"]},"lastError":{"description":"A safe message for people; never the provider's text or the key","type":["string","null"]},"notice":{"description":"An advisory about a connection that syncs but not completely (e.g. a Stripe key without Read access to Invoices: no renewals); never the provider's text","type":["string","null"]},"backfillDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["provider","connected","keyHint","livemode","accountName","status","lastSyncAt","lastError","notice","backfillDays"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"put":{"operationId":"connectDodo","summary":"Connect Dodo Payments","tags":["Payment providers"],"description":"Checks the API key with the provider (400 when it is rejected or lacks a read permission), stores it encrypted, and queues the import of the last `backfillDays` days of payments (90 by default, 365 at most). When the key belongs to another account or mode than the payments already synced, those are deleted.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"secretKey":{"type":"string","minLength":8,"maxLength":1024,"pattern":"^[A-Za-z0-9\\-._~+/]+=*$","description":"A Dodo Payments API key; never returned, stored encrypted"},"backfillDays":{"default":90,"type":"integer","minimum":1,"maximum":365}},"required":["secretKey"],"additionalProperties":false}}}},"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"provider":{"type":"string","enum":["stripe","dodo","polar"]},"connected":{"type":"boolean"},"keyHint":{"description":"A non-secret type prefix when the provider has one and the last four characters, e.g. rk_live_…wxyz","type":["string","null"]},"livemode":{"description":"Live/production (true) or test/sandbox (false)","type":["boolean","null"]},"accountName":{"type":["string","null"]},"status":{"anyOf":[{"type":"string","enum":["ok","syncing","error"]},{"type":"null"}]},"lastSyncAt":{"type":["string","null"]},"lastError":{"description":"A safe message for people; never the provider's text or the key","type":["string","null"]},"notice":{"description":"An advisory about a connection that syncs but not completely (e.g. a Stripe key without Read access to Invoices: no renewals); never the provider's text","type":["string","null"]},"backfillDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["provider","connected","keyHint","livemode","accountName","status","lastSyncAt","lastError","notice","backfillDays"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"disconnectDodo","summary":"Disconnect Dodo Payments","tags":["Payment providers"],"description":"Deletes the connection and its key; with `deletePayments=true`, the payments synced from it too.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"deletePayments","required":false,"description":"Also delete this provider's synced payments"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"responses":{"204":{"description":"No Content"}}}},"/api/v1/sites/{siteId}/integrations/dodo/rematch":{"post":{"operationId":"rematchDodoPayments","summary":"Re-run Dodo Payments attribution","tags":["Payment providers"],"description":"Re-reads the connection's whole history window and attributes every payment again with today's data, for example once the site identifies users or sends the checkout event. Queued (202); 404 without a connection.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":["queued"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/integrations/dodo/sync":{"post":{"operationId":"syncDodo","summary":"Sync Dodo Payments now","tags":["Payment providers"],"description":"Queues a sync of new payments now rather than at the next scheduled run, and resumes a connection halted by a rejected key. 404 without a connection.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":["queued"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/integrations/polar":{"get":{"operationId":"getPolarConnection","summary":"Get the Polar connection","tags":["Payment providers"],"description":"The connection's state: key hint, live or test mode, account, sync status, last sync and last error; never the key.\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"provider":{"type":"string","enum":["stripe","dodo","polar"]},"connected":{"type":"boolean"},"keyHint":{"description":"A non-secret type prefix when the provider has one and the last four characters, e.g. rk_live_…wxyz","type":["string","null"]},"livemode":{"description":"Live/production (true) or test/sandbox (false)","type":["boolean","null"]},"accountName":{"type":["string","null"]},"status":{"anyOf":[{"type":"string","enum":["ok","syncing","error"]},{"type":"null"}]},"lastSyncAt":{"type":["string","null"]},"lastError":{"description":"A safe message for people; never the provider's text or the key","type":["string","null"]},"notice":{"description":"An advisory about a connection that syncs but not completely (e.g. a Stripe key without Read access to Invoices: no renewals); never the provider's text","type":["string","null"]},"backfillDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["provider","connected","keyHint","livemode","accountName","status","lastSyncAt","lastError","notice","backfillDays"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"put":{"operationId":"connectPolar","summary":"Connect Polar","tags":["Payment providers"],"description":"Checks the API key with the provider (400 when it is rejected or lacks a read permission), stores it encrypted, and queues the import of the last `backfillDays` days of payments (90 by default, 365 at most). When the key belongs to another account or mode than the payments already synced, those are deleted.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"secretKey":{"type":"string","pattern":"^polar_oat_[A-Za-z0-9]{20,200}$","description":"A Polar API key; never returned, stored encrypted"},"backfillDays":{"default":90,"type":"integer","minimum":1,"maximum":365}},"required":["secretKey"],"additionalProperties":false}}}},"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"provider":{"type":"string","enum":["stripe","dodo","polar"]},"connected":{"type":"boolean"},"keyHint":{"description":"A non-secret type prefix when the provider has one and the last four characters, e.g. rk_live_…wxyz","type":["string","null"]},"livemode":{"description":"Live/production (true) or test/sandbox (false)","type":["boolean","null"]},"accountName":{"type":["string","null"]},"status":{"anyOf":[{"type":"string","enum":["ok","syncing","error"]},{"type":"null"}]},"lastSyncAt":{"type":["string","null"]},"lastError":{"description":"A safe message for people; never the provider's text or the key","type":["string","null"]},"notice":{"description":"An advisory about a connection that syncs but not completely (e.g. a Stripe key without Read access to Invoices: no renewals); never the provider's text","type":["string","null"]},"backfillDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["provider","connected","keyHint","livemode","accountName","status","lastSyncAt","lastError","notice","backfillDays"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"disconnectPolar","summary":"Disconnect Polar","tags":["Payment providers"],"description":"Deletes the connection and its key; with `deletePayments=true`, the payments synced from it too.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"deletePayments","required":false,"description":"Also delete this provider's synced payments"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"responses":{"204":{"description":"No Content"}}}},"/api/v1/sites/{siteId}/integrations/polar/rematch":{"post":{"operationId":"rematchPolarPayments","summary":"Re-run Polar attribution","tags":["Payment providers"],"description":"Re-reads the connection's whole history window and attributes every payment again with today's data, for example once the site identifies users or sends the checkout event. Queued (202); 404 without a connection.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":["queued"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/integrations/polar/sync":{"post":{"operationId":"syncPolar","summary":"Sync Polar now","tags":["Payment providers"],"description":"Queues a sync of new payments now rather than at the next scheduled run, and resumes a connection halted by a rejected key. 404 without a connection.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":["queued"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/integrations/stripe":{"get":{"operationId":"getStripeConnection","summary":"Get the Stripe connection","tags":["Payment providers"],"description":"The connection's state: key hint, live or test mode, account, sync status, last sync and last error; never the key.\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"provider":{"type":"string","enum":["stripe","dodo","polar"]},"connected":{"type":"boolean"},"keyHint":{"description":"A non-secret type prefix when the provider has one and the last four characters, e.g. rk_live_…wxyz","type":["string","null"]},"livemode":{"description":"Live/production (true) or test/sandbox (false)","type":["boolean","null"]},"accountName":{"type":["string","null"]},"status":{"anyOf":[{"type":"string","enum":["ok","syncing","error"]},{"type":"null"}]},"lastSyncAt":{"type":["string","null"]},"lastError":{"description":"A safe message for people; never the provider's text or the key","type":["string","null"]},"notice":{"description":"An advisory about a connection that syncs but not completely (e.g. a Stripe key without Read access to Invoices: no renewals); never the provider's text","type":["string","null"]},"backfillDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["provider","connected","keyHint","livemode","accountName","status","lastSyncAt","lastError","notice","backfillDays"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"put":{"operationId":"connectStripe","summary":"Connect Stripe","tags":["Payment providers"],"description":"Checks the API key with the provider (400 when it is rejected or lacks a read permission), stores it encrypted, and queues the import of the last `backfillDays` days of payments (90 by default, 365 at most). When the key belongs to another account or mode than the payments already synced, those are deleted.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"secretKey":{"type":"string","pattern":"^(sk|rk)_(live|test)_[A-Za-z0-9_]{8,240}$","description":"A Stripe API key; never returned, stored encrypted"},"backfillDays":{"default":90,"type":"integer","minimum":1,"maximum":365}},"required":["secretKey"],"additionalProperties":false}}}},"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"provider":{"type":"string","enum":["stripe","dodo","polar"]},"connected":{"type":"boolean"},"keyHint":{"description":"A non-secret type prefix when the provider has one and the last four characters, e.g. rk_live_…wxyz","type":["string","null"]},"livemode":{"description":"Live/production (true) or test/sandbox (false)","type":["boolean","null"]},"accountName":{"type":["string","null"]},"status":{"anyOf":[{"type":"string","enum":["ok","syncing","error"]},{"type":"null"}]},"lastSyncAt":{"type":["string","null"]},"lastError":{"description":"A safe message for people; never the provider's text or the key","type":["string","null"]},"notice":{"description":"An advisory about a connection that syncs but not completely (e.g. a Stripe key without Read access to Invoices: no renewals); never the provider's text","type":["string","null"]},"backfillDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["provider","connected","keyHint","livemode","accountName","status","lastSyncAt","lastError","notice","backfillDays"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"disconnectStripe","summary":"Disconnect Stripe","tags":["Payment providers"],"description":"Deletes the connection and its key; with `deletePayments=true`, the payments synced from it too.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"deletePayments","required":false,"description":"Also delete this provider's synced payments"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"responses":{"204":{"description":"No Content"}}}},"/api/v1/sites/{siteId}/integrations/stripe/rematch":{"post":{"operationId":"rematchStripePayments","summary":"Re-run Stripe attribution","tags":["Payment providers"],"description":"Re-reads the connection's whole history window and attributes every payment again with today's data, for example once the site identifies users or sends the checkout event. Queued (202); 404 without a connection.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":["queued"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/integrations/stripe/sync":{"post":{"operationId":"syncStripe","summary":"Sync Stripe now","tags":["Payment providers"],"description":"Queues a sync of new payments now rather than at the next scheduled run, and resumes a connection halted by a rejected key. 404 without a connection.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":["queued"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/journeys":{"get":{"operationId":"getJourneys","summary":"Get journeys","tags":["Journeys"],"description":"The most common page paths of the window's sessions, `steps` pages long at most (3 by default; repeats in a row count once), optionally from the first page matching `start_page` and up to the first matching `end_page` (globs), by section with `group=section`; with how many sessions took each and, with `goal`, how many of those converted.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":3,"type":"integer","minimum":2,"maximum":10},"in":"query","name":"steps","required":false},{"schema":{"type":"string","minLength":1,"maxLength":1024},"in":"query","name":"start_page","required":false},{"schema":{"type":"string","minLength":1,"maxLength":1024},"in":"query","name":"end_page","required":false},{"schema":{"default":"page","type":"string","enum":["page","section"]},"in":"query","name":"group","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"goal","required":false},{"schema":{"default":100,"type":"integer","minimum":1,"maximum":500},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total_sessions":{"type":"number"},"paths":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"sessions":{"type":"number"},"percentage":{"type":"number"},"conversions":{"type":["number","null"]}},"required":["path","sessions","percentage","conversions"],"additionalProperties":false}}},"required":["total_sessions","paths"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/journeys/sessions":{"get":{"operationId":"listJourneySessions","summary":"List a journey's sessions","tags":["Journeys"],"description":"The sessions that took one path (`path`, a JSON array of its pages, with the report's `steps`, `start_page`, `end_page` and `group`), a page at a time (`meta.nextCursor`).\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `sessions:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":3,"type":"integer","minimum":2,"maximum":10},"in":"query","name":"steps","required":false},{"schema":{"type":"string","minLength":1,"maxLength":1024},"in":"query","name":"start_page","required":false},{"schema":{"type":"string","minLength":1,"maxLength":1024},"in":"query","name":"end_page","required":false},{"schema":{"default":"page","type":"string","enum":["page","section"]},"in":"query","name":"group","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"path","required":true},{"schema":{"type":"string","maxLength":512},"in":"query","name":"cursor","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]},{"shareToken":["sessions:read"]},{"shareTokenQuery":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"session_id":{"type":"string"},"visitor_id":{"type":"string"},"user_id":{"type":"string"},"started_at":{"type":"string"},"ended_at":{"type":"string"},"duration":{"type":"number"},"pageviews":{"type":"number"},"events":{"type":"number"},"entry_page":{"type":"string"},"exit_page":{"type":"string"},"referrer_domain":{"type":"string"},"channel":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"device_type":{"type":"string"}},"required":["session_id","visitor_id","user_id","started_at","ended_at","duration","pageviews","events","entry_page","exit_page","referrer_domain","channel","country","city","browser","os","device_type"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/live":{"get":{"operationId":"getLive","summary":"Get the live summary","tags":["Live"],"description":"Visitors seen in the last 5 minutes (null when presence cannot be read) and, over the last 30 minutes, pageviews per minute and the top 10 pages (by pageviews), referrers and countries (by visitors). Never cached.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"visitors":{"description":"Visitors seen in the last 5 minutes; null when Valkey cannot be read","type":["number","null"]},"pageviews_last_30m":{"type":"array","items":{"type":"object","properties":{"minute":{"type":"string"},"count":{"type":"number"}},"required":["minute","count"],"additionalProperties":false}},"top_pages":{"type":"array","items":{"type":"object","properties":{"pathname":{"type":"string"},"pageviews":{"type":"number"}},"required":["pathname","pageviews"],"additionalProperties":false}},"top_referrers":{"type":"array","items":{"type":"object","properties":{"referrer_domain":{"type":"string"},"visitors":{"type":"number"}},"required":["referrer_domain","visitors"],"additionalProperties":false}},"countries":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"visitors":{"type":"number"}},"required":["country","visitors"],"additionalProperties":false}}},"required":["visitors","pageviews_last_30m","top_pages","top_referrers","countries"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/live/stream":{"get":{"operationId":"streamLive","summary":"Stream live activity","tags":["Live"],"description":"Server-sent events (`text/event-stream`; 406 when `Accept` refuses it): `event` for each pageview or event as it arrives (10 a second at most, the rest dropped), and `count` (visitors in the last 5 minutes) every 5 seconds. Members and API keys holding `sessions:read` (not share links) also get each visitor's detail: `visitor` on each pageview, and `leave` when a visitor goes. Share links pass their token as `?share=`, since EventSource sets no headers. Access is checked again every minute, and a stream ends after an hour (EventSource reconnects). Open streams are capped per caller, per organization, per owner across organizations (a user with the API keys it created), and for guests per site (429).\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"The event stream","content":{"text/event-stream":{"schema":{"type":"string","description":"`event`, `count`, `visitor` and `leave`"}}}}}}},"/api/v1/sites/{siteId}/live/visitors":{"get":{"operationId":"listLiveVisitors","summary":"List live visitors","tags":["Live"],"description":"One row per visitor seen in the last 5 minutes, most recent first: approximate location, device, referrer, current page, pageviews and times; 1,000 at most, `meta.truncated` when there were more. Never cached.\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"visitor_id":{"type":"string"},"lat":{"description":"Last known, 2 decimals","type":["number","null"]},"lon":{"type":["number","null"]},"country":{"type":"string"},"city":{"type":"string"},"device_type":{"type":"string"},"os":{"type":"string"},"browser":{"type":"string"},"referrer_domain":{"type":"string","description":"The session's first non-empty one"},"pathname":{"type":"string","description":"Latest pageview"},"pageviews":{"type":"number"},"started_at":{"type":"string"},"last_seen_at":{"type":"string"}},"required":["visitor_id","lat","lon","country","city","device_type","os","browser","referrer_domain","pathname","pageviews","started_at","last_seen_at"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/notifications":{"get":{"operationId":"getNotificationSettings","summary":"Get the notification settings","tags":["Notifications"],"description":"Who gets new-sale emails, the members who may (those who can read the site's revenue), and the state of each webhook channel (a hint of its URL, never the URL).\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string"},"description":"User ids of the members new-sale emails go to"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["userId","name","email"],"additionalProperties":false},"description":"The organization members who can read this site's revenue: the ones recipients are chosen from"},"webhooks":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["slack","discord"]},"connected":{"type":"boolean"},"enabled":{"type":"boolean"},"urlHint":{"description":"The host and the last four characters; the URL itself is never returned","type":["string","null"]},"lastError":{"description":"Why the last delivery failed or was not sent (a fixed message), null after a success","type":["string","null"]},"lastSentAt":{"type":["string","null"]}},"required":["kind","connected","enabled","urlHint","lastError","lastSentAt"],"additionalProperties":false}}},"required":["recipients","members","webhooks"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/notifications/discord":{"put":{"operationId":"setDiscordNotifications","summary":"Set the Discord webhook","tags":["Notifications"],"description":"Sets the webhook URL (stored encrypted, never returned) or switches it on or off. Setting a URL or switching it on needs `revenue:read` too (403 otherwise), since the webhook then receives every sale. Whoever sets the URL is recorded: once that member or API key can no longer read the site's revenue (or is deleted), the webhook gets nothing and its `lastError` says so until the URL is set again. 400 for a URL that is not the service's incoming webhook URL, or for switching before a URL is set.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"A Discord incoming webhook URL (https://discord.com/api/webhooks/…); stored encrypted, never returned","type":"string","maxLength":512},"enabled":{"description":"Off keeps the webhook but sends nothing (default on with a new URL)","type":"boolean"}},"additionalProperties":false}}}},"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string"},"description":"User ids of the members new-sale emails go to"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["userId","name","email"],"additionalProperties":false},"description":"The organization members who can read this site's revenue: the ones recipients are chosen from"},"webhooks":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["slack","discord"]},"connected":{"type":"boolean"},"enabled":{"type":"boolean"},"urlHint":{"description":"The host and the last four characters; the URL itself is never returned","type":["string","null"]},"lastError":{"description":"Why the last delivery failed or was not sent (a fixed message), null after a success","type":["string","null"]},"lastSentAt":{"type":["string","null"]}},"required":["kind","connected","enabled","urlHint","lastError","lastSentAt"],"additionalProperties":false}}},"required":["recipients","members","webhooks"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteDiscordNotifications","summary":"Remove the Discord webhook","tags":["Notifications"],"description":"Deletes the webhook and its stored URL.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string"},"description":"User ids of the members new-sale emails go to"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["userId","name","email"],"additionalProperties":false},"description":"The organization members who can read this site's revenue: the ones recipients are chosen from"},"webhooks":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["slack","discord"]},"connected":{"type":"boolean"},"enabled":{"type":"boolean"},"urlHint":{"description":"The host and the last four characters; the URL itself is never returned","type":["string","null"]},"lastError":{"description":"Why the last delivery failed or was not sent (a fixed message), null after a success","type":["string","null"]},"lastSentAt":{"type":["string","null"]}},"required":["kind","connected","enabled","urlHint","lastError","lastSentAt"],"additionalProperties":false}}},"required":["recipients","members","webhooks"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/notifications/email":{"put":{"operationId":"setEmailNotifications","summary":"Set the new-sale email recipients","tags":["Notifications"],"description":"Replaces the members who get an email for each new sale; each must be a member who can read the site's revenue (400 otherwise).\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userIds":{"maxItems":200,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"The members new-sale emails go to (replaces the list)"}},"required":["userIds"],"additionalProperties":false}}}},"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string"},"description":"User ids of the members new-sale emails go to"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["userId","name","email"],"additionalProperties":false},"description":"The organization members who can read this site's revenue: the ones recipients are chosen from"},"webhooks":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["slack","discord"]},"connected":{"type":"boolean"},"enabled":{"type":"boolean"},"urlHint":{"description":"The host and the last four characters; the URL itself is never returned","type":["string","null"]},"lastError":{"description":"Why the last delivery failed or was not sent (a fixed message), null after a success","type":["string","null"]},"lastSentAt":{"type":["string","null"]}},"required":["kind","connected","enabled","urlHint","lastError","lastSentAt"],"additionalProperties":false}}},"required":["recipients","members","webhooks"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/notifications/slack":{"put":{"operationId":"setSlackNotifications","summary":"Set the Slack webhook","tags":["Notifications"],"description":"Sets the webhook URL (stored encrypted, never returned) or switches it on or off. Setting a URL or switching it on needs `revenue:read` too (403 otherwise), since the webhook then receives every sale. Whoever sets the URL is recorded: once that member or API key can no longer read the site's revenue (or is deleted), the webhook gets nothing and its `lastError` says so until the URL is set again. 400 for a URL that is not the service's incoming webhook URL, or for switching before a URL is set.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"A Slack incoming webhook URL (https://hooks.slack.com/services/…); stored encrypted, never returned","type":"string","maxLength":512},"enabled":{"description":"Off keeps the webhook but sends nothing (default on with a new URL)","type":"boolean"}},"additionalProperties":false}}}},"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string"},"description":"User ids of the members new-sale emails go to"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["userId","name","email"],"additionalProperties":false},"description":"The organization members who can read this site's revenue: the ones recipients are chosen from"},"webhooks":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["slack","discord"]},"connected":{"type":"boolean"},"enabled":{"type":"boolean"},"urlHint":{"description":"The host and the last four characters; the URL itself is never returned","type":["string","null"]},"lastError":{"description":"Why the last delivery failed or was not sent (a fixed message), null after a success","type":["string","null"]},"lastSentAt":{"type":["string","null"]}},"required":["kind","connected","enabled","urlHint","lastError","lastSentAt"],"additionalProperties":false}}},"required":["recipients","members","webhooks"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteSlackNotifications","summary":"Remove the Slack webhook","tags":["Notifications"],"description":"Deletes the webhook and its stored URL.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string"},"description":"User ids of the members new-sale emails go to"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["userId","name","email"],"additionalProperties":false},"description":"The organization members who can read this site's revenue: the ones recipients are chosen from"},"webhooks":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["slack","discord"]},"connected":{"type":"boolean"},"enabled":{"type":"boolean"},"urlHint":{"description":"The host and the last four characters; the URL itself is never returned","type":["string","null"]},"lastError":{"description":"Why the last delivery failed or was not sent (a fixed message), null after a success","type":["string","null"]},"lastSentAt":{"type":["string","null"]}},"required":["kind","connected","enabled","urlHint","lastError","lastSentAt"],"additionalProperties":false}}},"required":["recipients","members","webhooks"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/notifications/test":{"post":{"operationId":"testNotification","summary":"Send a test notification","tags":["Notifications"],"description":"Sends a fictional sale to one channel now (email: to the signed-in caller only). 200 whether the delivery worked or not (`ok`, and why it failed); 400 when there is nothing to send to: no webhook URL set, or an email asked by an API key or by a caller who cannot read the site's revenue.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["email","slack","discord"],"description":"email goes to the signed-in caller only; a webhook gets the message even while switched off"}},"required":["channel"],"additionalProperties":false}}}},"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"},"message":{"description":"Why it failed (a fixed message), or null","type":["string","null"]}},"required":["ok","message"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/overview":{"get":{"operationId":"getOverview","summary":"Get the overview","tags":["Analytics"],"description":"Visitors, sessions, pageviews, events, bounce rate, session durations and views per session in the window; with a comparison window, the same figures for it under `previous`.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"visitors":{"type":"number"},"sessions":{"type":"number"},"pageviews":{"type":"number"},"events":{"type":"number"},"bounce_rate":{"type":"number"},"avg_session_duration":{"type":"number"},"median_session_duration":{"type":"number"},"views_per_session":{"type":"number"},"previous":{"type":"object","properties":{"visitors":{"type":"number"},"sessions":{"type":"number"},"pageviews":{"type":"number"},"events":{"type":"number"},"bounce_rate":{"type":"number"},"avg_session_duration":{"type":"number"},"median_session_duration":{"type":"number"},"views_per_session":{"type":"number"}},"required":["visitors","sessions","pageviews","events","bounce_rate","avg_session_duration","median_session_duration","views_per_session"],"additionalProperties":false}},"required":["visitors","sessions","pageviews","events","bounce_rate","avg_session_duration","median_session_duration","views_per_session"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/pages":{"get":{"operationId":"listPages","summary":"List pages","tags":["Analytics"],"description":"Each page (or section, with `group=section`) with its visitors, sessions, pageviews, entries, exits, bounce rate and time on page, ranked by pageviews (or by entries or exits, with `view`), a page at a time (`limit` and `offset`; `meta.totalCount`); with `goal`, its converting sessions.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":"all","type":"string","enum":["all","entry","exit"]},"in":"query","name":"view","required":false,"description":"`all` pages ranked by pageviews, or the pages with entries (`entry`) or exits (`exit`) ranked by them"},{"schema":{"default":"page","type":"string","enum":["page","section"]},"in":"query","name":"group","required":false,"description":"`section` groups /a/b/c under /a/**"},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false,"description":"Case-insensitive match on the pathname or the title"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"goal","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"pathname":{"type":"string"},"title":{"type":"string"},"visitors":{"type":"number"},"sessions":{"type":"number","description":"Sessions with a pageview of the page"},"pageviews":{"type":"number"},"entries":{"type":"number"},"exits":{"type":"number"},"bounce_rate":{"type":"number"},"time_on_page":{"type":"number","description":"Mean seconds to the session's next pageview; exits are excluded"},"conversions":{"description":"With `goal`: the page's sessions that converted","type":"number"}},"required":["pathname","title","visitors","sessions","pageviews","entries","exits","bounce_rate","time_on_page"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/pages/trends":{"get":{"operationId":"getPageTrends","summary":"Get page trends","tags":["Analytics"],"description":"Pageviews per time bucket of each of up to 20 pathnames.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"paths","required":true,"description":"JSON array of 1-20 pathnames, matched exactly; section keys such as /blog/** are not resolved (they match no pageview)"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"series":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"pageviews":{"type":"number"}},"required":["t","pageviews"],"additionalProperties":false}}},"required":["key","series"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/payments":{"get":{"operationId":"listPayments","summary":"List payments","tags":["Revenue"],"description":"The window's payments from every provider (or of one `currency` or `status`), newest first, with how each was attributed; the ids, the customer email and the linked visits need `sessions:read` too (null otherwise). A page at a time (`meta.nextCursor`).\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"in":"query","name":"currency","required":false,"description":"ISO 4217 code: only payments in this currency; default: every currency"},{"schema":{"type":"string","enum":["last_non_direct","first_visit","last_visit"]},"in":"query","name":"model","required":false,"description":"Which visit of the paying person a payment is credited to: last_non_direct, first_visit (both within the site's lookback window) or last_visit; default: the site's model"},{"schema":{"type":"string","enum":["paid","partially_refunded","refunded"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"search","required":false,"description":"Substring of the payment id, utm_source, referrer domain or (sessions:read) email"},{"schema":{"type":"string","maxLength":2200},"in":"query","name":"cursor","required":false,"description":"`meta.nextCursor` of the previous page"},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"payment_id":{"type":"string"},"provider":{"type":"string","enum":["stripe","dodo","polar","custom"]},"ts":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"refunded_amount":{"type":"number"},"status":{"type":"string","enum":["paid","partially_refunded","refunded"]},"customer_email":{"description":"Only with sessions:read, and only when the site stores emails","type":["string","null"]},"attribution":{"type":"string","enum":["checkout_ref","user_id","email","customer","none"]},"session_id":{"description":"The linked visit (last_visit); only with sessions:read","type":["string","null"]},"visitor_id":{"description":"Only with sessions:read","type":["string","null"]},"user_id":{"description":"Only with sessions:read","type":["string","null"]},"credited_session_id":{"description":"The visit the credit model credits, whose attributes the row shows; only with sessions:read","type":["string","null"]},"channel":{"type":"string"},"referrer_domain":{"type":"string"},"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"device_type":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"entry_page":{"type":"string"},"affiliate":{"type":"string"},"time_to_convert":{"description":"Seconds from the attributed user's first event to the payment","type":["number","null"]}},"required":["payment_id","provider","ts","amount","currency","refunded_amount","status","customer_email","attribution","session_id","visitor_id","user_id","credited_session_id","channel","referrer_domain","utm_source","utm_medium","utm_campaign","country","city","device_type","browser","os","entry_page","affiliate","time_to_convert"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"post":{"operationId":"recordPayment","summary":"Record a payment","tags":["Revenue"],"description":"Records a payment from your own billing (provider `custom`), or updates the one recorded with the same `payment_id`: 201 when it is new, 200 when it existed (sending the same request again changes nothing). It is linked to a visit by `ref` (a `checkout` event's ref), then `user_id`/`customer_id` (an identified user), then `email` (the `email` trait your server sent for a user through the server-side identify), then an earlier linked payment of the same `customer_id`; an update that names none of them keeps the link. A different `ts` or `currency` replaces the recorded payment. 300 requests a minute per API key.\n\nRequires an API key holding `revenue:write` on the site. Session cookies and share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_id":{"type":"string","pattern":"^[!-~]{1,255}$","description":"Your billing system's id of the payment (order, transaction or invoice id), unique within the site"},"amount":{"type":"integer","minimum":1,"maximum":1000000000000,"description":"What the customer paid, tax included: an integer in the currency's minor unit (1999 is 19.99 USD, 1200 is 1,200 JPY)"},"currency":{"description":"ISO 4217 code, any case (stored lower-case)","type":"string","pattern":"^[A-Za-z]{3}$"},"ts":{"description":"When it was paid, ISO 8601 with a zone, from 2000-01-01T00:00:00Z to 5 minutes past the server's clock; default: now, or the recorded time of a payment already recorded","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"refunded_amount":{"description":"Refunded so far, in the same unit, 0 to amount; default: 0, or what was recorded before","anyOf":[{"type":"integer","minimum":0,"maximum":1000000000000},{"type":"null"}]},"status":{"description":"Instead of refunded_amount: paid (0) or refunded (all); with it, it must agree","anyOf":[{"type":"string","enum":["paid","partially_refunded","refunded"]},{"type":"null"}]},"email":{"description":"The customer's email: links the payment to a user your server identified with that `email` trait","anyOf":[{"type":"string","maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+$"},{"type":"null"}]},"ref":{"description":"The `ref` your page sent with its `checkout` event (pilotfox.event('checkout', { ref }))","anyOf":[{"type":"string","minLength":1,"maxLength":512,"pattern":"^\\P{Cc}+$"},{"type":"null"}]},"user_id":{"description":"The id you passed to pilotfox.identify() for the buyer","anyOf":[{"type":"string","minLength":1,"maxLength":255,"pattern":"^\\P{Cc}+$"},{"type":"null"}]},"customer_id":{"description":"Your billing system's customer id: links this customer's later payments to the same visit, and is matched like user_id for sites that identify users by it","anyOf":[{"type":"string","minLength":1,"maxLength":255,"pattern":"^\\P{Cc}+$"},{"type":"null"}]}},"required":["payment_id","amount","currency"],"additionalProperties":false}}}},"security":[{"apiKey":["revenue:write"]},{"apiKeyBearer":["revenue:write"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:write","keysOnly":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"payment_id":{"type":"string"},"provider":{"type":"string","enum":["custom"]},"ts":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"refunded_amount":{"type":"number"},"status":{"type":"string","enum":["paid","partially_refunded","refunded"]},"attribution":{"type":"string","enum":["checkout_ref","user_id","email","customer","none"],"description":"How the payment is linked to a visit: checkout_ref, user_id, email or customer (the first that matched), or none"}},"required":["payment_id","provider","ts","amount","currency","refunded_amount","status","attribution"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"payment_id":{"type":"string"},"provider":{"type":"string","enum":["custom"]},"ts":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"refunded_amount":{"type":"number"},"status":{"type":"string","enum":["paid","partially_refunded","refunded"]},"attribution":{"type":"string","enum":["checkout_ref","user_id","email","customer","none"],"description":"How the payment is linked to a visit: checkout_ref, user_id, email or customer (the first that matched), or none"}},"required":["payment_id","provider","ts","amount","currency","refunded_amount","status","attribution"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/payments/{paymentId}":{"delete":{"operationId":"deletePayment","summary":"Delete a recorded payment","tags":["Revenue"],"description":"Deletes a payment recorded through this API (a test payment, a mistake) from every report. 404 when none. 300 requests a minute per API key.\n\nRequires an API key holding `revenue:write` on the site. Session cookies and share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","pattern":"^[!-~]{1,255}$"},"in":"path","name":"paymentId","required":true,"description":"Your billing system's id of the payment (order, transaction or invoice id), unique within the site"}],"security":[{"apiKey":["revenue:write"]},{"apiKeyBearer":["revenue:write"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:write","keysOnly":true},"responses":{"204":{"description":"No Content"}}}},"/api/v1/sites/{siteId}/payments/{paymentId}/journey":{"get":{"operationId":"getPaymentJourney","summary":"Get a payment's journey","tags":["Revenue"],"description":"The paying person's visits up to the payment (the latest 50), with their pages and the credit models that credit each. Needs `sessions:read` too (403 otherwise); 404 for an unknown payment.\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string","enum":["stripe","dodo","polar","custom"]},"in":"query","name":"provider","required":false,"description":"The payment's provider (`provider` of the payment row), for an id two providers both use"},{"schema":{"type":"string","enum":["last_non_direct","first_visit","last_visit"]},"in":"query","name":"model","required":false,"description":"Which visit of the paying person a payment is credited to: last_non_direct, first_visit (both within the site's lookback window) or last_visit; default: the site's model"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"path","name":"paymentId","required":true}],"security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"payment":{"type":"object","properties":{"payment_id":{"type":"string"},"provider":{"type":"string","enum":["stripe","dodo","polar","custom"]},"ts":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"refunded_amount":{"type":"number"},"status":{"type":"string","enum":["paid","partially_refunded","refunded"]},"customer_email":{"description":"Only with sessions:read, and only when the site stores emails","type":["string","null"]},"attribution":{"type":"string","enum":["checkout_ref","user_id","email","customer","none"]},"session_id":{"description":"The linked visit (last_visit); only with sessions:read","type":["string","null"]},"visitor_id":{"description":"Only with sessions:read","type":["string","null"]},"user_id":{"description":"Only with sessions:read","type":["string","null"]},"credited_session_id":{"description":"The visit the credit model credits, whose attributes the row shows; only with sessions:read","type":["string","null"]},"channel":{"type":"string"},"referrer_domain":{"type":"string"},"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"device_type":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"entry_page":{"type":"string"},"affiliate":{"type":"string"},"time_to_convert":{"description":"Seconds from the attributed user's first event to the payment","type":["number","null"]}},"required":["payment_id","provider","ts","amount","currency","refunded_amount","status","customer_email","attribution","session_id","visitor_id","user_id","credited_session_id","channel","referrer_domain","utm_source","utm_medium","utm_campaign","country","city","device_type","browser","os","entry_page","affiliate","time_to_convert"],"additionalProperties":false},"first_seen_at":{"type":["string","null"]},"time_to_convert":{"type":["number","null"]},"credit_model":{"type":"string","enum":["last_non_direct","first_visit","last_visit"],"description":"The credit model applied (model= or the site's)"},"credit_window_days":{"type":"number"},"sessions":{"type":"array","items":{"type":"object","properties":{"session_id":{"type":"string"},"credited_by":{"type":"array","items":{"type":"string","enum":["last_non_direct","first_visit","last_visit"]},"description":"The credit models that credit this visit"},"started_at":{"type":"string"},"ended_at":{"type":"string"},"duration":{"type":"number","description":"Seconds, millisecond precision"},"entry_page":{"type":"string"},"exit_page":{"type":"string"},"referrer_domain":{"type":"string"},"channel":{"type":"string"},"utm_source":{"type":"string"},"utm_campaign":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"device_type":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"affiliate":{"type":"string"},"pageviews":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"string"},"pathname":{"type":"string"},"page_title":{"type":"string"}},"required":["ts","pathname","page_title"],"additionalProperties":false}}},"required":["session_id","credited_by","started_at","ended_at","duration","entry_page","exit_page","referrer_domain","channel","utm_source","utm_campaign","country","city","device_type","browser","os","affiliate","pageviews"],"additionalProperties":false}}},"required":["payment","first_seen_at","time_to_convert","credit_model","credit_window_days","sessions"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/payments/{paymentId}/refund":{"post":{"operationId":"refundPayment","summary":"Refund a recorded payment","tags":["Revenue"],"description":"Sets the refunded total of a payment recorded through this API (not a synced provider's): the whole amount by default (the body may be left out), or `refunded_amount` (the total so far, so sending it again changes nothing). 404 when no such payment was recorded. 300 requests a minute per API key.\n\nRequires an API key holding `revenue:write` on the site. Session cookies and share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"refunded_amount":{"description":"The total refunded so far (not this refund's part), 0 to amount; default: the whole amount","anyOf":[{"type":"integer","minimum":0,"maximum":1000000000000},{"type":"null"}]}},"additionalProperties":false},{"type":"null"}]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","pattern":"^[!-~]{1,255}$"},"in":"path","name":"paymentId","required":true,"description":"Your billing system's id of the payment (order, transaction or invoice id), unique within the site"}],"security":[{"apiKey":["revenue:write"]},{"apiKeyBearer":["revenue:write"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:write","keysOnly":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"payment_id":{"type":"string"},"provider":{"type":"string","enum":["custom"]},"ts":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"refunded_amount":{"type":"number"},"status":{"type":"string","enum":["paid","partially_refunded","refunded"]},"attribution":{"type":"string","enum":["checkout_ref","user_id","email","customer","none"],"description":"How the payment is linked to a visit: checkout_ref, user_id, email or customer (the first that matched), or none"}},"required":["payment_id","provider","ts","amount","currency","refunded_amount","status","attribution"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/proxy-secret":{"get":{"operationId":"getProxySecret","summary":"Get the proxy secret state","tags":["Sites"],"description":"Whether the site has a first-party proxy secret, with its last four characters and creation date; never the secret itself.\n\nRequires `site:read` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:read"]},{"apiKeyBearer":["site:read"]},{"session":["site:read"]}],"x-pilotfox-access":{"kind":"site","permission":"site:read"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"enabled":{"type":"boolean"},"hint":{"type":["string","null"]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["enabled","hint","createdAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"post":{"operationId":"rotateProxySecret","summary":"Create or replace the proxy secret","tags":["Sites"],"description":"A new first-party proxy secret, replacing the previous one at once. This answer is the only one that carries it. The proxy sends it in `X-PilotFox-Proxy-Secret`, with the visitor's address in `X-PilotFox-IP`. Send `{}` as the body: a request without one is 400.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"secret":{"type":"string"},"hint":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["secret","hint","createdAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteProxySecret","summary":"Delete the proxy secret","tags":["Sites"],"description":"Removes the secret: ingest requests that still carry it get 400 from then on.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/replays":{"get":{"operationId":"listReplays","summary":"List session replays","tags":["Replays"],"description":"The window's recorded sessions at least `min_duration` seconds long (the site's replay setting by default), newest first, a page at a time (`meta.nextCursor`); visitor and user ids only with `sessions:read`. Never cached.\n\nRequires `replay:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `replay:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"integer","minimum":0,"maximum":1000000},"in":"query","name":"min_duration","required":false,"description":"Seconds; default the site's settings.replay.minDurationSeconds"},{"schema":{"type":"string","maxLength":2200},"in":"query","name":"cursor","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["replay:read"]},{"apiKeyBearer":["replay:read"]},{"session":["replay:read"]},{"shareToken":["replay:read"]},{"shareTokenQuery":["replay:read"]}],"x-pilotfox-access":{"kind":"site","permission":"replay:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"session_id":{"type":"string"},"visitor_id":{"description":"null without sessions:read","type":["string","null"]},"user_id":{"description":"The identified uid; null when anonymous or without sessions:read","type":["string","null"]},"started_at":{"type":"string"},"ended_at":{"type":"string"},"duration":{"type":"number","description":"Seconds, millisecond precision"},"events":{"type":"number"},"chunks":{"type":"number"},"bytes":{"type":"number"},"entry_page":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"region_name":{"type":"string"},"city":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"device_type":{"type":"string"},"screen":{"type":"string","description":"\"WxH\", or \"\" when unknown"}},"required":["session_id","visitor_id","user_id","started_at","ended_at","duration","events","chunks","bytes","entry_page","country","region","region_name","city","browser","os","device_type","screen"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/replays/{sessionId}":{"get":{"operationId":"getReplay","summary":"Get a session replay","tags":["Replays"],"description":"One recorded session and the index of its chunks.\n\nRequires `replay:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `replay:read` scope.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"sessionId","required":true}],"security":[{"apiKey":["replay:read"]},{"apiKeyBearer":["replay:read"]},{"session":["replay:read"]},{"shareToken":["replay:read"]},{"shareTokenQuery":["replay:read"]}],"x-pilotfox-access":{"kind":"site","permission":"replay:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"session_id":{"type":"string"},"visitor_id":{"description":"null without sessions:read","type":["string","null"]},"user_id":{"description":"The identified uid; null when anonymous or without sessions:read","type":["string","null"]},"started_at":{"type":"string"},"ended_at":{"type":"string"},"duration":{"type":"number","description":"Seconds, millisecond precision"},"events":{"type":"number"},"chunks":{"type":"number"},"bytes":{"type":"number"},"entry_page":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"region_name":{"type":"string"},"city":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"device_type":{"type":"string"},"screen":{"type":"string","description":"\"WxH\", or \"\" when unknown"},"chunks_index":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"number"},"ts_start":{"type":"string"},"ts_end":{"type":"string"},"events":{"type":"number"},"bytes":{"type":"number"}},"required":["seq","ts_start","ts_end","events","bytes"],"additionalProperties":false}}},"required":["session_id","visitor_id","user_id","started_at","ended_at","duration","events","chunks","bytes","entry_page","country","region","region_name","city","browser","os","device_type","screen","chunks_index"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteReplay","summary":"Delete a session replay","tags":["Replays"],"description":"Deletes the recording from object storage and its index; 503, with nothing deleted, when storage is unavailable.\n\nRequires `replay:delete` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"sessionId","required":true}],"security":[{"apiKey":["replay:delete"]},{"apiKeyBearer":["replay:delete"]},{"session":["replay:delete"]}],"x-pilotfox-access":{"kind":"site","permission":"replay:delete"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/replays/{sessionId}/chunks":{"get":{"operationId":"getReplayChunks","summary":"Get replay chunks","tags":["Replays"],"description":"Up to `limit` chunks (5 by default, 20 at most; fewer past a response size cap) of the recording's rrweb events from `from_seq` on, read from object storage; `meta.nextCursor` is the next `from_seq`. 503 when storage is unavailable or too many playbacks are running.\n\nRequires `replay:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `replay:read` scope.","parameters":[{"schema":{"default":0,"type":"integer","minimum":0,"maximum":4294967295},"in":"query","name":"from_seq","required":false},{"schema":{"default":5,"type":"integer","minimum":1,"maximum":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"sessionId","required":true}],"security":[{"apiKey":["replay:read"]},{"apiKeyBearer":["replay:read"]},{"session":["replay:read"]},{"shareToken":["replay:read"]},{"shareTokenQuery":["replay:read"]}],"x-pilotfox-access":{"kind":"site","permission":"replay:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"number"},"events":{"type":"array","items":{}}},"required":["seq","events"],"additionalProperties":false}}},"required":["chunks"],"additionalProperties":false},"meta":{"type":"object","properties":{"nextCursor":{"description":"The next from_seq; null at the end","type":["string","null"]}},"required":["nextCursor"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/reports":{"get":{"operationId":"getReportSubscriptions","summary":"Get my email report subscriptions","tags":["Notifications"],"description":"Whether the signed-in caller gets this site's weekly and monthly email reports (403 for API keys, which have no inbox).\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"weekly":{"type":"boolean"},"monthly":{"type":"boolean"}},"required":["weekly","monthly"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"put":{"operationId":"setReportSubscriptions","summary":"Set my email report subscriptions","tags":["Notifications"],"description":"Subscribes the signed-in caller to this site's weekly or monthly email report (`true`) or unsubscribes them (`false`); a period left out keeps its state. 403 for API keys.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"weekly":{"type":"boolean"},"monthly":{"type":"boolean"}},"additionalProperties":false,"description":"Subscribes (true) or unsubscribes (false) the caller; a period left out keeps its state"}}},"description":"Subscribes (true) or unsubscribes (false) the caller; a period left out keeps its state"},"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"weekly":{"type":"boolean"},"monthly":{"type":"boolean"}},"required":["weekly","monthly"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/reports/preview":{"get":{"operationId":"previewReport","summary":"Preview an email report","tags":["Notifications"],"description":"The report of the last complete week or month (`period`) as the caller would get it, with real data: subject, HTML and text; revenue only for callers with `revenue:read`.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"default":"weekly","type":"string","enum":["weekly","monthly"]},"in":"query","name":"period","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"subject":{"type":"string"},"html":{"type":"string","description":"A complete HTML document; show it sandboxed (no scripts)"},"text":{"type":"string"},"start":{"type":"string","description":"First local day of the period (YYYY-MM-DD)"},"end":{"type":"string","description":"Last local day of the period, included"}},"required":["subject","html","text","start","end"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/retention":{"get":{"operationId":"getRetention","summary":"Get the retention report","tags":["Journeys"],"description":"Cohorts of new users by their first active day, week or month (`unit`) in the window, and the share of each cohort active again 0, 1, 2… periods later. Needs a bounded window (400 for `all=true`).\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":"week","type":"string","enum":["day","week","month"]},"in":"query","name":"unit","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"periods","required":false,"description":"Offset columns; default one per cohort"},{"schema":{"default":90,"type":"integer","minimum":0,"maximum":365},"in":"query","name":"lookback_days","required":false,"description":"Users seen this long before the window are not new"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"unit":{"type":"string","enum":["day","week","month"]},"periods":{"type":"number"},"partialFirst":{"type":"boolean"},"partialLast":{"type":"boolean"},"cohorts":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"size":{"type":"number"},"counts":{"type":"array","items":{"type":["number","null"]}},"rates":{"type":"array","items":{"type":["number","null"]}}},"required":["start","size","counts","rates"],"additionalProperties":false}}},"required":["unit","periods","partialFirst","partialLast","cohorts"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/revenue/breakdown":{"get":{"operationId":"getRevenueBreakdown","summary":"Get a revenue breakdown","tags":["Revenue"],"description":"Revenue, payments and conversion per value of one session dimension (`dim`, as `/breakdown` takes it) or of the payment's `affiliate`, in one currency (`currency`, else the site's), credited by the site's credit model (or `model`), a page at a time (`limit` and `offset`; `meta.totalCount`).\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"in":"query","name":"currency","required":false,"description":"ISO 4217 code: only amounts in this currency count, so every amount of the response is in it (no conversion); default: the site's currency"},{"schema":{"type":"string","enum":["last_non_direct","first_visit","last_visit"]},"in":"query","name":"model","required":false,"description":"Which visit of the paying person a payment is credited to: last_non_direct, first_visit (both within the site's lookback window) or last_visit; default: the site's model"},{"schema":{"type":"string"},"in":"query","name":"dim","required":true,"description":"A session dimension of the registry, or \"affiliate\" (the payment's own)"},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"region":{"type":"string"},"region_name":{"type":"string"},"country":{"type":"string"},"revenue":{"type":"number"},"gross":{"type":"number"},"refunded":{"type":"number"},"payments":{"type":"number"},"paying_visitors":{"type":"number"},"visitors":{"type":"number"},"conversion_rate":{"type":"number"},"percentage":{"type":"number","description":"row revenue ÷ window revenue × 100"}},"required":["value","revenue","gross","refunded","payments","paying_visitors","visitors","conversion_rate","percentage"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/revenue/connections":{"get":{"operationId":"listRevenueConnections","summary":"List payment provider connections","tags":["Payment providers"],"description":"Every supported provider (Stripe, Polar, Dodo Payments) with its connection state on the site; never a key.\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["stripe","dodo","polar"]},"connected":{"type":"boolean"},"keyHint":{"description":"A non-secret type prefix when the provider has one and the last four characters, e.g. rk_live_…wxyz","type":["string","null"]},"livemode":{"description":"Live/production (true) or test/sandbox (false)","type":["boolean","null"]},"accountName":{"type":["string","null"]},"status":{"anyOf":[{"type":"string","enum":["ok","syncing","error"]},{"type":"null"}]},"lastSyncAt":{"type":["string","null"]},"lastError":{"description":"A safe message for people; never the provider's text or the key","type":["string","null"]},"notice":{"description":"An advisory about a connection that syncs but not completely (e.g. a Stripe key without Read access to Invoices: no renewals); never the provider's text","type":["string","null"]},"backfillDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"label":{"type":"string","description":"Shown to people: \"Stripe\", \"Dodo Payments\", \"Polar\""}},"required":["provider","connected","keyHint","livemode","accountName","status","lastSyncAt","lastError","notice","backfillDays","label"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/revenue/subscriptions/breakdown":{"get":{"operationId":"getSubscriptionsBreakdown","summary":"Get an MRR breakdown","tags":["Revenue"],"description":"MRR and subscribers at the window's end (or now) per value of a session dimension (`dim`) of the visit each subscription is credited to (by the site's credit model, or `model`), in one currency (`currency`, else the site's), a page at a time (`limit` and `offset`; `meta.totalCount`).\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"in":"query","name":"currency","required":false,"description":"ISO 4217 code: only amounts in this currency count, so every amount of the response is in it (no conversion); default: the site's currency"},{"schema":{"type":"string"},"in":"query","name":"dim","required":true,"description":"A session dimension of the registry: that of the visit the subscription is credited to (`model=`)"},{"schema":{"type":"string","enum":["last_non_direct","first_visit","last_visit"]},"in":"query","name":"model","required":false,"description":"Which visit of the paying person a payment is credited to: last_non_direct, first_visit (both within the site's lookback window) or last_visit; default: the site's model"},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"region":{"type":"string"},"region_name":{"type":"string"},"country":{"type":"string"},"mrr":{"type":"number"},"subscribers":{"type":"number"},"percentage":{"type":"number","description":"row MRR ÷ MRR at `as_of` (attributed or not) × 100"}},"required":["value","mrr","subscribers","percentage"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/revenue/subscriptions/summary":{"get":{"operationId":"getSubscriptionsSummary","summary":"Get the subscriptions summary","tags":["Revenue"],"description":"MRR and its movements, subscribers, churn, ARPU, lifetime value and trials of the providers that record subscriptions, in one currency (`currency`, else the site's), and the currencies seen; with a comparison window, the same figures for it under `previous`.\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"in":"query","name":"currency","required":false,"description":"ISO 4217 code: only amounts in this currency count, so every amount of the response is in it (no conversion); default: the site's currency"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"as_of":{"type":"string","description":"The instant MRR and subscribers are counted at: the window's end, capped at now"},"mrr":{"type":"number","description":"Monthly recurring revenue at `as_of`: active and past_due subscriptions, minor unit"},"mrr_start":{"type":"number","description":"MRR just before the window (0 for all time)"},"new_mrr":{"type":"number","description":"MRR of subscriptions paying for the first time"},"expansion_mrr":{"type":"number","description":"MRR gained by paying subscriptions (upgrades)"},"contraction_mrr":{"type":"number","description":"MRR lost by paying subscriptions still paying (downgrades)"},"churned_mrr":{"type":"number","description":"MRR of subscriptions that stopped (canceled, unpaid, paused)"},"reactivation_mrr":{"type":"number","description":"MRR of subscriptions paying again after 0"},"net_new_mrr":{"type":"number","description":"new + expansion + reactivation − contraction − churned"},"active_subscribers":{"type":"number","description":"Customers with positive MRR at `as_of`"},"active_subscribers_start":{"type":"number"},"new_subscribers":{"type":"number","description":"Customers paying for the first time in the window"},"reactivated_subscribers":{"type":"number"},"churned_subscribers":{"type":"number","description":"Customers whose MRR reached 0 in the window"},"subscriber_churn_rate":{"type":"number","description":"Percent: churned in the 30 days to `as_of` ÷ (active 30 days before + new in those 30 days)"},"arpu":{"type":"number","description":"MRR ÷ active subscribers, minor unit"},"ltv":{"description":"ARPU ÷ subscriber churn rate; null while the churn rate is 0","type":["number","null"]},"trials":{"type":"object","properties":{"active":{"type":"number","description":"Subscriptions trialing at `as_of`"},"new":{"type":"number","description":"Trials started in the window"}},"required":["active","new"],"additionalProperties":false},"currency":{"type":"string"},"currencies":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"subscriptions":{"type":"number"}},"required":["currency","subscriptions"],"additionalProperties":false}},"previous":{"type":"object","properties":{"as_of":{"type":"string","description":"The instant MRR and subscribers are counted at: the window's end, capped at now"},"mrr":{"type":"number","description":"Monthly recurring revenue at `as_of`: active and past_due subscriptions, minor unit"},"mrr_start":{"type":"number","description":"MRR just before the window (0 for all time)"},"new_mrr":{"type":"number","description":"MRR of subscriptions paying for the first time"},"expansion_mrr":{"type":"number","description":"MRR gained by paying subscriptions (upgrades)"},"contraction_mrr":{"type":"number","description":"MRR lost by paying subscriptions still paying (downgrades)"},"churned_mrr":{"type":"number","description":"MRR of subscriptions that stopped (canceled, unpaid, paused)"},"reactivation_mrr":{"type":"number","description":"MRR of subscriptions paying again after 0"},"net_new_mrr":{"type":"number","description":"new + expansion + reactivation − contraction − churned"},"active_subscribers":{"type":"number","description":"Customers with positive MRR at `as_of`"},"active_subscribers_start":{"type":"number"},"new_subscribers":{"type":"number","description":"Customers paying for the first time in the window"},"reactivated_subscribers":{"type":"number"},"churned_subscribers":{"type":"number","description":"Customers whose MRR reached 0 in the window"},"subscriber_churn_rate":{"type":"number","description":"Percent: churned in the 30 days to `as_of` ÷ (active 30 days before + new in those 30 days)"},"arpu":{"type":"number","description":"MRR ÷ active subscribers, minor unit"},"ltv":{"description":"ARPU ÷ subscriber churn rate; null while the churn rate is 0","type":["number","null"]},"trials":{"type":"object","properties":{"active":{"type":"number","description":"Subscriptions trialing at `as_of`"},"new":{"type":"number","description":"Trials started in the window"}},"required":["active","new"],"additionalProperties":false}},"required":["as_of","mrr","mrr_start","new_mrr","expansion_mrr","contraction_mrr","churned_mrr","reactivation_mrr","net_new_mrr","active_subscribers","active_subscribers_start","new_subscribers","reactivated_subscribers","churned_subscribers","subscriber_churn_rate","arpu","ltv","trials"],"additionalProperties":false}},"required":["as_of","mrr","mrr_start","new_mrr","expansion_mrr","contraction_mrr","churned_mrr","reactivation_mrr","net_new_mrr","active_subscribers","active_subscribers_start","new_subscribers","reactivated_subscribers","churned_subscribers","subscriber_churn_rate","arpu","ltv","trials","currency","currencies"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/revenue/subscriptions/timeseries":{"get":{"operationId":"getSubscriptionsTimeseries","summary":"Get the subscriptions time series","tags":["Revenue"],"description":"MRR, active subscribers and the MRR movements per time bucket, in one currency (`currency`, else the site's).\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"in":"query","name":"currency","required":false,"description":"ISO 4217 code: only amounts in this currency count, so every amount of the response is in it (no conversion); default: the site's currency"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"mrr":{"type":"number","description":"MRR at the bucket's end (capped at now)"},"active_subscribers":{"type":"number"},"new_mrr":{"type":"number","description":"MRR of subscriptions paying for the first time"},"expansion_mrr":{"type":"number","description":"MRR gained by paying subscriptions (upgrades)"},"contraction_mrr":{"type":"number","description":"MRR lost by paying subscriptions still paying (downgrades)"},"churned_mrr":{"type":"number","description":"MRR of subscriptions that stopped (canceled, unpaid, paused)"},"reactivation_mrr":{"type":"number","description":"MRR of subscriptions paying again after 0"},"net_new_mrr":{"type":"number","description":"new + expansion + reactivation − contraction − churned"}},"required":["t","mrr","active_subscribers","new_mrr","expansion_mrr","contraction_mrr","churned_mrr","reactivation_mrr","net_new_mrr"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/revenue/summary":{"get":{"operationId":"getRevenueSummary","summary":"Get the revenue summary","tags":["Revenue"],"description":"Revenue, refunds, payments, average order value, paying visitors and conversion rate of the payments in one currency (`currency`, else the site's), credited to visits by the site's credit model (or `model`), and the currencies seen in the window; with a comparison window, the same figures for it under `previous`.\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"in":"query","name":"currency","required":false,"description":"ISO 4217 code: only amounts in this currency count, so every amount of the response is in it (no conversion); default: the site's currency"},{"schema":{"type":"string","enum":["last_non_direct","first_visit","last_visit"]},"in":"query","name":"model","required":false,"description":"Which visit of the paying person a payment is credited to: last_non_direct, first_visit (both within the site's lookback window) or last_visit; default: the site's model"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revenue":{"type":"number","description":"gross − refunded, in the currency's minor unit"},"gross":{"type":"number"},"refunded":{"type":"number"},"payments":{"type":"number"},"refunds":{"type":"number","description":"payments with a refunded amount"},"aov":{"type":"number","description":"round(gross / payments), minor unit"},"paying_visitors":{"type":"number"},"visitors":{"type":"number"},"conversion_rate":{"type":"number","description":"paying_visitors ÷ visitors × 100"},"revenue_per_visitor":{"type":"number","description":"revenue ÷ visitors, in the currency's minor unit, not rounded (0 without visitors)"},"unattributed_payments":{"type":"number"},"currency":{"type":"string"},"currencies":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"payments":{"type":"number"}},"required":["currency","payments"],"additionalProperties":false}},"credit_model":{"type":"string","enum":["last_non_direct","first_visit","last_visit"],"description":"The credit model applied (model= or the site's)"},"credit_window_days":{"type":"number","description":"The site's lookback window of last_non_direct and first_visit"},"previous":{"type":"object","properties":{"revenue":{"type":"number","description":"gross − refunded, in the currency's minor unit"},"gross":{"type":"number"},"refunded":{"type":"number"},"payments":{"type":"number"},"refunds":{"type":"number","description":"payments with a refunded amount"},"aov":{"type":"number","description":"round(gross / payments), minor unit"},"paying_visitors":{"type":"number"},"visitors":{"type":"number"},"conversion_rate":{"type":"number","description":"paying_visitors ÷ visitors × 100"},"revenue_per_visitor":{"type":"number","description":"revenue ÷ visitors, in the currency's minor unit, not rounded (0 without visitors)"},"unattributed_payments":{"type":"number"}},"required":["revenue","gross","refunded","payments","refunds","aov","paying_visitors","visitors","conversion_rate","revenue_per_visitor","unattributed_payments"],"additionalProperties":false}},"required":["revenue","gross","refunded","payments","refunds","aov","paying_visitors","visitors","conversion_rate","revenue_per_visitor","unattributed_payments","currency","currencies","credit_model","credit_window_days"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/revenue/timeseries":{"get":{"operationId":"getRevenueTimeseries","summary":"Get the revenue time series","tags":["Revenue"],"description":"Revenue and payments per time bucket in one currency (`currency`, else the site's); with a comparison window, each point carries the comparison's point at the same index under `previous` (null where that series is shorter).\n\nRequires `revenue:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"in":"query","name":"currency","required":false,"description":"ISO 4217 code: only amounts in this currency count, so every amount of the response is in it (no conversion); default: the site's currency"},{"schema":{"type":"string","enum":["last_non_direct","first_visit","last_visit"]},"in":"query","name":"model","required":false,"description":"Which visit of the paying person a payment is credited to: last_non_direct, first_visit (both within the site's lookback window) or last_visit; default: the site's model"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["revenue:read"]},{"apiKeyBearer":["revenue:read"]},{"session":["revenue:read"]}],"x-pilotfox-access":{"kind":"site","permission":"revenue:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"revenue":{"type":"number"},"gross":{"type":"number"},"refunded":{"type":"number"},"payments":{"type":"number"},"previous":{"anyOf":[{"type":"object","properties":{"t":{"type":"string"},"revenue":{"type":"number"},"gross":{"type":"number"},"refunded":{"type":"number"},"payments":{"type":"number"}},"required":["t","revenue","gross","refunded","payments"],"additionalProperties":false},{"type":"null"}]}},"required":["t","revenue","gross","refunded","payments"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console":{"get":{"operationId":"getSiteSearchConsole","summary":"Get the site's Search Console status","tags":["Search Console"],"description":"Whether the site is linked to a Search Console property, its sync progress and errors, and what the caller may do (`canManage`, `canLink`).\n\nRequires `searchConsole:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["searchConsole:read"]},{"apiKeyBearer":["searchConsole:read"]},{"session":["searchConsole:read"]}],"x-pilotfox-access":{"kind":"site","permission":"searchConsole:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"configured":{"type":"boolean"},"canManage":{"type":"boolean","description":"site:update: sync now, unlink"},"canLink":{"type":"boolean","description":"site:update with org-wide access: list the org's Google connections and properties, link one"},"redirectUri":{"type":"string"},"orgConnections":{"type":"number","description":"active Google connections of the site's organization"},"link":{"anyOf":[{"type":"object","properties":{"property":{"type":"string"},"status":{"type":"string","enum":["backfilling","ready","error","unlinked"]},"connection":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"googleEmail":{"type":"string"},"status":{"type":"string","enum":["active","needs_reconnect"]}},"required":["id","googleEmail","status"],"additionalProperties":false},{"type":"null"}]},"backfill":{"type":"object","properties":{"days":{"type":"number"},"total":{"type":"number"},"done":{"type":"number"},"complete":{"type":"boolean"}},"required":["days","total","done","complete"],"additionalProperties":false},"lastSyncAt":{"type":["string","null"]},"lastSuccessAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"lastErrorAt":{"type":["string","null"]},"nextSyncAfter":{"type":["string","null"]},"linkedAt":{"type":"string"},"data":{"type":"object","properties":{"earliest":{"type":["string","null"]},"latest":{"type":["string","null"]},"lastComplete":{"description":"newest day Google has finished counting (Pacific Time)","type":["string","null"]}},"required":["earliest","latest","lastComplete"],"additionalProperties":false}},"required":["property","status","connection","backfill","lastSyncAt","lastSuccessAt","lastError","lastErrorAt","nextSyncAfter","linkedAt","data"],"additionalProperties":false},{"type":"null"}]}},"required":["configured","canManage","canLink","redirectUri","orgConnections","link"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"put":{"operationId":"linkSearchConsoleProperty","summary":"Link a Search Console property","tags":["Search Console"],"description":"Links the site to a property of an organization connection and queues the import of its last `backfillDays` days (90 by default, 486 at most). Linking the same property again keeps its data and only widens the history; another property replaces it. Only for callers with access to every site of the organization (403); 400 for a property the Google account cannot read, 409 when the connection needs reconnecting.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"property":{"type":"string","minLength":1,"maxLength":2048},"backfillDays":{"default":90,"type":"integer","minimum":1,"maximum":486}},"required":["connectionId","property"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":["queued"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"unlinkSearchConsole","summary":"Unlink Search Console","tags":["Search Console"],"description":"Stops syncing the property; its imported data stays readable unless `deleteData=true` deletes it. 404 when the site has no link.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"default":"false","type":"string","enum":["true","false"]},"in":"query","name":"deleteData","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/connections":{"get":{"operationId":"listSiteSearchConsoleConnections","summary":"List connections to link","tags":["Search Console"],"description":"The organization's Google connections a property can be linked from. Only for callers with access to every site of the organization.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"googleEmail":{"type":"string"},"status":{"type":"string","enum":["active","needs_reconnect"]}},"required":["id","googleEmail","status"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/countries":{"get":{"operationId":"listSearchConsoleCountries","summary":"List search countries","tags":["Search Console"],"description":"Clicks, impressions, CTR and average position per country in the window, searchable (`search`) and sortable (`sort`, `order`), a page at a time (`limit` and `offset`; `meta.totalCount`); with a comparison window, each row's previous figures too.\n\nRequires `searchConsole:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false},{"schema":{"default":"clicks","type":"string","enum":["clicks","impressions","ctr","position","clicks_change","key"]},"in":"query","name":"sort","required":false},{"schema":{"default":"desc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["searchConsole:read"]},{"apiKeyBearer":["searchConsole:read"]},{"session":["searchConsole:read"]}],"x-pilotfox-access":{"kind":"site","permission":"searchConsole:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"country":{"type":"string","description":"ISO 3166-1 alpha-2, empty when Google's code is not one"},"country3":{"type":"string","description":"Google's ISO 3166-1 alpha-3 code, lower case"},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]}},"required":["clicks","impressions","ctr","position","country","country3","previous"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"tz":{"type":"string","enum":["America/Los_Angeles"]},"bucket":{"type":"string","enum":["day","week","month"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"number"},"previousAvailable":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/devices":{"get":{"operationId":"listSearchConsoleDevices","summary":"List search devices","tags":["Search Console"],"description":"Clicks, impressions, CTR and average position per device type in the window, searchable (`search`) and sortable (`sort`, `order`), a page at a time (`limit` and `offset`; `meta.totalCount`); with a comparison window, each row's previous figures too.\n\nRequires `searchConsole:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false},{"schema":{"default":"clicks","type":"string","enum":["clicks","impressions","ctr","position","clicks_change","key"]},"in":"query","name":"sort","required":false},{"schema":{"default":"desc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["searchConsole:read"]},{"apiKeyBearer":["searchConsole:read"]},{"session":["searchConsole:read"]}],"x-pilotfox-access":{"kind":"site","permission":"searchConsole:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"device":{"type":"string"},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]}},"required":["clicks","impressions","ctr","position","device","previous"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"tz":{"type":"string","enum":["America/Los_Angeles"]},"bucket":{"type":"string","enum":["day","week","month"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"number"},"previousAvailable":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/insights":{"get":{"operationId":"getSearchConsoleInsights","summary":"Get search insights","tags":["Search Console"],"description":"Queries of one kind (`type`) against the comparison window (else the same number of days just before the window): `winners` and `losers` (clicks gained or lost), `new` and `lost` (impressions in one window only), `striking` (average position 8 to 20, 10 impressions or more: a small gain reaches page one) or `ctr` (page-one queries with 50 impressions or more and a CTR below half the site's own for their position).\n\nRequires `searchConsole:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","enum":["winners","losers","new","lost","striking","ctr"]},"in":"query","name":"type","required":true},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["searchConsole:read"]},{"apiKeyBearer":["searchConsole:read"]},{"session":["searchConsole:read"]}],"x-pilotfox-access":{"kind":"site","permission":"searchConsole:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"query":{"type":"string"},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]},"band_ctr":{"type":"number"},"missed_clicks":{"type":"number"}},"required":["clicks","impressions","ctr","position","query","previous"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"tz":{"type":"string","enum":["America/Los_Angeles"]},"bucket":{"type":"string","enum":["day","week","month"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"number"},"previousAvailable":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/overview":{"get":{"operationId":"getSearchConsoleOverview","summary":"Get the search overview","tags":["Search Console"],"description":"Clicks, impressions, CTR and average position in the window and per time bucket; with a comparison window, its totals under `previous` (null when it has no synced data). Days are Google's, in Pacific Time; 404 when the site has no link.\n\nRequires `searchConsole:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["searchConsole:read"]},{"apiKeyBearer":["searchConsole:read"]},{"session":["searchConsole:read"]}],"x-pilotfox-access":{"kind":"site","permission":"searchConsole:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totals":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]},"series":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"date":{"type":"string","description":"bucket start, YYYY-MM-DD (Pacific Time)"},"provisional":{"type":"boolean","description":"Google is still counting a day of this bucket"},"synced":{"type":"boolean"}},"required":["clicks","impressions","ctr","position","date","provisional","synced"],"additionalProperties":false}}},"required":["totals","series"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"tz":{"type":"string","enum":["America/Los_Angeles"]},"bucket":{"type":"string","enum":["day","week","month"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"number"},"previousAvailable":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/pages":{"get":{"operationId":"listSearchConsolePages","summary":"List search pages","tags":["Search Console"],"description":"Clicks, impressions, CTR and average position per page in the window, searchable (`search`) and sortable (`sort`, `order`), a page at a time (`limit` and `offset`; `meta.totalCount`); with a comparison window, each row's previous figures too.\n\nRequires `searchConsole:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false},{"schema":{"default":"clicks","type":"string","enum":["clicks","impressions","ctr","position","clicks_change","key"]},"in":"query","name":"sort","required":false},{"schema":{"default":"desc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["searchConsole:read"]},{"apiKeyBearer":["searchConsole:read"]},{"session":["searchConsole:read"]}],"x-pilotfox-access":{"kind":"site","permission":"searchConsole:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"page":{"type":"string"},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]}},"required":["clicks","impressions","ctr","position","page","previous"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"tz":{"type":"string","enum":["America/Los_Angeles"]},"bucket":{"type":"string","enum":["day","week","month"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"number"},"previousAvailable":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/pages/detail":{"get":{"operationId":"getSearchConsolePage","summary":"Get a search page's detail","tags":["Search Console"],"description":"One page's totals and series in the window, and the top 100 queries it showed for, by clicks.\n\nRequires `searchConsole:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","minLength":1,"maxLength":4096},"in":"query","name":"page","required":true},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["searchConsole:read"]},{"apiKeyBearer":["searchConsole:read"]},{"session":["searchConsole:read"]}],"x-pilotfox-access":{"kind":"site","permission":"searchConsole:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totals":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]},"series":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"date":{"type":"string","description":"bucket start, YYYY-MM-DD (Pacific Time)"},"provisional":{"type":"boolean","description":"Google is still counting a day of this bucket"},"synced":{"type":"boolean"}},"required":["clicks","impressions","ctr","position","date","provisional","synced"],"additionalProperties":false}},"queries":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"query":{"type":"string"},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]}},"required":["clicks","impressions","ctr","position","query","previous"],"additionalProperties":false}}},"required":["totals","series","queries"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"tz":{"type":"string","enum":["America/Los_Angeles"]},"bucket":{"type":"string","enum":["day","week","month"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"number"},"previousAvailable":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/properties":{"get":{"operationId":"listSearchConsoleProperties","summary":"List Search Console properties","tags":["Search Console"],"description":"The properties a connection's Google account can see, with its permission on each. Only for callers with access to every site of the organization.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"connectionId","required":true},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"properties":{"type":"array","items":{"type":"object","properties":{"siteUrl":{"type":"string"},"permission":{"type":"string","enum":["owner","full","restricted","unverified","unknown"]},"kind":{"type":"string","enum":["domain","url_prefix"]},"usable":{"type":"boolean","description":"unverified users cannot read a property's data"}},"required":["siteUrl","permission","kind","usable"],"additionalProperties":false}},"suggested":{"type":["string","null"]}},"required":["properties","suggested"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/queries":{"get":{"operationId":"listSearchConsoleQueries","summary":"List search queries","tags":["Search Console"],"description":"Clicks, impressions, CTR and average position per search query in the window, searchable (`search`) and sortable (`sort`, `order`), a page at a time (`limit` and `offset`; `meta.totalCount`); with a comparison window, each row's previous figures too.\n\nRequires `searchConsole:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search","required":false},{"schema":{"default":"clicks","type":"string","enum":["clicks","impressions","ctr","position","clicks_change","key"]},"in":"query","name":"sort","required":false},{"schema":{"default":"desc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["searchConsole:read"]},{"apiKeyBearer":["searchConsole:read"]},{"session":["searchConsole:read"]}],"x-pilotfox-access":{"kind":"site","permission":"searchConsole:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"query":{"type":"string"},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]}},"required":["clicks","impressions","ctr","position","query","previous"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"tz":{"type":"string","enum":["America/Los_Angeles"]},"bucket":{"type":"string","enum":["day","week","month"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"number"},"previousAvailable":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/queries/detail":{"get":{"operationId":"getSearchConsoleQuery","summary":"Get a search query's detail","tags":["Search Console"],"description":"One query's totals and series in the window, and its top 100 pages, countries and devices by clicks.\n\nRequires `searchConsole:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","minLength":1,"maxLength":2048},"in":"query","name":"query","required":true},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["searchConsole:read"]},{"apiKeyBearer":["searchConsole:read"]},{"session":["searchConsole:read"]}],"x-pilotfox-access":{"kind":"site","permission":"searchConsole:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totals":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]},"series":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"date":{"type":"string","description":"bucket start, YYYY-MM-DD (Pacific Time)"},"provisional":{"type":"boolean","description":"Google is still counting a day of this bucket"},"synced":{"type":"boolean"}},"required":["clicks","impressions","ctr","position","date","provisional","synced"],"additionalProperties":false}},"pages":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"page":{"type":"string"},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]}},"required":["clicks","impressions","ctr","position","page","previous"],"additionalProperties":false}},"countries":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"country":{"type":"string","description":"ISO 3166-1 alpha-2, empty when Google's code is not one"},"country3":{"type":"string","description":"Google's ISO 3166-1 alpha-3 code, lower case"},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]}},"required":["clicks","impressions","ctr","position","country","country3","previous"],"additionalProperties":false}},"devices":{"type":"array","items":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]},"device":{"type":"string"},"previous":{"anyOf":[{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number","description":"clicks ÷ impressions, 0..1"},"position":{"description":"impression-weighted average position; null without impressions","type":["number","null"]}},"required":["clicks","impressions","ctr","position"],"additionalProperties":false},{"type":"null"}]}},"required":["clicks","impressions","ctr","position","device","previous"],"additionalProperties":false}}},"required":["totals","series","pages","countries","devices"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"tz":{"type":"string","enum":["America/Los_Angeles"]},"bucket":{"type":"string","enum":["day","week","month"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"number"},"previousAvailable":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/search-console/sync":{"post":{"operationId":"syncSearchConsole","summary":"Sync Search Console now","tags":["Search Console"],"description":"Queues a sync of the linked property now rather than at the next scheduled run. Send `{}` as the body: a request without one is 400. 404 when the site has no link, 503 when Google OAuth is not configured.\n\nRequires `site:update` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["site:update"]},{"apiKeyBearer":["site:update"]},{"session":["site:update"]}],"x-pilotfox-access":{"kind":"site","permission":"site:update"},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":["queued"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/segments":{"get":{"operationId":"listSegments","summary":"List segments","tags":["Segments"],"description":"The segments the caller sees on this site: the site's own and the organization-wide ones, public or their own private ones.\n\nRequires `segments:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["segments:read"]},{"apiKeyBearer":["segments:read"]},{"session":["segments:read"]}],"x-pilotfox-access":{"kind":"site","permission":"segments:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"filters":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"dim":{"type":"string","minLength":1,"maxLength":80},"op":{"type":"string","enum":["eq","neq","contains","not_contains","starts_with","ends_with","regex","not_regex","is_set","is_not_set","gt","gte","lt","lte"]},"values":{"default":[],"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]}}},"required":["dim","op","values"],"additionalProperties":false}},"isPublic":{"type":"boolean"},"scope":{"type":"string","enum":["site","org"]},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","description","filters","isPublic","scope","createdBy","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"operationId":"createSegment","summary":"Create a segment","tags":["Segments"],"description":"A named set of filters for this site, or for every site of the organization (`scope: org`: for unrestricted members whose organization role grants `segments:write`, and API keys not limited to some sites), private to its creator or public to the organization. API keys create public segments only.\n\nRequires `segments:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"filters":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"dim":{"type":"string","minLength":1,"maxLength":80},"op":{"type":"string","enum":["eq","neq","contains","not_contains","starts_with","ends_with","regex","not_regex","is_set","is_not_set","gt","gte","lt","lte"]},"values":{"default":[],"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]}}},"required":["dim","op"]}},"isPublic":{"default":false,"type":"boolean"},"scope":{"default":"site","type":"string","enum":["site","org"]}},"required":["name","filters"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["segments:write"]},{"apiKeyBearer":["segments:write"]},{"session":["segments:write"]}],"x-pilotfox-access":{"kind":"site","permission":"segments:write"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"filters":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"dim":{"type":"string","minLength":1,"maxLength":80},"op":{"type":"string","enum":["eq","neq","contains","not_contains","starts_with","ends_with","regex","not_regex","is_set","is_not_set","gt","gte","lt","lte"]},"values":{"default":[],"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]}}},"required":["dim","op","values"],"additionalProperties":false}},"isPublic":{"type":"boolean"},"scope":{"type":"string","enum":["site","org"]},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","description","filters","isPublic","scope","createdBy","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/segments/{id}":{"get":{"operationId":"getSegment","summary":"Get a segment","tags":["Segments"],"description":"Requires `segments:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["segments:read"]},{"apiKeyBearer":["segments:read"]},{"session":["segments:read"]}],"x-pilotfox-access":{"kind":"site","permission":"segments:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"filters":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"dim":{"type":"string","minLength":1,"maxLength":80},"op":{"type":"string","enum":["eq","neq","contains","not_contains","starts_with","ends_with","regex","not_regex","is_set","is_not_set","gt","gte","lt","lte"]},"values":{"default":[],"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]}}},"required":["dim","op","values"],"additionalProperties":false}},"isPublic":{"type":"boolean"},"scope":{"type":"string","enum":["site","org"]},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","description","filters","isPublic","scope","createdBy","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteSegment","summary":"Delete a segment","tags":["Segments"],"description":"Deleting an organization-wide segment needs the reach creating one takes (403 otherwise).\n\nRequires `segments:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["segments:write"]},{"apiKeyBearer":["segments:write"]},{"session":["segments:write"]}],"x-pilotfox-access":{"kind":"site","permission":"segments:write"},"responses":{"204":{"description":"No Content"}}},"patch":{"operationId":"updateSegment","summary":"Update a segment","tags":["Segments"],"description":"Changes the fields sent. Editing an organization-wide segment, or moving one to `scope: org`, needs the reach creating one takes (403 otherwise); a segment whose creator was deleted must stay public (400).\n\nRequires `segments:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"filters":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"dim":{"type":"string","minLength":1,"maxLength":80},"op":{"type":"string","enum":["eq","neq","contains","not_contains","starts_with","ends_with","regex","not_regex","is_set","is_not_set","gt","gte","lt","lte"]},"values":{"default":[],"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]}}},"required":["dim","op"]}},"isPublic":{"type":"boolean"},"scope":{"type":"string","enum":["site","org"]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["segments:write"]},{"apiKeyBearer":["segments:write"]},{"session":["segments:write"]}],"x-pilotfox-access":{"kind":"site","permission":"segments:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"filters":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"dim":{"type":"string","minLength":1,"maxLength":80},"op":{"type":"string","enum":["eq","neq","contains","not_contains","starts_with","ends_with","regex","not_regex","is_set","is_not_set","gt","gte","lt","lte"]},"values":{"default":[],"maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]}}},"required":["dim","op","values"],"additionalProperties":false}},"isPublic":{"type":"boolean"},"scope":{"type":"string","enum":["site","org"]},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","description","filters","isPublic","scope","createdBy","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/sessions":{"get":{"operationId":"listSessions","summary":"List sessions","tags":["Sessions"],"description":"The window's sessions, highest `sort` value first (`started` by default: newest first), narrowed by `view` and `search`, a page at a time (`meta.nextCursor`). Share links get no coordinates (`lat` and `lon` null).\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `sessions:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":"started","type":"string","enum":["started","ended","duration","pageviews","events"]},"in":"query","name":"sort","required":false},{"schema":{"default":"all","type":"string","enum":["all","identified","with_replay","converted","bounced","with_errors"]},"in":"query","name":"view","required":false},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"search","required":false,"description":"Case-insensitive substring of the session's user id, entry page, exit page or referrer domain, or of the `name` / `email` trait of the user's profile (traits only with users:read). Kept out of the query log."},{"schema":{"type":"string","maxLength":2200},"in":"query","name":"cursor","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]},{"shareToken":["sessions:read"]},{"shareTokenQuery":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"session_id":{"type":"string"},"visitor_id":{"type":"string"},"user_id":{"type":"string"},"identified":{"type":"boolean"},"started_at":{"type":"string"},"ended_at":{"type":"string"},"duration":{"type":"number","description":"Seconds, millisecond precision"},"pageviews":{"type":"number"},"events":{"type":"number"},"errors":{"type":"number"},"entry_page":{"type":"string"},"exit_page":{"type":"string"},"referrer_domain":{"type":"string"},"channel":{"type":"string"},"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"utm_term":{"type":"string"},"utm_content":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"region_name":{"type":"string"},"city":{"type":"string"},"lat":{"type":["number","null"]},"lon":{"type":["number","null"]},"browser":{"type":"string"},"os":{"type":"string"},"device_type":{"type":"string"},"screen":{"type":"string"},"language":{"type":"string"},"has_replay":{"type":"boolean"},"goal_ids":{"type":"array","items":{"type":"string"}}},"required":["session_id","visitor_id","user_id","identified","started_at","ended_at","duration","pageviews","events","errors","entry_page","exit_page","referrer_domain","channel","utm_source","utm_medium","utm_campaign","utm_term","utm_content","country","region","region_name","city","lat","lon","browser","os","device_type","screen","language","has_replay","goal_ids"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/sessions/summary":{"get":{"operationId":"getSessionsSummary","summary":"Get the sessions summary","tags":["Sessions"],"description":"Sessions, visitors, pageviews, events, errors, average duration and bounce rate in the window, the count of each list view, and sessions per time bucket.\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `sessions:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]},{"shareToken":["sessions:read"]},{"shareTokenQuery":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totals":{"type":"object","properties":{"sessions":{"type":"number"},"visitors":{"type":"number"},"pageviews":{"type":"number"},"events":{"type":"number"},"errors":{"type":"number"},"avg_session_duration":{"type":"number","description":"Seconds, over sessions with a pageview"},"bounce_rate":{"type":"number","description":"Percent (0-100) of sessions with a pageview"}},"required":["sessions","visitors","pageviews","events","errors","avg_session_duration","bounce_rate"],"additionalProperties":false},"views":{"type":"object","propertyNames":{"type":"string","enum":["all","identified","with_replay","converted","bounced","with_errors"]},"additionalProperties":{"type":"number"},"required":["all","identified","with_replay","converted","bounced","with_errors"]},"series":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"sessions":{"type":"number"}},"required":["t","sessions"],"additionalProperties":false}}},"required":["totals","views","series"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/sessions/{sessionId}":{"get":{"operationId":"getSession","summary":"Get a session","tags":["Sessions"],"description":"One session and its events in order, a page at a time (`meta.nextCursor`). `at`, any instant of the session, narrows the lookup to 24 hours either side of it. 404 when no such session is found. Share links get no coordinates (`lat` and `lon` null).\n\nRequires `sessions:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `sessions:read` scope.","parameters":[{"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"in":"query","name":"at","required":false,"description":"Any instant of the session: bounds the lookup to at ± 24 hours (all time up to now without it)"},{"schema":{"type":"string","maxLength":2200},"in":"query","name":"cursor","required":false,"description":"`meta.nextCursor` of the previous page"},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":500},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"sessionId","required":true}],"security":[{"apiKey":["sessions:read"]},{"apiKeyBearer":["sessions:read"]},{"session":["sessions:read"]},{"shareToken":["sessions:read"]},{"shareTokenQuery":["sessions:read"]}],"x-pilotfox-access":{"kind":"site","permission":"sessions:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"session":{"type":"object","properties":{"session_id":{"type":"string"},"visitor_id":{"type":"string"},"user_id":{"type":"string"},"identified":{"type":"boolean"},"started_at":{"type":"string"},"ended_at":{"type":"string"},"duration":{"type":"number","description":"Seconds, millisecond precision"},"pageviews":{"type":"number"},"events":{"type":"number"},"errors":{"type":"number"},"entry_page":{"type":"string"},"exit_page":{"type":"string"},"referrer_domain":{"type":"string"},"channel":{"type":"string"},"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"utm_term":{"type":"string"},"utm_content":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"region_name":{"type":"string"},"city":{"type":"string"},"lat":{"type":["number","null"]},"lon":{"type":["number","null"]},"browser":{"type":"string"},"os":{"type":"string"},"device_type":{"type":"string"},"screen":{"type":"string"},"language":{"type":"string"},"has_replay":{"type":"boolean"},"goal_ids":{"type":"array","items":{"type":"string"}}},"required":["session_id","visitor_id","user_id","identified","started_at","ended_at","duration","pageviews","events","errors","entry_page","exit_page","referrer_domain","channel","utm_source","utm_medium","utm_campaign","utm_term","utm_content","country","region","region_name","city","lat","lon","browser","os","device_type","screen","language","has_replay","goal_ids"],"additionalProperties":false},"events":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"string"},"type":{"type":"string"},"event_name":{"type":"string"},"hostname":{"type":"string"},"pathname":{"type":"string"},"querystring":{"type":"string"},"page_title":{"type":"string"},"referrer":{"type":"string"},"identified_user_id":{"type":"string","description":"The uid the event carried; '' when anonymous"},"props":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean"]}},"error_fingerprint":{"type":"string"},"lcp":{"description":"Milliseconds; vital rows only","type":["number","null"]},"cls":{"type":["number","null"]},"inp":{"description":"Milliseconds; vital rows only","type":["number","null"]},"fcp":{"description":"Milliseconds; vital rows only","type":["number","null"]},"ttfb":{"description":"Milliseconds; vital rows only","type":["number","null"]}},"required":["ts","type","event_name","hostname","pathname","querystring","page_title","referrer","identified_user_id","props","error_fingerprint","lcp","cls","inp","fcp","ttfb"],"additionalProperties":false}}},"required":["session","events"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/share-links":{"get":{"operationId":"listShareLinks","summary":"List share links","tags":["Share links"],"description":"The site's share links that are not revoked (expired ones included), newest first, with their scopes, expiry and last use; never the tokens: `tokenPrefix` is their start.\n\nRequires `shareLink:read` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["shareLink:read"]},{"apiKeyBearer":["shareLink:read"]},{"session":["shareLink:read"]}],"x-pilotfox-access":{"kind":"site","permission":"shareLink:read"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"tokenPrefix":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","tokenPrefix","scopes","expiresAt","lastUsedAt","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}},"post":{"operationId":"createShareLink","summary":"Create a share link","tags":["Share links"],"description":"A read-only link to the site's dashboard with `scopes` (`analytics:read`, `sessions:read`, `users:read`, `replay:read`; `analytics:read` by default), each one the caller holds on the site (403 otherwise), and an optional `expiresAt` in the future. This answer is the only one that carries the token and the link's URL (`<PUBLIC_URL>/share/<token>`). Not with an MCP OAuth token (403).\n\nRequires `shareLink:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"scopes":{"default":["analytics:read"],"minItems":1,"type":"array","items":{"type":"string","enum":["analytics:read","sessions:read","users:read","replay:read"]}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["shareLink:write"]},{"apiKeyBearer":["shareLink:write"]},{"session":["shareLink:write"]}],"x-pilotfox-access":{"kind":"site","permission":"shareLink:write"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string"},"url":{"type":"string"}},"required":["id","token","url"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/share-links/{id}":{"delete":{"operationId":"revokeShareLink","summary":"Revoke a share link","tags":["Share links"],"description":"The link's token is refused from the next request on.\n\nRequires `shareLink:write` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":["shareLink:write"]},{"apiKeyBearer":["shareLink:write"]},{"session":["shareLink:write"]}],"x-pilotfox-access":{"kind":"site","permission":"shareLink:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/snippet":{"get":{"operationId":"getSiteSnippet","summary":"Get the tracking snippet","tags":["Sites"],"description":"The `<script>` tag that loads the tracker for this site, to put on every page.\n\nRequires `site:read` on the site (an API key, or a signed-in member's role). Share links: 401.","security":[{"apiKey":["site:read"]},{"apiKeyBearer":["site:read"]},{"session":["site:read"]}],"x-pilotfox-access":{"kind":"site","permission":"site:read"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"html":{"type":"string"}},"required":["html"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/timeseries":{"get":{"operationId":"getTimeseries","summary":"Get the traffic time series","tags":["Analytics"],"description":"Visitors, sessions, pageviews, events, bounce rate and average session duration per time bucket (only those named in `metrics`, a comma list, when given). With a comparison window, each point carries the comparison's point at the same index under `previous` (null where that series is shorter).\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","enum":["previous","year"]},"in":"query","name":"compare","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_start","required":false},{"schema":{"type":"string"},"in":"query","name":"compare_end","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"query","name":"metrics","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"visitors":{"type":"number"},"sessions":{"type":"number"},"pageviews":{"type":"number"},"events":{"type":"number"},"bounce_rate":{"type":"number"},"avg_session_duration":{"type":"number"},"t":{"type":"string"},"previous":{"anyOf":[{"type":"object","properties":{"visitors":{"type":"number"},"sessions":{"type":"number"},"pageviews":{"type":"number"},"events":{"type":"number"},"bounce_rate":{"type":"number"},"avg_session_duration":{"type":"number"},"t":{"type":"string"}},"required":["t"],"additionalProperties":false},{"type":"null"}]}},"required":["t"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/traits/keys":{"get":{"operationId":"listTraitKeys","summary":"List trait keys","tags":["People"],"description":"The trait keys of the site's profiles, with how many users carry each, most used first.\n\nRequires `users:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `users:read` scope.","parameters":[{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["users:read"]},{"apiKeyBearer":["users:read"]},{"session":["users:read"]},{"shareToken":["users:read"]},{"shareTokenQuery":["users:read"]}],"x-pilotfox-access":{"kind":"site","permission":"users:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"users":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["key","users"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/traits/values":{"get":{"operationId":"listTraitValues","summary":"List trait values","tags":["People"],"description":"The values (as text) of the trait `key` across the site's profiles, with how many users have each, most common first.\n\nRequires `users:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `users:read` scope.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"query","name":"key","required":true},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["users:read"]},{"apiKeyBearer":["users:read"]},{"session":["users:read"]},{"shareToken":["users:read"]},{"shareTokenQuery":["users:read"]}],"x-pilotfox-access":{"kind":"site","permission":"users:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["value","count"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/users":{"get":{"operationId":"listUsers","summary":"List users","tags":["People"],"description":"The window's users, anonymous visitors included (identified ones only with `identified_only=true`, and only users not seen in the 90 days before the window with `new_only=true`), with their traits and activity, highest `sort` value first (`last_seen` by default), a page at a time (`meta.nextCursor`). `search` matches part of the user id, or of a profile's `name` or `email` trait; `traits` (a JSON object) keeps the users whose profile holds those traits.\n\nRequires `users:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `users:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":"last_seen","type":"string","enum":["last_seen","first_seen","sessions","pageviews","events"]},"in":"query","name":"sort","required":false},{"schema":{"type":"string"},"in":"query","name":"identified_only","required":false},{"schema":{"type":"string"},"in":"query","name":"new_only","required":false},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"search","required":false},{"schema":{"type":"string","maxLength":2000},"in":"query","name":"traits","required":false},{"schema":{"type":"string","maxLength":2200},"in":"query","name":"cursor","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["users:read"]},{"apiKeyBearer":["users:read"]},{"session":["users:read"]},{"shareToken":["users:read"]},{"shareTokenQuery":["users:read"]}],"x-pilotfox-access":{"kind":"site","permission":"users:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"identified":{"type":"boolean","description":"The key is a uid or an alias, not the raw visitor id"},"first_seen":{"type":"string","description":"First activity within the window"},"last_seen":{"type":"string","description":"Last activity within the window"},"sessions":{"type":"number"},"pageviews":{"type":"number"},"events":{"type":"number"},"visitors":{"type":"number"},"country":{"type":"string","description":"Of the latest session in the window, like region, city, device_type, browser and os"},"region":{"type":"string"},"city":{"type":"string"},"device_type":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"is_new":{"type":"boolean","description":"No session in the 90 days before the window (all-time: every user)"},"traits":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean"]}}},"required":["user_id","identified","first_seen","last_seen","sessions","pageviews","events","visitors","country","region","city","device_type","browser","os","is_new","traits"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/users/identify":{"post":{"operationId":"identifyVisitor","summary":"Identify a visitor","tags":["People"],"description":"Links a visitor id (a `visitor_id` as the reports show it; 400 otherwise) to a user id by hand, as the tracker's identify does, with optional traits merged into the profile's.\n\nRequires `users:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"visitorId":{"type":"string","maxLength":20},"userId":{"type":"string","minLength":1,"maxLength":255},"traits":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":64},"additionalProperties":{"type":["string","number","boolean","null"]}}},"required":["visitorId","userId"]}}}},"security":[{"apiKey":["users:write"]},{"apiKeyBearer":["users:write"]},{"session":["users:write"]}],"x-pilotfox-access":{"kind":"site","permission":"users:write"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"204":{"description":"No Content"}}}},"/api/v1/sites/{siteId}/users/summary":{"get":{"operationId":"getUsersSummary","summary":"Get the users summary","tags":["People"],"description":"Visitors, identified users, new and returning visitors, and sessions in the window.\n\nRequires `users:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `users:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["users:read"]},{"apiKeyBearer":["users:read"]},{"session":["users:read"]},{"shareToken":["users:read"]},{"shareTokenQuery":["users:read"]}],"x-pilotfox-access":{"kind":"site","permission":"users:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"visitors":{"type":"number"},"identified":{"type":"number"},"new":{"type":"number"},"returning":{"type":"number","description":"visitors - new"},"sessions":{"type":"number"}},"required":["visitors","identified","new","returning","sessions"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/users/{userId}":{"get":{"operationId":"getUser","summary":"Get a user","tags":["People"],"description":"One user's profile over all time: traits, totals, devices, locations, linked visitors, web vitals and an activity calendar. 404 for a user with neither a session nor a stored profile.\n\nRequires `users:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `users:read` scope.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"path","name":"userId","required":true}],"security":[{"apiKey":["users:read"]},{"apiKeyBearer":["users:read"]},{"session":["users:read"]},{"shareToken":["users:read"]},{"shareTokenQuery":["users:read"]}],"x-pilotfox-access":{"kind":"site","permission":"users:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user_id":{"type":"string"},"identified":{"type":"boolean","description":"A session's key is a uid or an alias, or a profile exists"},"traits":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean"]}},"profile":{"anyOf":[{"type":"object","properties":{"first_seen_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["first_seen_at","updated_at"],"additionalProperties":false},{"type":"null"}],"description":"The stored profile, null without one"},"first_seen":{"description":"First activity, all time; null without sessions","type":["string","null"]},"last_seen":{"type":["string","null"]},"totals":{"type":"object","properties":{"sessions":{"type":"number"},"pageviews":{"type":"number"},"events":{"type":"number"},"errors":{"type":"number"},"avg_session_duration":{"type":"number","description":"Seconds, over sessions with a pageview"}},"required":["sessions","pageviews","events","errors","avg_session_duration"],"additionalProperties":false},"devices":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"device_type":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"sessions":{"type":"number"}},"required":["device_type","browser","os","sessions"],"additionalProperties":false}},"locations":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"region":{"type":"string"},"region_name":{"type":"string"},"city":{"type":"string"},"sessions":{"type":"number"}},"required":["country","region","region_name","city","sessions"],"additionalProperties":false}},"linked_visitors":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"visitor_id":{"type":"string"},"sessions":{"type":"number"},"first_seen":{"type":"string"},"last_seen":{"type":"string"}},"required":["visitor_id","sessions","first_seen","last_seen"],"additionalProperties":false}},"vitals":{"type":"object","properties":{"lcp":{"description":"p75 over the user's sessions, null without a value","type":["number","null"]},"cls":{"description":"p75 over the user's sessions, null without a value","type":["number","null"]},"inp":{"description":"p75 over the user's sessions, null without a value","type":["number","null"]},"fcp":{"description":"p75 over the user's sessions, null without a value","type":["number","null"]},"ttfb":{"description":"p75 over the user's sessions, null without a value","type":["number","null"]}},"required":["lcp","cls","inp","fcp","ttfb"],"additionalProperties":false},"calendar":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"YYYY-MM-DD in the site's time zone"},"sessions":{"type":"number"},"pageviews":{"type":"number"}},"required":["date","sessions","pageviews"],"additionalProperties":false},"description":"Days with sessions in the 365 days up to last_seen"}},"required":["user_id","identified","traits","profile","first_seen","last_seen","totals","devices","locations","linked_visitors","vitals","calendar"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}},"delete":{"operationId":"eraseUser","summary":"Erase a user","tags":["People"],"description":"Queues the erasure of everything stored about the user on this site: events, session replays, aliases, the link of their payments and the profile. 202 with the job id, whether or not the user exists; 503 while background jobs are not running.\n\nRequires `users:delete` on the site (an API key, or a signed-in member's role). Share links: 401.","parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"path","name":"userId","required":true}],"security":[{"apiKey":["users:delete"]},{"apiKeyBearer":["users:delete"]},{"session":["users:delete"]}],"x-pilotfox-access":{"kind":"site","permission":"users:delete"},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"jobId":{"type":"string"}},"required":["jobId"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/users/{userId}/sessions":{"get":{"operationId":"listUserSessions","summary":"List a user's sessions","tags":["People"],"description":"The user's sessions (all time without window keys), sorted and narrowed as `/sessions` does (`sort`, `view`), a page at a time (`meta.nextCursor`).\n\nRequires `users:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `users:read` scope.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"default":"started","type":"string","enum":["started","ended","duration","pageviews","events"]},"in":"query","name":"sort","required":false},{"schema":{"default":"all","type":"string","enum":["all","identified","with_replay","converted","bounced","with_errors"]},"in":"query","name":"view","required":false},{"schema":{"type":"string","maxLength":2200},"in":"query","name":"cursor","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"path","name":"userId","required":true}],"security":[{"apiKey":["users:read"]},{"apiKeyBearer":["users:read"]},{"session":["users:read"]},{"shareToken":["users:read"]},{"shareTokenQuery":["users:read"]}],"x-pilotfox-access":{"kind":"site","permission":"users:read","allowShare":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"session_id":{"type":"string"},"visitor_id":{"type":"string"},"user_id":{"type":"string"},"identified":{"type":"boolean"},"started_at":{"type":"string"},"ended_at":{"type":"string"},"duration":{"type":"number","description":"Seconds, millisecond precision"},"pageviews":{"type":"number"},"events":{"type":"number"},"errors":{"type":"number"},"entry_page":{"type":"string"},"exit_page":{"type":"string"},"referrer_domain":{"type":"string"},"channel":{"type":"string"},"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"utm_term":{"type":"string"},"utm_content":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"region_name":{"type":"string"},"city":{"type":"string"},"lat":{"type":["number","null"]},"lon":{"type":["number","null"]},"browser":{"type":"string"},"os":{"type":"string"},"device_type":{"type":"string"},"screen":{"type":"string"},"language":{"type":"string"},"has_replay":{"type":"boolean"},"goal_ids":{"type":"array","items":{"type":"string"}}},"required":["session_id","visitor_id","user_id","identified","started_at","ended_at","duration","pageviews","events","errors","entry_page","exit_page","referrer_domain","channel","utm_source","utm_medium","utm_campaign","utm_term","utm_content","country","region","region_name","city","lat","lon","browser","os","device_type","screen","language","has_replay","goal_ids"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/users/{userId}/traits":{"put":{"operationId":"replaceUserTraits","summary":"Replace a user's traits","tags":["People"],"description":"Replaces every trait of the user's profile (a null value drops that key), creating the profile when there is none; the traits take 4 KB of JSON at most (400 past it).\n\nRequires `users:write` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"traits":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":64},"additionalProperties":{"type":["string","number","boolean","null"]}}},"required":["traits"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"path","name":"userId","required":true}],"security":[{"apiKey":["users:write"]},{"apiKeyBearer":["users:write"]},{"session":["users:write"]}],"x-pilotfox-access":{"kind":"site","permission":"users:write"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user_id":{"type":"string"},"traits":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean"]}},"first_seen_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["user_id","traits","first_seen_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/verify-install":{"post":{"operationId":"verifyInstall","summary":"Check the tracker installation","tags":["Sites"],"description":"Fetches the site's home page (`https://<domain>/`, then `http://` when https got no answer) and looks for this site's tracker script. Every outcome of the fetch is a 200: `installed`, or why not (`reason`). Send `{}` as the body: a request without one is 400. 10 a minute per caller.\n\nRequires `site:read` on the site (an API key, or a signed-in member's role). Share links: 401.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"security":[{"apiKey":["site:read"]},{"apiKeyBearer":["site:read"]},{"session":["site:read"]}],"x-pilotfox-access":{"kind":"site","permission":"site:read"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"type":"object","properties":{"installed":{"type":"boolean","enum":[true]},"url":{"type":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["installed","url","status"],"additionalProperties":false},{"type":"object","properties":{"installed":{"type":"boolean","enum":[false]},"url":{"type":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reason":{"type":"string","enum":["script_not_found","wrong_site","unreachable","timeout","blocked"]}},"required":["installed","url","reason"],"additionalProperties":false}]}},"required":["data"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/vitals":{"get":{"operationId":"getVitals","summary":"Get web vitals","tags":["Analytics"],"description":"The p50, p75, p90 and p99 of LCP, CLS, INP, FCP and TTFB in the window, with their sample counts and how many were good, needing improvement (`ni`) or poor by Google's thresholds.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"lcp":{"type":"object","properties":{"p50":{"type":["number","null"]},"p75":{"type":["number","null"]},"p90":{"type":["number","null"]},"p99":{"type":["number","null"]},"good":{"type":"number"},"ni":{"type":"number"},"poor":{"type":"number"},"count":{"type":"number"}},"required":["p50","p75","p90","p99","good","ni","poor","count"],"additionalProperties":false},"cls":{"type":"object","properties":{"p50":{"type":["number","null"]},"p75":{"type":["number","null"]},"p90":{"type":["number","null"]},"p99":{"type":["number","null"]},"good":{"type":"number"},"ni":{"type":"number"},"poor":{"type":"number"},"count":{"type":"number"}},"required":["p50","p75","p90","p99","good","ni","poor","count"],"additionalProperties":false},"inp":{"type":"object","properties":{"p50":{"type":["number","null"]},"p75":{"type":["number","null"]},"p90":{"type":["number","null"]},"p99":{"type":["number","null"]},"good":{"type":"number"},"ni":{"type":"number"},"poor":{"type":"number"},"count":{"type":"number"}},"required":["p50","p75","p90","p99","good","ni","poor","count"],"additionalProperties":false},"fcp":{"type":"object","properties":{"p50":{"type":["number","null"]},"p75":{"type":["number","null"]},"p90":{"type":["number","null"]},"p99":{"type":["number","null"]},"good":{"type":"number"},"ni":{"type":"number"},"poor":{"type":"number"},"count":{"type":"number"}},"required":["p50","p75","p90","p99","good","ni","poor","count"],"additionalProperties":false},"ttfb":{"type":"object","properties":{"p50":{"type":["number","null"]},"p75":{"type":["number","null"]},"p90":{"type":["number","null"]},"p99":{"type":["number","null"]},"good":{"type":"number"},"ni":{"type":"number"},"poor":{"type":"number"},"count":{"type":"number"}},"required":["p50","p75","p90","p99","good","ni","poor","count"],"additionalProperties":false}},"required":["lcp","cls","inp","fcp","ttfb"],"additionalProperties":false},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/vitals/breakdown":{"get":{"operationId":"getVitalsBreakdown","summary":"Get a web vitals breakdown","tags":["Analytics"],"description":"One metric's percentile `p` (`value_metric`) and good, needs-improvement and poor counts per value of `dim` (`pathname`, `country`, `device_type`, `browser`, `os` or `region`), most samples first, a page at a time.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","enum":["lcp","cls","inp","fcp","ttfb"]},"in":"query","name":"metric","required":true},{"schema":{"default":"p75","type":"string","enum":["p50","p75","p90","p99"]},"in":"query","name":"p","required":false,"description":"The percentile reported: each point's `value` (time series) or each row's `value_metric` (breakdown)"},{"schema":{"type":"string","enum":["pathname","country","device_type","browser","os","region"]},"in":"query","name":"dim","required":true},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"value_metric":{"type":["number","null"]},"count":{"type":"number"},"good":{"type":"number"},"ni":{"type":"number"},"poor":{"type":"number"}},"required":["value","value_metric","count","good","ni","poor"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/api/v1/sites/{siteId}/vitals/timeseries":{"get":{"operationId":"getVitalsTimeseries","summary":"Get a web vital time series","tags":["Analytics"],"description":"One metric's percentile `p` per time bucket, with its sample count.\n\nRequires `analytics:read` on the site (an API key, or a signed-in member's role). Share links: allowed, with the `analytics:read` scope. Public sites: open to everyone, no credential needed.","parameters":[{"schema":{"type":"string"},"in":"query","name":"start","required":false},{"schema":{"type":"string"},"in":"query","name":"end","required":false},{"schema":{"type":"string"},"in":"query","name":"last","required":false},{"schema":{"type":"string","enum":["true"]},"in":"query","name":"all","required":false},{"schema":{"type":"string"},"in":"query","name":"tz","required":false},{"schema":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]},"in":"query","name":"bucket","required":false},{"schema":{"type":"string","maxLength":64000},"in":"query","name":"filters","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"segment","required":false},{"schema":{"type":"string","enum":["lcp","cls","inp","fcp","ttfb"]},"in":"query","name":"metric","required":true},{"schema":{"default":"p75","type":"string","enum":["p50","p75","p90","p99"]},"in":"query","name":"p","required":false,"description":"The percentile reported: each point's `value` (time series) or each row's `value_metric` (breakdown)"},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"security":[{"apiKey":["analytics:read"]},{"apiKeyBearer":["analytics:read"]},{"session":["analytics:read"]},{"shareToken":["analytics:read"]},{"shareTokenQuery":["analytics:read"]},{}],"x-pilotfox-access":{"kind":"site","permission":"analytics:read","allowShare":true,"allowPublic":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"value":{"type":["number","null"]},"count":{"type":"number"}},"required":["t","value","count"],"additionalProperties":false}},"meta":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"tz":{"type":"string"},"bucket":{"type":"string","enum":["minute","5m","15m","hour","day","week","month","year"]}},"required":["from","to","tz","bucket"],"additionalProperties":false},"compare":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"type":["string","null"]},"truncated":{"type":"boolean"},"cache":{"type":"string","enum":["hit","miss","coalesced"]}},"required":["window"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}}}}},"/maps/tiles/boundaries/{z}/{x}/{y}.mvt":{"get":{"operationId":"getBoundaryTile","summary":"Get a boundary map tile","tags":["Geography"],"description":"One XYZ vector tile (Mapbox Vector Tile) of the country and region boundaries the dashboard's maps draw (source layers `countries` and `regions`, keyed by `code`), for Mapbox GL JS or MapLibre GL JS; the URL template is in `GET /api/v1/config` (`maps.boundaries`). Public. With `?v=` set to the archive's ETag it is cached for a day as immutable, otherwise for five minutes; 204 for an empty tile, 404 outside the archive or when the instance has none.","security":[],"parameters":[{"schema":{"type":"string"},"in":"path","name":"z","required":true},{"schema":{"type":"string"},"in":"path","name":"x","required":true},{"schema":{"type":"string"},"in":"path","name":"y","required":true}],"responses":{"200":{"description":"The tile","content":{"application/vnd.mapbox-vector-tile":{"schema":{"type":"string"}}}},"204":{"description":"No Content: nothing in this tile"},"304":{"description":"Not Modified: the `If-None-Match` tag is current"}}}}},"servers":[{"url":"{protocol}://{host}","description":"pilotfox.app, or a self-hosted instance at its own PUBLIC_URL","variables":{"protocol":{"enum":["https","http"],"default":"https"},"host":{"default":"pilotfox.app","description":"The instance's host (and port, if any): pilotfox.app, or the host of a self-hosted PUBLIC_URL"}}}],"tags":[{"name":"System","description":"Liveness and readiness probes, and the instance settings the web app reads first."},{"name":"Account","description":"The signed-in user, their organizations, their email report subscriptions and what deleting the account would do."},{"name":"Organizations","description":"Organization-wide reports and who sees which site: restricted members' and teams' site grants."},{"name":"API keys","description":"An organization's API keys: list, create (the only answer with the key), delete."},{"name":"Sites","description":"Sites, their settings, the tracking snippet, install check and first-party proxy."},{"name":"Share links","description":"Read-only links to one site's dashboard, and what a link opens."},{"name":"Analytics","description":"Traffic reports of a site: overview, time series, breakdowns, pages, heatmap and web vitals, and referrer icons."},{"name":"Events","description":"Custom and autocaptured events: names, properties, counts and the raw event list."},{"name":"Errors","description":"JavaScript errors the tracker captured, grouped by fingerprint."},{"name":"Geography","description":"Countries, regions, cities and map points of visitors, and the map tiles."},{"name":"Live","description":"Who is on the site now: counts, visitors and the server-sent event stream."},{"name":"Bots","description":"Bot and AI crawler traffic that ingest set aside from the visitor reports."},{"name":"People","description":"Visitors and identified users: profiles, traits, sessions and erasure."},{"name":"Sessions","description":"Sessions and their event timelines."},{"name":"Goals","description":"Conversion goals, their stats and the conversions behind them."},{"name":"Funnels","description":"Saved and ad hoc funnels, their reports and the sessions in each step."},{"name":"Journeys","description":"Paths visitors take through the site, and cohort retention."},{"name":"Segments","description":"Saved filters, which the analytics reports apply with `segment=`."},{"name":"Annotations","description":"Notes on a date or a date range of a site's charts, or of every site of the organization."},{"name":"Replays","description":"Session recordings: list, play back and delete."},{"name":"Revenue","description":"Revenue reports, subscriptions and payments, from connected providers and the payments API."},{"name":"Payment providers","description":"Connections to Stripe, Polar and Dodo Payments, whose payments feed the revenue reports."},{"name":"Affiliates","description":"A site's affiliates, their reports, and the portal each one can open."},{"name":"Search Console","description":"Google Search Console connections, property links and search reports."},{"name":"Notifications","description":"New-sale notifications and email report settings of a site."},{"name":"Imports","description":"Bring history in from other analytics tools or a PilotFox export."},{"name":"Exports","description":"A site's raw events as NDJSON."},{"name":"Ingest","description":"Server-side event ingest and identify, with API keys."},{"name":"Tracker","description":"The browser tracker: its scripts and the endpoints it sends to (no credential)."},{"name":"MCP","description":"The Model Context Protocol server, and the OAuth discovery documents of its clients."},{"name":"Auth","description":"The web app's sign-in and account endpoints, and the OAuth authorization server of MCP clients."},{"name":"Admin","description":"Instance administration for system administrators: statistics, organizations and sites, jobs, backups."}]}