{"openapi":"3.1.0","info":{"title":"Clickport API","version":"2026-09-08","description":"Read your Clickport analytics, ingest events and revenue, and pull AI agent (crawler/citation) data. Authenticate with a site or team API key: an Authorization: Bearer <key> header, or x-api-key: <key>."},"servers":[{"url":"https://clickport.io"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key sent as Authorization: Bearer <key>."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key sent as x-api-key: <key>."}}},"paths":{"/api/event":{"post":{"summary":"Ingest one tracking event. Normal tracker.js installations use data-domain without a key. Keyed installations accept events.write or a private legacy tracker key.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"events.write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Internal tracker.js event payload."}}}},"responses":{"200":{"description":"Accepted (or silently dropped, e.g. rate-limited).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success"]}}}}}}},"/api/revenue":{"post":{"summary":"Record a revenue event (order or refund) from your own backend.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"tracker","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","description":"Unique per site. Retries with the same id are acknowledged but never double-counted."},"amount":{"type":"number","description":"Major units. Negative = refund."},"currency":{"type":"string","description":"3-letter ISO code, e.g. USD."},"ref":{"type":"string","description":"clickport.checkoutRef() token for session attribution."},"refund_of":{"type":"string","description":"The original order_id this refund belongs to."},"occurred_at":{"type":"string","description":"ISO-8601 or epoch seconds. Default now, max 90 days back."},"source":{"type":"string","description":"Free-form label, lands in the event meta."}},"required":["order_id","amount","currency"]}}}},"responses":{"200":{"description":"Recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":true}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent-visits":{"post":{"summary":"Ingest a batch of AI agent fetch lines from a connector, as newline-delimited JSON.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"agent-visits","requestBody":{"required":true,"content":{"application/x-ndjson":{"schema":{"type":"string","description":"One JSON object per line, each with keys: ts, path, method, status, duration_ms, headers, connector, connector_version. Optionally gzip-compressed (Content-Encoding: gzip)."}}}},"responses":{"204":{"description":"Accepted. See the x-agent-visits-accepted / x-agent-visits-truncated response headers for the per-batch outcome."},"400":{"description":"Malformed body (bad gzip/encoding).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"415":{"description":"Wrong Content-Type; must be application/x-ndjson.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/query":{"post":{"summary":"Flexible metrics/dimensions query, the same engine every dashboard panel uses.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","enum":["today","yesterday","24h","7d","14d","30d","90d","12m","all","realtime"],"description":"Default 'today'."},"date_range":{"type":"object","description":"Overrides period. start inclusive, end exclusive, both YYYY-MM-DD.","properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"}}},"metrics":{"type":"array","items":{"type":"string"},"description":"Default ['visitors']."},"dimensions":{"type":"array","items":{"type":"string"},"description":"Zero or more breakdown dimensions."},"filters":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"operator":{"type":"string","enum":["is","is_not","contains","not_contains"]},"value":{"type":"string"}},"required":["dimension","operator","value"]}},"order_by":{"type":"string"},"order_dir":{"type":"string","enum":["asc","desc"]},"limit":{"type":"integer","minimum":1,"maximum":10000,"description":"Default 100."},"offset":{"type":"integer","minimum":0},"include_comparison":{"type":"boolean"},"timezone":{"type":"string","description":"Default UTC."}}}}}},"responses":{"200":{"description":"Query result.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/mcp":{"post":{"summary":"MCP (Model Context Protocol) JSON-RPC endpoint, Streamable HTTP transport, stateless.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"A single JSON-RPC 2.0 message, or a batch (array) of up to 10.","oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","additionalProperties":true}}]}}}},"responses":{"200":{"description":"JSON-RPC response, or an array of responses for a batch request.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"All messages in the batch were notifications; no response body."}}}},"/api/realtime":{"get":{"summary":"Who is on the site right now.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Current activity.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","description":"Currently-active visitors."},"visitors":{"type":"array","description":"Up to 100 active sessions, most recently active first.","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/goals":{"get":{"summary":"Conversion numbers for every configured goal over a date range.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"period","in":"query","required":false,"description":"Named date range. Alternative to start_date/end_date.","schema":{"type":"string","enum":["today","yesterday","24h","7d","14d","30d","90d","12m","all","realtime"]}},{"name":"start_date","in":"query","required":false,"description":"Start date, YYYY-MM-DD. Used together with end_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"End date, YYYY-MM-DD, exclusive. Used together with start_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"timezone","in":"query","required":false,"description":"IANA timezone for date boundaries, e.g. 'Europe/Berlin'. Default UTC.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Click-goal product rows to return. Default 100, max 500.","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Default 0.","schema":{"type":"integer"}},{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Goals for the range. Empty when start_date/end_date are omitted.","content":{"application/json":{"schema":{"type":"object","properties":{"goals":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"visitors":{"type":"integer"},"total_revenue":{"type":"number"},"average_revenue":{"type":"number"}}}}}}}}}}}},"/api/pages":{"get":{"summary":"Top pages breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/sources":{"get":{"summary":"Top traffic sources breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/referrers":{"get":{"summary":"Top referrer URLs breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/countries":{"get":{"summary":"Top countries breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/languages":{"get":{"summary":"Top visitor languages breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/locales":{"get":{"summary":"Top visitor locales breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/campaigns":{"get":{"summary":"Top campaigns breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/utm-sources":{"get":{"summary":"Top utm_source values breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/utm-mediums":{"get":{"summary":"Top utm_medium values breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/utm-content":{"get":{"summary":"Top utm_content values breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/utm-term":{"get":{"summary":"Top utm_term values breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/entry-pages":{"get":{"summary":"Top entry pages breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/exit-pages":{"get":{"summary":"Top exit pages breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/tech":{"get":{"summary":"Device, browser, and OS breakdown.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response. Exact shape follows the dashboard panel this route feeds; see ARCHITECTURE.md.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agent-visits/report":{"get":{"summary":"AI agent traffic report: KPIs, per-company funnel, top agents, top pages, and a timeseries.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"period","in":"query","required":false,"description":"Named date range. Alternative to start_date/end_date.","schema":{"type":"string","enum":["today","yesterday","24h","7d","14d","30d","90d","12m","all","realtime"]}},{"name":"start_date","in":"query","required":false,"description":"Start date, YYYY-MM-DD. Used together with end_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"End date, YYYY-MM-DD, exclusive. Used together with start_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"timezone","in":"query","required":false,"description":"IANA timezone for date boundaries, e.g. 'Europe/Berlin'. Default UTC.","schema":{"type":"string"}},{"name":"pages_limit","in":"query","required":false,"description":"Rows in the pages array. Default 50, max 500.","schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"AI agent report for the range.","content":{"application/json":{"schema":{"type":"object","properties":{"has_data":{"type":"boolean"},"kpis":{"type":"object","properties":{"citations":{"type":"integer","description":"Verified live_retrieval hits (see cited in the vocabulary)."},"crawls":{"type":"integer","description":"Verified hits that are not live_retrieval and not search."},"spoofed":{"type":"integer"},"ai_visits":{"type":"integer","description":"Human sessions that arrived from an AI referrer (demand side)."},"ai_conversions":{"type":"integer"}}},"funnel":{"type":"array","items":{"type":"object","properties":{"company":{"type":"string"},"ingested":{"type":"integer"},"cited":{"type":"integer"},"visits":{"type":"integer"},"conversions":{"type":"integer"}}}},"agents":{"type":"array","items":{"type":"object","properties":{"agent":{"type":"string"},"company":{"type":"string"},"intent":{"type":"string","enum":["live_retrieval","indexing","training","search"]},"hits":{"type":"integer"},"verified":{"type":"integer"},"spoofed":{"type":"integer"},"last_seen":{"type":"string","format":"date-time"}}}},"pages":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"hits":{"type":"integer"},"cited":{"type":"integer"},"visitors":{"type":"integer"}}}},"timeseries":{"type":"array","items":{"type":"object","properties":{"slot":{"type":"string"},"cited":{"type":"integer"},"crawled":{"type":"integer"}}}},"granularity":{"type":"string","enum":["hourly","daily"]}},"additionalProperties":true}}}}}}},"/api/agent-visits/summary":{"get":{"summary":"Light aggregate for the AI agent channel: totals and connection state.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"period","in":"query","required":false,"description":"Named date range. Alternative to start_date/end_date.","schema":{"type":"string","enum":["today","yesterday","24h","7d","14d","30d","90d","12m","all","realtime"]}},{"name":"start_date","in":"query","required":false,"description":"Start date, YYYY-MM-DD. Used together with end_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"End date, YYYY-MM-DD, exclusive. Used together with start_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"timezone","in":"query","required":false,"description":"IANA timezone for date boundaries, e.g. 'Europe/Berlin'. Default UTC.","schema":{"type":"string"}},{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Summary for the range, plus all-time connection state.","content":{"application/json":{"schema":{"type":"object","properties":{"has_data":{"type":"boolean"},"citations":{"type":"integer"},"crawls":{"type":"integer"},"spoofed":{"type":"integer"},"last_hit":{"type":["string","null"],"format":"date-time"},"last_connector":{"type":["string","null"]},"last_test_hit":{"type":["string","null"],"format":"date-time"},"last_test_connector":{"type":["string","null"]}},"additionalProperties":true}}}}}}},"/api/agent-visits/page-engines":{"get":{"summary":"Per-company AI read split for one page.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"period","in":"query","required":false,"description":"Named date range. Alternative to start_date/end_date.","schema":{"type":"string","enum":["today","yesterday","24h","7d","14d","30d","90d","12m","all","realtime"]}},{"name":"start_date","in":"query","required":false,"description":"Start date, YYYY-MM-DD. Used together with end_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"End date, YYYY-MM-DD, exclusive. Used together with start_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"timezone","in":"query","required":false,"description":"IANA timezone for date boundaries, e.g. 'Europe/Berlin'. Default UTC.","schema":{"type":"string"}},{"name":"path","in":"query","required":true,"description":"Exact page path.","schema":{"type":"string"}},{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Per-company reads for the page.","content":{"application/json":{"schema":{"type":"object","properties":{"engines":{"type":"array","items":{"type":"object","properties":{"company":{"type":"string"},"cited":{"type":"integer"},"hits":{"type":"integer"},"visitors":{"type":"integer"}}}}}}}}}}}},"/api/agent-visits/series":{"get":{"summary":"One company's or one page's AI-read timeseries, bucketed to match the main dashboard chart.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"period","in":"query","required":false,"description":"Named date range. Alternative to start_date/end_date.","schema":{"type":"string","enum":["today","yesterday","24h","7d","14d","30d","90d","12m","all","realtime"]}},{"name":"start_date","in":"query","required":false,"description":"Start date, YYYY-MM-DD. Used together with end_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"End date, YYYY-MM-DD, exclusive. Used together with start_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"timezone","in":"query","required":false,"description":"IANA timezone for date boundaries, e.g. 'Europe/Berlin'. Default UTC.","schema":{"type":"string"}},{"name":"company","in":"query","required":false,"description":"Limit to one company. company or path is required.","schema":{"type":"string"}},{"name":"path","in":"query","required":false,"description":"Limit to one page path. company or path is required.","schema":{"type":"string"}},{"name":"granularity","in":"query","required":false,"description":"Default 'daily'.","schema":{"type":"string","enum":["minute","hourly","hourly_crossday","weekly","monthly","daily"]}},{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Timeseries for the given company or path.","content":{"application/json":{"schema":{"type":"object","properties":{"series":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"One row per bucket. The time key (hour, date, week, or datetime) matches the requested granularity; reads and cited are always present.","properties":{"reads":{"type":"integer"},"cited":{"type":"integer"}}}}}}}}}}}},"/api/agent-visits/live":{"get":{"summary":"Last 30 minutes of AI agent fetches (up to 30 rows).","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Live feed.","content":{"application/json":{"schema":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"agent":{"type":"string"},"company":{"type":"string"},"intent":{"type":"string","enum":["live_retrieval","indexing","training","search"]},"verification":{"type":"string","enum":["verified","unverifiable","spoofed"]},"path":{"type":"string"}}}}}}}}}}}},"/api/agent-visits/hits":{"get":{"summary":"Raw per-fetch AI agent log, cursor-paginated. The closest thing to the connector's own event stream.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","parameters":[{"name":"period","in":"query","required":false,"description":"Named date range. Alternative to start_date/end_date.","schema":{"type":"string","enum":["today","yesterday","24h","7d","14d","30d","90d","12m","all","realtime"]}},{"name":"start_date","in":"query","required":false,"description":"Start date, YYYY-MM-DD. Used together with end_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"End date, YYYY-MM-DD, exclusive. Used together with start_date instead of period.","schema":{"type":"string","format":"date"}},{"name":"timezone","in":"query","required":false,"description":"IANA timezone for date boundaries, e.g. 'Europe/Berlin'. Default UTC.","schema":{"type":"string"}},{"name":"company","in":"query","required":false,"description":"Exact company name, e.g. OpenAI.","schema":{"type":"string"}},{"name":"agent","in":"query","required":false,"description":"Exact agent name, e.g. GPTBot.","schema":{"type":"string"}},{"name":"intent","in":"query","required":false,"description":"Filter to one intent.","schema":{"type":"string","enum":["live_retrieval","indexing","training","search"]}},{"name":"path","in":"query","required":false,"description":"Exact page path.","schema":{"type":"string"}},{"name":"include_spoofed","in":"query","required":false,"description":"Set to 1 to include spoofed rows. Default excludes them.","schema":{"type":"integer","enum":[0,1]}},{"name":"limit","in":"query","required":false,"description":"Rows per page. Default 500, max 1000.","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response's next_cursor, for the next page.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"'ndjson' streams one JSON object per line instead of the { hits, next_cursor } envelope. Default 'json'.","schema":{"type":"string","enum":["json","ndjson"]}},{"name":"site_domain","in":"query","required":false,"description":"Required for team keys: the site's domain as added to Clickport. Ignored (and unnecessary) for a site-scoped key.","schema":{"type":"string"}},{"name":"site_id","in":"query","required":false,"description":"Also accepted: the numeric site id. Prefer site_domain.","schema":{"type":"integer"}}],"responses":{"200":{"description":"A page of hits.","content":{"application/json":{"schema":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"UTC."},"agent":{"type":"string"},"company":{"type":"string"},"intent":{"type":"string","enum":["live_retrieval","indexing","training","search"]},"verification":{"type":"string","enum":["verified","unverifiable","spoofed"]},"path":{"type":"string"},"status":{"type":"integer"},"duration_ms":{"type":"integer"},"connector":{"type":"string"}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page, or null when there are no more rows."}}}},"application/x-ndjson":{"schema":{"type":"string","description":"One hit object per line; a trailing {\"next_cursor\": ...} line when there are more rows."}}}}}}},"/api/team/sites":{"get":{"summary":"List the calling team's sites. Team API key only (403 for a site-scoped key).","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"read","responses":{"200":{"description":"The team's sites.","content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"timezone":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"verified_at":{"type":["string","null"],"format":"date-time"}}}},"all_sites_view_domain":{"type":["string","null"],"description":"The consolidated All-sites view's domain, or null if the team has none."}}}}}}}},"post":{"summary":"Create a site for the calling team and return its tracker and AI Agents keys. Idempotent on domain. Team API key only.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-clickport-scope":"sites.manage","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Bare host, e.g. example.com."},"timezone":{"type":"string","description":"IANA timezone. Default UTC."}},"required":["domain"]}}}},"responses":{"200":{"description":"Created, or already existed in this team (created: false, no keys reissued).","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean","description":"false when the domain already existed in this team; no keys are re-issued."},"site":{"type":"object","properties":{"domain":{"type":"string"},"timezone":{"type":"string"}}},"tracker_key":{"type":"string","description":"Only present when created is true. Event-only key (events.write) for legacy keyed trackers. Cannot read analytics or call the Revenue API. Normal website installation uses data-domain and needs no key."},"agent_key":{"type":"string","description":"Only present when created is true."},"dashboard_url":{"type":"string","format":"uri"}}}}}},"403":{"description":"Site limit reached for this team.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"This domain is already registered to a different team.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}}}