{ "openapi": "3.1.0", "info": { "title": "Totallytics API", "version": "2026-09-18", "description": "Current unversioned API; the document version is a reference revision, not a URL prefix. Product management uses Firebase ID bearer tokens. Public site metadata and stats can be read anonymously; private reads require the owner. Collector routes require no token. Product API responses have no cross-origin CORS headers, so use a server-side or same-origin client. Collector CORS is separate. Successful collection is receipt, not durable storage confirmation. Write examples use placeholder hostnames; demo.bitgate.dev is for read-only examples. Site lookups are cached per server instance for five minutes (existing) or one minute (missing). Historical-import routes require the site owner even for public sites; source discovery requires sign-in. Import creation is asynchronous; verify progress and actual reports before considering a migration complete. No product API-key or SDK is defined here." }, "servers": [ { "url": "https://totallytics.com" } ], "externalDocs": { "description": "Developer documentation", "url": "https://analytics.bitgate.dev/docs" }, "tags": [ { "name": "Sites", "description": "Site registration, ownership and visibility." }, { "name": "Stats", "description": "Overview, dimension breakdowns and account summaries." }, { "name": "Imports", "description": "Owner-only historical import jobs. Source discovery requires sign-in. Asynchronous jobs, not an exactly-once data migration guarantee." }, { "name": "Collector", "description": "Browser tracking and ingestion. No authentication." }, { "name": "Health", "description": "HTTP liveness and global preflight behavior." } ], "security": [], "paths": { "/api/sites": { "get": { "tags": [ "Sites" ], "operationId": "listSites", "summary": "List your sites", "description": "Returns all caller-owned sites ordered by creation time. Requires a Firebase ID token; no pagination.", "responses": { "200": { "description": "Owned site list.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitesResponse" }, "example": { "sites": [] } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "FirebaseIdToken": [] } ] }, "post": { "tags": [ "Sites" ], "operationId": "createSite", "summary": "Register a hostname", "description": "Registers a globally unique hostname to the signed-in account. New sites are private with an empty display name. Maximum 50 sites per account. No hostname verification workflow is performed by this route.", "responses": { "201": { "description": "Site registered.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedSite" }, "example": { "hostname": "your-domain.example" } } } }, "400": { "description": "Hostname validation or account site limit failed.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "hostname": { "value": { "error": "invalid hostname" } }, "limit": { "value": { "error": "site limit reached" } } } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "409": { "$ref": "#/components/responses/SiteExists" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "FirebaseIdToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSite" }, "example": { "hostname": "your-domain.example" } } } } }, "options": { "tags": [ "Health" ], "operationId": "preflight_api_sites", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/api/sites/summary": { "get": { "tags": [ "Stats" ], "operationId": "getSitesSummary", "summary": "Summarize your sites", "description": "Authenticated account-wide report, even for public sites. Sparse daily rollups from a rolling cutoff 31 days ago plus independent five-minute live counts. All owned sites are included in creation order; inactive sites have days: [] and live: 0. The first day can be partial. Only tz is read; from, to and limit are ignored.", "responses": { "200": { "description": "Owned-site summary.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryResponse" }, "example": { "sites": [ { "hostname": "your-domain.example", "live": 0, "days": [ { "day": "2026-09-16", "pageviews": 3, "visitors": 2 } ] } ] } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "FirebaseIdToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Timezone" } ] }, "options": { "tags": [ "Health" ], "operationId": "preflight_api_sites_summary", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/api/sites/{hostname}": { "parameters": [ { "$ref": "#/components/parameters/Hostname" } ], "get": { "tags": [ "Sites" ], "operationId": "getSite", "summary": "Read site metadata", "description": "Anonymous access is allowed only for a public site. Private sites require their owner token. Unknown site returns 404, unauthenticated private reads 401, and another account 403. Public reads do not validate the token. Site lookups cache existing entries for five minutes and misses for one minute per server instance.", "responses": { "200": { "description": "Site metadata, without owner_uid.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" }, "example": { "hostname": "demo.bitgate.dev", "display_name": "Demo site", "is_public": true, "created_at": "2026-09-17T17:28:42.089Z" } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "403": { "$ref": "#/components/responses/NotYourSite" }, "404": { "$ref": "#/components/responses/UnknownSite" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ {}, { "FirebaseIdToken": [] } ], "parameters": [ { "name": "hostname", "in": "path", "required": true, "description": "Use the normalized hostname returned at registration. Lookups do not lowercase path values.", "schema": { "type": "string" }, "example": "demo.bitgate.dev" } ] }, "patch": { "tags": [ "Sites" ], "operationId": "updateSite", "summary": "Update name and visibility", "description": "Owner only, even if the site is public. Changes display_name and is_public; no rename or ownership transfer. The handling instance invalidates its lookup cache, but other instances can retain an existing entry for up to five minutes.", "responses": { "200": { "description": "Current name and visibility.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatedSite" }, "example": { "hostname": "your-domain.example", "display_name": "My website", "is_public": false } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "403": { "$ref": "#/components/responses/NotYourSite" }, "404": { "$ref": "#/components/responses/UnknownSite" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "FirebaseIdToken": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSite" }, "example": { "display_name": "My website", "is_public": false } } } } }, "delete": { "tags": [ "Sites" ], "operationId": "deleteSite", "summary": "Remove a site registration", "description": "Owner only. Deletes the registry entry, not historical analytics. Once cached registrations expire, reports return 404 and new collection is normally discarded. Does not provide data erasure. A later deletion of a missing registration returns 404. Associated import-job records are deleted by database cascade; previously imported analytics remain.", "responses": { "200": { "description": "Registration removed.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedSite" }, "example": { "deleted": "your-domain.example" } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "403": { "$ref": "#/components/responses/NotYourSite" }, "404": { "$ref": "#/components/responses/UnknownSite" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "FirebaseIdToken": [] } ] }, "options": { "tags": [ "Health" ], "operationId": "preflight_api_sites_hostname", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/api/sites/{hostname}/overview": { "parameters": [ { "name": "hostname", "in": "path", "required": true, "description": "Use the normalized hostname returned at registration. Lookups do not lowercase path values.", "schema": { "type": "string" }, "example": "demo.bitgate.dev" } ], "get": { "tags": [ "Stats" ], "operationId": "getOverview", "summary": "Read traffic overview", "description": "Public site or owner. Access is checked before query validation. Returns totals, previous equal-length period, sparse series, live and granularity. Pageviews/visitors filter hourly aggregates by bucket start: non-hour-aligned bounds differ from exact-timestamp breakdowns. Append averages filter individual append timestamps and are per append row, not pageview. Visitor identifiers rotate daily in UTC; overview distinct counts are approximate. Live counts all non-bot row types over the last five minutes, independent of the selected range.", "responses": { "200": { "description": "Traffic overview.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverviewResponse" }, "example": { "totals": { "pageviews": 3, "visitors": 2, "avg_duration_s": 42, "avg_scroll": 75 }, "previous": { "pageviews": 2, "visitors": 2, "avg_duration_s": 30, "avg_scroll": 50 }, "series": [ { "t": 1789516800, "pageviews": 1, "visitors": 1 }, { "t": 1789520400, "pageviews": 2, "visitors": 2 } ], "live": 0, "granularity": "hour" } } } }, "400": { "description": "The rounded range is non-finite, has from >= to, or exceeds 400 days.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid range" } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "403": { "$ref": "#/components/responses/NotYourSite" }, "404": { "$ref": "#/components/responses/UnknownSite" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ {}, { "FirebaseIdToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/Timezone" } ] }, "options": { "tags": [ "Health" ], "operationId": "preflight_api_sites_hostname_overview", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/api/sites/{hostname}/breakdown": { "parameters": [ { "name": "hostname", "in": "path", "required": true, "description": "Use the normalized hostname returned at registration. Lookups do not lowercase path values.", "schema": { "type": "string" }, "example": "demo.bitgate.dev" } ], "get": { "tags": [ "Stats" ], "operationId": "getBreakdown", "summary": "Read a traffic breakdown", "description": "Public site or owner. Counts raw non-bot rows within exact timestamps; events counts event rows and other dimensions count pageviews. Group visitors are exact distinct daily-rotating identifiers. Empty labels are omitted except pages/referrers, where they become Direct / none. Sorted by value descending. tz is ignored. No metadata query, arbitrary filters, pagination cursor, offset or total-row count. Access is checked before dimension and range validation.", "responses": { "200": { "description": "Ranked groups.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreakdownResponse" }, "example": { "rows": [ { "name": "/pricing", "value": 3, "visitors": 2 } ] } } } }, "400": { "description": "Missing/unknown dimension, or invalid range.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "dimension": { "value": { "error": "unknown dimension" } }, "range": { "value": { "error": "invalid range" } } } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "403": { "$ref": "#/components/responses/NotYourSite" }, "404": { "$ref": "#/components/responses/UnknownSite" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ {}, { "FirebaseIdToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Dimension" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/Limit" } ] }, "options": { "tags": [ "Health" ], "operationId": "preflight_api_sites_hostname_breakdown", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/latest.js": { "get": { "tags": [ "Collector" ], "operationId": "getTrackerScript", "summary": "Load the browser tracker", "description": "Serves the tracker script, which sends subsequent pageview and event requests. Loading the file alone does not collect a pageview. Configure it using script-tag attributes; see the installation guide.", "responses": { "200": { "description": "Browser JavaScript.", "headers": { "Access-Control-Allow-Origin": { "$ref": "#/components/headers/AllowOrigin" }, "Access-Control-Allow-Methods": { "$ref": "#/components/headers/AllowMethods" }, "Access-Control-Allow-Headers": { "$ref": "#/components/headers/AllowHeaders" }, "Access-Control-Max-Age": { "$ref": "#/components/headers/PreflightMaxAge" }, "Cache-Control": { "schema": { "type": "string", "const": "public, max-age=86400, stale-while-revalidate=604800" } } }, "content": { "application/javascript": { "schema": { "type": "string" } } } } }, "security": [] }, "options": { "tags": [ "Collector" ], "operationId": "preflight_latest_js", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/simple.gif": { "get": { "tags": [ "Collector" ], "operationId": "collectPixel", "summary": "Collect via an image beacon", "description": "Collection, not a read-only report. Reads the shared payload fields from query parameters. Metadata is a URL-encoded string. A valid payload returns a GIF; validation failures return text. No authentication. Normally only registered hostnames are stored; a registry lookup failure can bypass that check. DNT: 1 or X-Do-Not-Track: 1 skips before payload validation unless collect-dnt is true.", "responses": { "200": { "$ref": "#/components/responses/PixelOk" }, "400": { "$ref": "#/components/responses/CollectorBadRequest" } }, "security": [], "parameters": [ { "name": "hostname", "in": "query", "description": "Required after scalar-to-string conversion. Lowercased and truncated to 253 characters, not trimmed. Use the exact registered hostname without scheme, port or path.", "schema": { "type": "string" }, "example": "your-domain.example", "required": true }, { "$ref": "#/components/parameters/CollectType" }, { "$ref": "#/components/parameters/CollectEvent" }, { "$ref": "#/components/parameters/CollectPath" }, { "$ref": "#/components/parameters/CollectQuery" }, { "$ref": "#/components/parameters/CollectReferrer" }, { "$ref": "#/components/parameters/CollectMetadata" }, { "$ref": "#/components/parameters/CollectId" }, { "$ref": "#/components/parameters/CollectPageId" }, { "$ref": "#/components/parameters/CollectSessionId" }, { "$ref": "#/components/parameters/CollectOriginalId" }, { "$ref": "#/components/parameters/CollectDuration" }, { "$ref": "#/components/parameters/CollectScrolled" }, { "$ref": "#/components/parameters/CollectViewportWidth" }, { "$ref": "#/components/parameters/CollectViewportHeight" }, { "$ref": "#/components/parameters/CollectScreenWidth" }, { "$ref": "#/components/parameters/CollectScreenHeight" }, { "$ref": "#/components/parameters/CollectError" }, { "$ref": "#/components/parameters/CollectUa" }, { "$ref": "#/components/parameters/CollectTimezone" }, { "$ref": "#/components/parameters/CollectLanguage" }, { "$ref": "#/components/parameters/CollectOsName" }, { "$ref": "#/components/parameters/CollectOsVersion" }, { "$ref": "#/components/parameters/CollectBrands" }, { "$ref": "#/components/parameters/CollectVersion" }, { "$ref": "#/components/parameters/CollectHostnameOriginal" }, { "$ref": "#/components/parameters/CollectUnique" }, { "$ref": "#/components/parameters/CollectMobile" }, { "$ref": "#/components/parameters/CollectBot" }, { "$ref": "#/components/parameters/CollectBrave" }, { "$ref": "#/components/parameters/CollectDuck" }, { "$ref": "#/components/parameters/CollectHttps" }, { "$ref": "#/components/parameters/CollectCollectDnt" }, { "$ref": "#/components/parameters/CollectUtmSource" }, { "$ref": "#/components/parameters/CollectUtmMedium" }, { "$ref": "#/components/parameters/CollectUtmCampaign" }, { "$ref": "#/components/parameters/CollectUtmTerm" }, { "$ref": "#/components/parameters/CollectUtmContent" }, { "$ref": "#/components/parameters/Dnt" }, { "$ref": "#/components/parameters/XDoNotTrack" } ] }, "options": { "tags": [ "Collector" ], "operationId": "preflight_simple_gif", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/noscript.gif": { "get": { "tags": [ "Collector" ], "operationId": "collectNoscriptPixel", "summary": "Collect without JavaScript", "description": "Same payload and response as simple.gif. Derives missing hostname, path, https and query from the page URL in Referer. Explicit query parameters win even when empty. type defaults pageview. Referer does not supply the acquisition referrer field; browser policies can omit it or reduce it to an origin. No authentication; DNT and background-write semantics are the same as simple.gif.", "responses": { "200": { "$ref": "#/components/responses/PixelOk" }, "400": { "$ref": "#/components/responses/CollectorBadRequest" } }, "security": [], "parameters": [ { "$ref": "#/components/parameters/CollectHostname" }, { "$ref": "#/components/parameters/CollectType" }, { "$ref": "#/components/parameters/CollectEvent" }, { "$ref": "#/components/parameters/CollectPath" }, { "$ref": "#/components/parameters/CollectQuery" }, { "$ref": "#/components/parameters/CollectReferrer" }, { "$ref": "#/components/parameters/CollectMetadata" }, { "$ref": "#/components/parameters/CollectId" }, { "$ref": "#/components/parameters/CollectPageId" }, { "$ref": "#/components/parameters/CollectSessionId" }, { "$ref": "#/components/parameters/CollectOriginalId" }, { "$ref": "#/components/parameters/CollectDuration" }, { "$ref": "#/components/parameters/CollectScrolled" }, { "$ref": "#/components/parameters/CollectViewportWidth" }, { "$ref": "#/components/parameters/CollectViewportHeight" }, { "$ref": "#/components/parameters/CollectScreenWidth" }, { "$ref": "#/components/parameters/CollectScreenHeight" }, { "$ref": "#/components/parameters/CollectError" }, { "$ref": "#/components/parameters/CollectUa" }, { "$ref": "#/components/parameters/CollectTimezone" }, { "$ref": "#/components/parameters/CollectLanguage" }, { "$ref": "#/components/parameters/CollectOsName" }, { "$ref": "#/components/parameters/CollectOsVersion" }, { "$ref": "#/components/parameters/CollectBrands" }, { "$ref": "#/components/parameters/CollectVersion" }, { "$ref": "#/components/parameters/CollectHostnameOriginal" }, { "$ref": "#/components/parameters/CollectUnique" }, { "$ref": "#/components/parameters/CollectMobile" }, { "$ref": "#/components/parameters/CollectBot" }, { "$ref": "#/components/parameters/CollectBrave" }, { "$ref": "#/components/parameters/CollectDuck" }, { "$ref": "#/components/parameters/CollectHttps" }, { "$ref": "#/components/parameters/CollectCollectDnt" }, { "$ref": "#/components/parameters/CollectUtmSource" }, { "$ref": "#/components/parameters/CollectUtmMedium" }, { "$ref": "#/components/parameters/CollectUtmCampaign" }, { "$ref": "#/components/parameters/CollectUtmTerm" }, { "$ref": "#/components/parameters/CollectUtmContent" }, { "$ref": "#/components/parameters/Dnt" }, { "$ref": "#/components/parameters/XDoNotTrack" }, { "$ref": "#/components/parameters/Referer" } ] }, "options": { "tags": [ "Collector" ], "operationId": "preflight_noscript_gif", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/events": { "post": { "tags": [ "Collector" ], "operationId": "collectJson", "summary": "Collect one JSON payload", "description": "No authentication. Shares the exact same handler and body as the other POST collector route. Both default to pageview, so set type explicitly. For append rows use type append and an optional original_id referring to the original pageview; it is not validated and does not deduplicate. JSON parsing is required before DNT skipping. Writes run in the background; 200 is not durable confirmation. Unregistered hostnames normally drop, but a lookup failure can bypass the check. Bots can be stored but are excluded from reports. No client timestamp, country or IP override and no automatic retry/idempotency guarantee.", "responses": { "200": { "$ref": "#/components/responses/CollectorOk" }, "400": { "$ref": "#/components/responses/CollectorBadRequest" } }, "security": [], "parameters": [ { "$ref": "#/components/parameters/Dnt" }, { "$ref": "#/components/parameters/XDoNotTrack" } ], "requestBody": { "$ref": "#/components/requestBodies/Collector" } }, "options": { "tags": [ "Collector" ], "operationId": "preflight_events", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/append": { "post": { "tags": [ "Collector" ], "operationId": "collectAppend", "summary": "Collect a duration or scroll append", "description": "No authentication. Shares the exact same handler and body as the other POST collector route. Both default to pageview, so set type explicitly. For append rows use type append and an optional original_id referring to the original pageview; it is not validated and does not deduplicate. JSON parsing is required before DNT skipping. Writes run in the background; 200 is not durable confirmation. Unregistered hostnames normally drop, but a lookup failure can bypass the check. Bots can be stored but are excluded from reports. No client timestamp, country or IP override and no automatic retry/idempotency guarantee.", "responses": { "200": { "$ref": "#/components/responses/CollectorOk" }, "400": { "$ref": "#/components/responses/CollectorBadRequest" } }, "security": [], "parameters": [ { "$ref": "#/components/parameters/Dnt" }, { "$ref": "#/components/parameters/XDoNotTrack" } ], "requestBody": { "$ref": "#/components/requestBodies/Collector" } }, "options": { "tags": [ "Collector" ], "operationId": "preflight_append", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/healthz": { "get": { "tags": [ "Health" ], "operationId": "getHealth", "summary": "Check HTTP liveness", "description": "Returns ok without querying storage or the registry. Not a readiness or durability check. No collector CORS headers on this response.", "responses": { "200": { "description": "The HTTP handler responded.", "content": { "text/plain": { "schema": { "type": "string", "const": "ok" }, "example": "ok" } } } }, "security": [] }, "options": { "tags": [ "Health" ], "operationId": "preflight_healthz", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/api/import-sources": { "get": { "tags": [ "Imports" ], "operationId": "listImportSources", "summary": "List historical import sources", "description": "Requires any signed-in Totallytics account; no site target or owner check. Returns source metadata and configuration field definitions, never credentials. The only current source is simpleanalytics. Product API responses have no cross-origin CORS headers.", "responses": { "200": { "description": "Source definitions.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportSourcesResponse" }, "example": { "sources": [ { "id": "simpleanalytics", "label": "SimpleAnalytics", "description": "Import pageviews and events from a SimpleAnalytics export.", "configFields": [ { "key": "user_id", "label": "User ID", "type": "text", "required": true, "placeholder": "sa_user_id_…", "help": "SimpleAnalytics dashboard → Account → API." }, { "key": "api_key", "label": "API key", "type": "password", "required": true, "placeholder": "sa_api_key_…" }, { "key": "source_hostname", "label": "Source hostname", "type": "text", "required": true, "help": "The hostname as registered in SimpleAnalytics. Usually the same as this site." } ] } ] } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "FirebaseIdToken": [] } ] }, "options": { "tags": [ "Health" ], "operationId": "preflight_api_import_sources", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/api/sites/{hostname}/imports": { "parameters": [ { "$ref": "#/components/parameters/Hostname" } ], "get": { "tags": [ "Imports" ], "operationId": "listImports", "summary": "List recent site imports", "description": "Requires the site owner Firebase ID bearer token even when the site is public. Authentication is checked before site lookup. Returns at most 50 jobs ordered by created_at descending, across all statuses. No pagination, cursor, offset or limit parameters. Password config fields are never echoed.", "responses": { "200": { "description": "Latest jobs, or an empty array.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportsResponse" }, "example": { "imports": [ { "id": "746b4998-643d-44c0-848d-4d8fe4c6ebef", "site": "your-domain.example", "source": "simpleanalytics", "source_label": "SimpleAnalytics", "status": "queued", "range_start": "2026-08-01", "range_end": "2026-08-31", "chunks_total": 2, "chunks_done": 0, "rows_imported": 0, "rows_skipped": 0, "error": null, "config": { "user_id": "${SA_USER_ID}", "source_hostname": "your-domain.example" }, "created_at": "2026-09-18T12:00:00.000Z", "finished_at": null } ] } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "403": { "$ref": "#/components/responses/NotYourSite" }, "404": { "$ref": "#/components/responses/UnknownSite" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "FirebaseIdToken": [] } ] }, "post": { "tags": [ "Imports" ], "operationId": "createImport", "summary": "Create and queue a historical import", "description": "Requires the site owner Firebase ID bearer token even when the site is public. Authentication is checked before site lookup. Validates source credentials with a recent SimpleAnalytics export before creating the job; the request can take time. 201 means queued, not finished. At most 20 new jobs per owner in the rolling previous 24 hours across all sites and statuses, with one queued/running job per site. The planner rounds start down to its month boundary and creates pageview and event chunks through the inclusive end. New jobs do not deduplicate overlapping data, and no idempotency key is supported. Verify progress and actual reports before considering the migration complete. Do not automatically repeat POST after an ambiguous failure.", "responses": { "201": { "description": "Job created and queued. No historical data completion guarantee.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" }, "example": { "id": "746b4998-643d-44c0-848d-4d8fe4c6ebef", "site": "your-domain.example", "source": "simpleanalytics", "source_label": "SimpleAnalytics", "status": "queued", "range_start": "2026-08-01", "range_end": "2026-08-31", "chunks_total": 2, "chunks_done": 0, "rows_imported": 0, "rows_skipped": 0, "error": null, "config": { "user_id": "${SA_USER_ID}", "source_hostname": "your-domain.example" }, "created_at": "2026-09-18T12:00:00.000Z", "finished_at": null } } } }, "400": { "description": "Date, source or source-configuration validation failed. Provider validation can return upstream error text.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "range": { "value": { "error": "invalid date range" } }, "source": { "value": { "error": "unknown import source" } }, "userId": { "value": { "error": "User ID is required" } }, "apiKey": { "value": { "error": "API key is required" } }, "hostnameRequired": { "value": { "error": "Source hostname is required" } }, "hostname": { "value": { "error": "Source hostname is invalid" } } } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "403": { "$ref": "#/components/responses/NotYourSite" }, "404": { "$ref": "#/components/responses/UnknownSite" }, "500": { "$ref": "#/components/responses/InternalError" }, "409": { "description": "Another queued or running job already exists for this site.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "active": { "value": { "error": "an import is already running for this site" } } } } } }, "429": { "description": "Owner has already created at least 20 jobs in the rolling previous 24 hours, across all sites and statuses. Same-job retry is not a new creation.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limit": { "value": { "error": "too many imports today, try again tomorrow" } } } } } }, "502": { "description": "Queue submission failed after job creation. The handler cancels the new job; inspect the site job list before another action.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "queue": { "value": { "error": "import queue unavailable, please try again" } } } } } } }, "security": [ { "FirebaseIdToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImport" }, "example": { "source": "simpleanalytics", "config": { "user_id": "${SA_USER_ID}", "api_key": "${SA_API_KEY}", "source_hostname": "your-domain.example" }, "start": "2026-08-01", "end": "2026-08-31" } } } } }, "options": { "tags": [ "Health" ], "operationId": "preflight_api_sites_hostname_imports", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/api/sites/{hostname}/imports/{jobId}": { "parameters": [ { "$ref": "#/components/parameters/Hostname" }, { "$ref": "#/components/parameters/ImportJobId" } ], "get": { "tags": [ "Imports" ], "operationId": "getImport", "summary": "Read import state and progress", "description": "Requires the site owner Firebase ID bearer token even when the site is public. Authentication is checked before site lookup. Returns the job directly, not wrapped. Progress counters are checkpointed only after an entire chunk; records can already be written before counters advance. Verify progress and actual reports before considering the migration complete.", "responses": { "200": { "description": "Current job snapshot.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" }, "example": { "id": "746b4998-643d-44c0-848d-4d8fe4c6ebef", "site": "your-domain.example", "source": "simpleanalytics", "source_label": "SimpleAnalytics", "status": "queued", "range_start": "2026-08-01", "range_end": "2026-08-31", "chunks_total": 2, "chunks_done": 0, "rows_imported": 0, "rows_skipped": 0, "error": null, "config": { "user_id": "${SA_USER_ID}", "source_hostname": "your-domain.example" }, "created_at": "2026-09-18T12:00:00.000Z", "finished_at": null } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "403": { "$ref": "#/components/responses/NotYourSite" }, "404": { "$ref": "#/components/responses/UnknownImport" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "FirebaseIdToken": [] } ] }, "options": { "tags": [ "Health" ], "operationId": "preflight_api_sites_hostname_imports_jobId", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/api/sites/{hostname}/imports/{jobId}/cancel": { "parameters": [ { "$ref": "#/components/parameters/Hostname" }, { "$ref": "#/components/parameters/ImportJobId" } ], "post": { "tags": [ "Imports" ], "operationId": "cancelImport", "summary": "Cancel an active import", "description": "Requires the site owner Firebase ID bearer token even when the site is public. Authentication is checked before site lookup. No request body. Only queued/running jobs may be canceled. Stops later queued work, not an in-flight export or write, and does not roll back rows already written. Stored source configuration is retained for retry. The response uses the prior job snapshot with status set to canceled, so finished_at can be stale; poll GET for persisted state.", "responses": { "200": { "description": "Cancellation recorded; in-flight work may still write rows.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" }, "example": { "id": "746b4998-643d-44c0-848d-4d8fe4c6ebef", "site": "your-domain.example", "source": "simpleanalytics", "source_label": "SimpleAnalytics", "status": "canceled", "range_start": "2026-08-01", "range_end": "2026-08-31", "chunks_total": 2, "chunks_done": 0, "rows_imported": 0, "rows_skipped": 0, "error": null, "config": { "user_id": "${SA_USER_ID}", "source_hostname": "your-domain.example" }, "created_at": "2026-09-18T12:00:00.000Z", "finished_at": null } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "403": { "$ref": "#/components/responses/NotYourSite" }, "404": { "$ref": "#/components/responses/UnknownImport" }, "500": { "$ref": "#/components/responses/InternalError" }, "409": { "description": "Job is not queued or running.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "state": { "value": { "error": "import is not active" } } } } } } }, "security": [ { "FirebaseIdToken": [] } ] }, "options": { "tags": [ "Health" ], "operationId": "preflight_api_sites_hostname_imports_jobId_cancel", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } }, "/api/sites/{hostname}/imports/{jobId}/retry": { "parameters": [ { "$ref": "#/components/parameters/Hostname" }, { "$ref": "#/components/parameters/ImportJobId" } ], "post": { "tags": [ "Imports" ], "operationId": "retryImport", "summary": "Resume a failed or canceled import", "description": "Requires the site owner Firebase ID bearer token even when the site is public. Authentication is checked before site lookup. No request body; credentials and dates cannot be replaced. Only failed/canceled jobs may be retried, not completed jobs. Resumes the same job from chunks_done with existing counters and config; checkpointed chunks are skipped, but partial-chunk writes and ambiguous insert retries may duplicate rows. Not idempotent or exactly-once. The creation-rate cap is not reapplied. Queue submission failure can return 500 after status was changed to queued. Another active job on the site can also produce 500 from the unique constraint. The response uses the prior snapshot with status queued and error null; finished_at can be stale. Poll GET before further actions.", "responses": { "200": { "description": "Same job re-queued, not import finished.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" }, "example": { "id": "746b4998-643d-44c0-848d-4d8fe4c6ebef", "site": "your-domain.example", "source": "simpleanalytics", "source_label": "SimpleAnalytics", "status": "queued", "range_start": "2026-08-01", "range_end": "2026-08-31", "chunks_total": 2, "chunks_done": 0, "rows_imported": 0, "rows_skipped": 0, "error": null, "config": { "user_id": "${SA_USER_ID}", "source_hostname": "your-domain.example" }, "created_at": "2026-09-18T12:00:00.000Z", "finished_at": "2026-09-18T12:01:00.000Z" } } } }, "401": { "$ref": "#/components/responses/SignInRequired" }, "403": { "$ref": "#/components/responses/NotYourSite" }, "404": { "$ref": "#/components/responses/UnknownImport" }, "500": { "description": "Queue submission can fail after the job is changed to queued; an existing active job can also reject retry. Inspect persisted state before another action.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "value": { "error": "internal error" } } } } } }, "409": { "description": "Job is neither failed nor canceled.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "state": { "value": { "error": "only failed or canceled imports can be retried" } } } } } } }, "security": [ { "FirebaseIdToken": [] } ] }, "options": { "tags": [ "Health" ], "operationId": "preflight_api_sites_hostname_imports_jobId_retry", "summary": "Handle a preflight request", "description": "The global OPTIONS handler responds independently of route authorization. Advertised methods are GET, POST, OPTIONS and the only allowed request header is Content-Type. This does not enable authenticated cross-origin product API calls; actual product API and health responses have no CORS headers.", "responses": { "204": { "$ref": "#/components/responses/Preflight" } }, "security": [] } } }, "components": { "securitySchemes": { "FirebaseIdToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Current Firebase ID token for an Totallytics user, sent as Authorization: Bearer . Not an API key, Firebase custom token, OAuth provider access token or session cookie. Obtain a current token from the authentication guide." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message." } }, "required": [ "error" ], "additionalProperties": false }, "Site": { "type": "object", "properties": { "hostname": { "type": "string", "description": "Registered hostname." }, "display_name": { "type": "string", "description": "Display name; initially empty." }, "is_public": { "type": "boolean", "description": "Allows anonymous site metadata and stats reads." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp.", "format": "date-time" } }, "required": [ "hostname", "display_name", "is_public", "created_at" ], "additionalProperties": false }, "OwnedSite": { "type": "object", "properties": { "hostname": { "type": "string", "description": "Registered hostname." }, "display_name": { "type": "string", "description": "Display name; initially empty." }, "is_public": { "type": "boolean", "description": "Allows anonymous site metadata and stats reads." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp.", "format": "date-time" }, "owner_uid": { "type": "string", "description": "Owner Firebase user ID; returned only by the authenticated list." } }, "required": [ "hostname", "display_name", "is_public", "created_at", "owner_uid" ], "additionalProperties": false }, "SitesResponse": { "type": "object", "properties": { "sites": { "type": "array", "items": { "$ref": "#/components/schemas/OwnedSite" }, "description": "All owned sites, ordered by creation time. No pagination." } }, "required": [ "sites" ], "additionalProperties": false }, "CreateSite": { "type": "object", "required": [ "hostname" ], "properties": { "hostname": { "type": "string", "description": "Trimmed and lowercased before validation. Normalized value is at most 253 characters and matches ^(?!-)[a-z0-9-]{1,63}(? API. Trimmed and truncated to 512 characters.", "minLength": 1 }, "api_key": { "type": "string", "description": "SimpleAnalytics API key, not an Totallytics bearer token. Trimmed and truncated to 512 characters. Never echoed in job config; removed from stored config on completion but retained for failed/canceled retries.", "minLength": 1, "writeOnly": true }, "source_hostname": { "type": "string", "description": "Source hostname registered in SimpleAnalytics; may differ from the destination site. Trimmed, truncated to 512 characters and lowercased. Must match ^(?!-)[a-z0-9-]{1,63}(?