{"openapi":"3.1.0","info":{"title":"Tinylytics API","version":"v1","description":"Machine-readable schema for Tinylytics API v1."},"servers":[{"url":"https://tinylytics.app/api/v1"}],"paths":{"/":{"get":{"summary":"API discovery metadata","description":"Public discovery endpoint with authentication details, docs links, and endpoint directory.","operationId":"getApiDiscovery","tags":["Discovery"],"responses":{"200":{"description":"Successful response."}},"security":[]}},"/me":{"get":{"summary":"Get current user","description":"Validate API key and return current account plus API key metadata.","operationId":"getCurrentUser","tags":["Account"],"responses":{"200":{"description":"Successful response."}},"security":[{"bearerAuth":[]}]}},"/openapi.json":{"get":{"summary":"OpenAPI schema","description":"OpenAPI 3.1 schema for Tinylytics API v1.","operationId":"getOpenApiSchema","tags":["Discovery"],"responses":{"200":{"description":"Successful response."}},"security":[]}},"/sites":{"get":{"summary":"List sites","description":"List sites available to the current authenticated user.","operationId":"listSites","tags":["Sites"],"responses":{"200":{"description":"Successful response."}},"security":[{"bearerAuth":[]}]}},"/sites/:id":{"get":{"summary":"Get site","description":"Fetch one site by numeric ID.","operationId":"getSite","tags":["Sites"],"responses":{"200":{"description":"Successful response."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/sites/:id/content":{"get":{"summary":"Get content monitoring","description":"Return content monitoring status, issues, and stats for a site. Requires an active subscription.","operationId":"getSiteContentMonitoring","tags":["Monitoring"],"responses":{"200":{"description":"Successful response."},"403":{"description":"This endpoint requires an active subscription."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/sites/:id/events":{"post":{"summary":"Create event","description":"Create one event for a site. Requires a full-access API key.","operationId":"createSiteEvent","tags":["Analytics"],"responses":{"201":{"description":"Event created."},"202":{"description":"Event accepted but ignored by rules."},"422":{"description":"Validation or payload error."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event"],"properties":{"event":{"type":"string"},"value":{"type":"string"},"path":{"type":"string"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"ip_address":{"type":"string"},"url":{"type":"string"},"referrer":{"type":"string"},"user_agent":{"type":"string"},"visitor_id":{"type":"string"},"source":{"type":"string"}}}}}}}},"/sites/:id/events/batch":{"post":{"summary":"Batch create events","description":"Create many events in one request. Requires a full-access API key.","operationId":"createSiteEventsBatch","tags":["Analytics"],"responses":{"200":{"description":"Batch processed with per-row statuses."},"422":{"description":"Payload must be a JSON array."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["event"],"properties":{"event":{"type":"string"},"value":{"type":"string"},"path":{"type":"string"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"ip_address":{"type":"string"},"url":{"type":"string"},"referrer":{"type":"string"},"user_agent":{"type":"string"},"visitor_id":{"type":"string"},"source":{"type":"string"}}}}}}}}},"/sites/:id/hits":{"get":{"summary":"List hits","description":"Read raw or grouped analytics hits for a site.","operationId":"listSiteHits","tags":["Analytics"],"responses":{"200":{"description":"Successful response."},"400":{"description":"Invalid parameter value or date format."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"start_date","in":"query","required":false,"description":"Range start date (`YYYY-MM-DD`).","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"Range end date (`YYYY-MM-DD`).","schema":{"type":"string"}},{"name":"time_zone","in":"query","required":false,"description":"Date-boundary mode.","schema":{"type":"string","enum":["utc","user"]}},{"name":"country","in":"query","required":false,"description":"Exact 2-letter country code.","schema":{"type":"string"}},{"name":"path","in":"query","required":false,"description":"Exact path filter.","schema":{"type":"string"}},{"name":"referrer","in":"query","required":false,"description":"Case-insensitive partial referrer filter.","schema":{"type":"string"}},{"name":"grouped","in":"query","required":false,"description":"Return grouped results when true.","schema":{"type":"boolean"}},{"name":"group_by","in":"query","required":false,"description":"Grouping field for grouped results.","schema":{"type":"string","enum":["path","country","referrer","browser_name","platform_name","source"]}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":1000}}]},"post":{"summary":"Create hit","description":"Create one hit for a site. Requires a full-access API key.","operationId":"createSiteHit","tags":["Analytics"],"responses":{"201":{"description":"Hit created."},"202":{"description":"Hit accepted but ignored by rules."},"422":{"description":"Validation or payload error."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path"],"properties":{"path":{"type":"string"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"ip_address":{"type":"string"},"url":{"type":"string"},"referrer":{"type":"string"},"user_agent":{"type":"string"},"visitor_id":{"type":"string"},"source":{"type":"string"}}}}}}}},"/sites/:id/hits/batch":{"post":{"summary":"Batch create hits","description":"Create many hits in one request. Requires a full-access API key.","operationId":"createSiteHitsBatch","tags":["Analytics"],"responses":{"200":{"description":"Batch processed with per-row statuses."},"422":{"description":"Payload must be a JSON array."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["path"],"properties":{"path":{"type":"string"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"ip_address":{"type":"string"},"url":{"type":"string"},"referrer":{"type":"string"},"user_agent":{"type":"string"},"visitor_id":{"type":"string"},"source":{"type":"string"}}}}}}}}},"/sites/:id/insights":{"get":{"summary":"Get insights","description":"Return AI insights generated for a site. Requires an active subscription.","operationId":"getSiteInsights","tags":["Insights"],"responses":{"200":{"description":"Successful response."},"403":{"description":"This endpoint requires an active subscription."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/sites/:id/kudos":{"get":{"summary":"List kudos","description":"Read kudos records for a site.","operationId":"listSiteKudos","tags":["Analytics"],"responses":{"200":{"description":"Successful response."},"400":{"description":"Invalid parameter value or date format."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"start_date","in":"query","required":false,"description":"Range start date (`YYYY-MM-DD`).","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"Range end date (`YYYY-MM-DD`).","schema":{"type":"string"}},{"name":"time_zone","in":"query","required":false,"description":"Date-boundary mode.","schema":{"type":"string","enum":["utc","user"]}},{"name":"path","in":"query","required":false,"description":"Exact path filter.","schema":{"type":"string"}},{"name":"uid","in":"query","required":false,"description":"Exact kudo UID filter.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":1000}}]},"post":{"summary":"Create kudo","description":"Create one kudo for a site. Requires a full-access API key.","operationId":"createSiteKudo","tags":["Analytics"],"responses":{"201":{"description":"Kudo created."},"202":{"description":"Kudo accepted but ignored by rules."},"422":{"description":"Validation or payload error."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path"],"properties":{"path":{"type":"string"},"custom_uid":{"type":"string"}}}}}}}},"/sites/:id/kudos/:kudo_uid":{"delete":{"summary":"Delete kudo","description":"Delete one kudo by UID. Requires a full-access API key.","operationId":"deleteSiteKudo","tags":["Analytics"],"responses":{"200":{"description":"Kudo deleted."},"404":{"description":"Kudo not found."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"kudo_uid","in":"path","required":true,"schema":{"type":"string"}}]}},"/sites/:id/leaderboard":{"get":{"summary":"Get leaderboard","description":"Return all-time path leaderboard for a site.","operationId":"getSiteLeaderboard","tags":["Analytics"],"responses":{"200":{"description":"Successful response."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/sites/:id/signals":{"get":{"summary":"List signals","description":"Return owner-submitted context signals for a site. Requires an active subscription and insights enabled.","operationId":"listSiteSignals","tags":["Insights"],"responses":{"200":{"description":"Successful response."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]},"post":{"summary":"Create signal","description":"Submit one owner context signal for a site. Requires a full-access API key, subscription, and insights enabled.","operationId":"createSiteSignal","tags":["Insights"],"responses":{"200":{"description":"Successful response."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/sites/:id/uptime":{"get":{"summary":"Get uptime","description":"Return uptime, SSL/domain status, and downtime history for a site. Requires an active subscription.","operationId":"getSiteUptime","tags":["Monitoring"],"responses":{"200":{"description":"Successful response."},"403":{"description":"This endpoint requires an active subscription."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/sites/:id/user_journeys":{"get":{"summary":"Get user journeys","description":"Return visitor journey analytics for a site.","operationId":"getSiteUserJourneys","tags":["Analytics"],"responses":{"200":{"description":"Successful response."},"400":{"description":"Invalid parameter value or date format."}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"start_date","in":"query","required":false,"description":"Range start date (`YYYY-MM-DD`).","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"Range end date (`YYYY-MM-DD`).","schema":{"type":"string"}},{"name":"time_zone","in":"query","required":false,"description":"Date-boundary mode.","schema":{"type":"string","enum":["utc","user"]}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":50}}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}}}}