{"openapi":"3.1.0","info":{"title":"Evumi Stats & Sites API","version":"0.1.15","description":"Team-scoped Bearer API for server-side scripts. MCP uses separate OAuth authorization. This reference documents implemented endpoints and does not promise complete Plausible compatibility."},"servers":[{"url":"/"}],"paths":{"/api/v2/query":{"post":{"operationId":"post_api_v2_query","tags":["Statistics"],"summary":"Query analytics","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions.","content":{"application/json":{"schema":{"type":"object","required":["results","query","meta"],"properties":{"results":{"type":"array","items":{"type":"object","required":["dimensions","metrics"],"properties":{"dimensions":{"type":"array","items":{"type":["string","number","null"]}},"metrics":{"type":"array","items":{"type":["number","null"]}}}}},"query":{"type":"object","description":"Normalized query, including requested metrics and dimensions"},"meta":{"type":"object","description":"Coverage, imported-history warnings, pagination and optional time labels"}}},"example":{"results":[{"dimensions":[],"metrics":[12,15,28]}],"query":{"site_id":"example.com","metrics":["visitors","visits","pageviews"],"date_range":"day","dimensions":[]},"meta":{}}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsQuery"},"examples":{"today_overview":{"summary":"Today overview","value":{"site_id":"example.com","metrics":["visitors","visits","pageviews"],"date_range":"day"}},"countries":{"summary":"Countries","value":{"site_id":"example.com","metrics":["visitors","pageviews"],"date_range":"7d","dimensions":["visit:country"],"include":{"imports":true,"total_rows":true},"pagination":{"limit":50,"offset":0}}},"app_os_and_version":{"summary":"App, OS and version","value":{"site_id":"example.com","metrics":["visitors"],"date_range":"day","dimensions":["visit:browser","visit:browser_version","visit:os"],"pagination":{"limit":100,"offset":0}}},"events_and_properties":{"summary":"Events and properties","value":{"site_id":"example.com","metrics":["events","visitors"],"date_range":"day","dimensions":["event:name","event:props:plan"],"filters":[["is","event:name",["Signup"]]],"pagination":{"limit":100,"offset":0}}},"hourly_trend":{"summary":"Hourly trend","value":{"site_id":"example.com","metrics":["visitors","pageviews"],"date_range":"day","dimensions":["time:hour"],"include":{"time_labels":true},"order_by":[["time:hour","asc"]]}}}}}}}},"/api/v1/stats/realtime/visitors":{"get":{"operationId":"get_api_v1_stats_realtime_visitors","tags":["Statistics"],"summary":"Realtime visitors","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"site_id","required":true,"description":"Site domain","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/api/v1/stats/aggregate":{"get":{"operationId":"get_api_v1_stats_aggregate","tags":["Statistics"],"summary":"Aggregate metrics","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"site_id","required":true,"description":"Site domain","schema":{"type":"string"}},{"in":"query","name":"period","required":false,"description":"day/7d/30d/month/6mo/12mo/custom","schema":{"type":"string"}},{"in":"query","name":"date","required":false,"description":"YYYY-MM-DD; for custom use start_date,end_date","schema":{"type":"string"}},{"in":"query","name":"metrics","required":false,"description":"Comma-separated metrics; defaults to visitors","schema":{"type":"string"}},{"in":"query","name":"filters","required":false,"description":"v1 filter syntax, for example visit:country==CN","schema":{"type":"string"}},{"in":"query","name":"with_imported","required":false,"description":"true includes compatible imported history","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/api/v1/stats/timeseries":{"get":{"operationId":"get_api_v1_stats_timeseries","tags":["Statistics"],"summary":"Time series","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"site_id","required":true,"description":"Site domain","schema":{"type":"string"}},{"in":"query","name":"period","required":false,"description":"day/7d/30d/month/6mo/12mo/custom","schema":{"type":"string"}},{"in":"query","name":"date","required":false,"description":"YYYY-MM-DD; for custom use start_date,end_date","schema":{"type":"string"}},{"in":"query","name":"metrics","required":false,"description":"Comma-separated metrics; defaults to visitors","schema":{"type":"string"}},{"in":"query","name":"filters","required":false,"description":"v1 filter syntax, for example visit:country==CN","schema":{"type":"string"}},{"in":"query","name":"with_imported","required":false,"description":"true includes compatible imported history","schema":{"type":"string"}},{"in":"query","name":"interval","required":false,"description":"hour/date/month","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/api/v1/stats/breakdown":{"get":{"operationId":"get_api_v1_stats_breakdown","tags":["Statistics"],"summary":"Dimension breakdown","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"site_id","required":true,"description":"Site domain","schema":{"type":"string"}},{"in":"query","name":"period","required":false,"description":"day/7d/30d/month/6mo/12mo/custom","schema":{"type":"string"}},{"in":"query","name":"date","required":false,"description":"YYYY-MM-DD; for custom use start_date,end_date","schema":{"type":"string"}},{"in":"query","name":"metrics","required":false,"description":"Comma-separated metrics; defaults to visitors","schema":{"type":"string"}},{"in":"query","name":"filters","required":false,"description":"v1 filter syntax, for example visit:country==CN","schema":{"type":"string"}},{"in":"query","name":"with_imported","required":false,"description":"true includes compatible imported history","schema":{"type":"string"}},{"in":"query","name":"property","required":true,"description":"For example, visit:browser","schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"description":"","schema":{"type":"string"}},{"in":"query","name":"page","required":false,"description":"","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/api/v1/sites":{"get":{"operationId":"get_api_v1_sites","tags":["Sites"],"summary":"List authorized sites","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"in":"query","name":"after","required":false,"description":"Use meta.after from the response. Do not combine with before.","schema":{"type":"string"}},{"in":"query","name":"before","required":false,"description":"Use meta.before from the response. Do not combine with after.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}},"post":{"operationId":"post_api_v1_sites","tags":["Sites"],"summary":"Create site","description":"Permission: Sites · Team-wide. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"timezone":{"type":"string","example":"Asia/Shanghai"}},"required":["domain"],"additionalProperties":false}}}}}},"/api/v1/sites/teams":{"get":{"operationId":"get_api_v1_sites_teams","tags":["Sites"],"summary":"List key team","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"in":"query","name":"after","required":false,"description":"Use meta.after from the response. Do not combine with before.","schema":{"type":"string"}},{"in":"query","name":"before","required":false,"description":"Use meta.before from the response. Do not combine with after.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/api/v1/sites/{site_id}":{"get":{"operationId":"get_api_v1_sites_site_id_","tags":["Sites"],"summary":"Get site","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"site_id","required":true,"schema":{"type":"string"},"description":"URL-encoded site domain"}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}},"put":{"operationId":"put_api_v1_sites_site_id_","tags":["Sites"],"summary":"Update site","description":"Permission: Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"site_id","required":true,"schema":{"type":"string"},"description":"URL-encoded site domain"}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"timezone":{"type":"string","example":"Asia/Shanghai"}},"required":[],"additionalProperties":false}}}}}},"/api/v1/sites/goals":{"get":{"operationId":"get_api_v1_sites_goals","tags":["Sites"],"summary":"List goals","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"site_id","required":true,"description":"Site domain","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"in":"query","name":"after","required":false,"description":"Use meta.after from the response. Do not combine with before.","schema":{"type":"string"}},{"in":"query","name":"before","required":false,"description":"Use meta.before from the response. Do not combine with after.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}},"put":{"operationId":"put_api_v1_sites_goals","tags":["Sites"],"summary":"Create goal idempotently","description":"Permission: Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"site_id":{"type":"string"},"goal_type":{"enum":["event","page"]},"event_name":{"type":"string"},"page_path":{"type":"string"},"display_name":{"type":"string"},"custom_props":{"type":"object","additionalProperties":{"type":"string"}}},"required":["site_id","goal_type"],"additionalProperties":false}}}}}},"/api/v1/sites/goals/{goal_id}":{"delete":{"operationId":"delete_api_v1_sites_goals_goal_id_","tags":["Sites"],"summary":"Delete goal","description":"Permission: Sites · Owner. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"goal_id","required":true,"schema":{"type":"string"},"description":"URL-encoded resource identifier"},{"in":"query","name":"site_id","required":true,"description":"Site domain","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/api/v1/sites/custom-props":{"get":{"operationId":"get_api_v1_sites_custom_props","tags":["Sites"],"summary":"List properties","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"site_id","required":true,"description":"Site domain","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"in":"query","name":"after","required":false,"description":"Use meta.after from the response. Do not combine with before.","schema":{"type":"string"}},{"in":"query","name":"before","required":false,"description":"Use meta.before from the response. Do not combine with after.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}},"put":{"operationId":"put_api_v1_sites_custom_props","tags":["Sites"],"summary":"Enable property","description":"Permission: Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"site_id":{"type":"string"},"property":{"type":"string"}},"required":["site_id","property"],"additionalProperties":false}}}}}},"/api/v1/sites/custom-props/{property}":{"delete":{"operationId":"delete_api_v1_sites_custom_props_property_","tags":["Sites"],"summary":"Hide property, retain historical values","description":"Permission: Sites · Owner. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"property","required":true,"schema":{"type":"string"},"description":"URL-encoded resource identifier"},{"in":"query","name":"site_id","required":true,"description":"Site domain","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/api/v1/sites/guests":{"get":{"operationId":"get_api_v1_sites_guests","tags":["Sites"],"summary":"List accepted site guests","description":"Permission: Stats / Sites. Up to 600 requests per key per hour.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"site_id","required":true,"description":"Site domain","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"in":"query","name":"after","required":false,"description":"Use meta.after from the response. Do not combine with before.","schema":{"type":"string"}},{"in":"query","name":"before","required":false,"description":"Use meta.before from the response. Do not combine with after.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. v2 array order matches the requested metrics and dimensions."},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient permission"},"404":{"description":"Site outside authorized scope"},"429":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer evumi_…"}},"schemas":{"StatsQuery":{"type":"object","required":["site_id","metrics","date_range"],"properties":{"site_id":{"type":"string","description":"Site domain, not a teamId or site UUID"},"metrics":{"type":"array","minItems":1,"uniqueItems":true,"items":{"enum":["visitors","visits","pageviews","events","bounce_rate","visit_duration","views_per_visit","percentage","conversion_rate","group_conversion_rate","scroll_depth","time_on_page","total_revenue","average_revenue"]},"description":"Revenue metrics currently return null. Time on page is also null when unavailable."},"date_range":{"oneOf":[{"enum":["day","24h","7d","28d","30d","91d","month","6mo","12mo","year","all"]},{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}],"description":"Uses the site timezone. day is today so far; 7d and similar ranges exclude today. Custom date ranges include both endpoints."},"dimensions":{"type":"array","maxItems":9,"items":{"anyOf":[{"enum":["event:page","event:hostname","event:goal","event:name","visit:entry_page","visit:entry_page_hostname","visit:exit_page","visit:exit_page_hostname","visit:source","visit:referrer","visit:channel","visit:utm_source","visit:utm_medium","visit:utm_campaign","visit:utm_content","visit:utm_term","visit:device","visit:browser","visit:browser_version","visit:os","visit:os_version","visit:country","visit:region","visit:city","visit:country_name","visit:region_name","visit:city_name","time","time:minute","time:hour","time:day","time:week","time:month"]},{"type":"string","pattern":"^event:props:.+"}]}},"filters":{"type":"array","items":{"type":"array"},"description":"Leaf: [is|is_not|contains|contains_not|matches|matches_not, dimension, [values]]. and/or take a child-node array; not/has_done/has_not_done take one node. Maximum 100 nodes and 8 levels."},"order_by":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string"},{"enum":["asc","desc"]}],"minItems":2,"maxItems":2}},"include":{"type":"object","properties":{"imports":{"type":"boolean","default":false},"time_labels":{"type":"boolean"},"total_rows":{"type":"boolean"}},"additionalProperties":false},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":10000,"default":10000},"offset":{"type":"integer","minimum":0,"maximum":1000000,"default":0}},"additionalProperties":false}}}}}}