{"openapi":"3.1.0","info":{"title":"Umami (BYOK) API","version":"0.1.0","description":"Umami (BYOK) lets an AI assistant read your own Umami data through the Umami API with a key you supply (Umami Cloud API key). Read-only: 6 tools (get_me, list_websites, get_website_stats, get_website_pageviews, get_website_metrics, get_active_visitors). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-umami.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-umami/docs"},"termsOfService":"https://connectorbay.com/byok-umami/terms"},"servers":[{"url":"https://byok-umami.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-umami/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_me":{"post":{"operationId":"get_me","summary":"Show who the key belongs to: Umami username, role and the name of the API key. Use for \"Which Umami account is my API ke","description":"Show who the key belongs to: Umami username, role and the name of the API key. Use for \"Which Umami account is my API key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_meArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_websites":{"post":{"operationId":"list_websites","summary":"List the tracked websites with ID, name, domain and creation date. Filter by search text; page with page and page_size. ","description":"List the tracked websites with ID, name, domain and creation date. Filter by search text; page with page and page_size. Use for \"Which websites do I track in Umami\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text used to filter the websites.","title":"Search"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many websites per page (1 to 100).","title":"Page Size"},"include_teams":{"anyOf":[{"const":"true","type":"string"},{"type":"null"}],"default":null,"description":"Set to true to include websites reachable through teams you own or manage.","title":"Include Teams"}},"title":"list_websitesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_website_stats":{"post":{"operationId":"get_website_stats","summary":"Get a website's totals for a period: pageviews, unique visitors, visits, bounces and total time, optionally compared wit","description":"Get a website's totals for a period: pageviews, unique visitors, visits, bounces and total time, optionally compared with the previous period or year, and filtered by page, referrer, country, device or UTM. Use for \"How many visitors did my Umami website get last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"ID of the website (from list_websites), a UUID.","maxLength":200,"title":"Website Id","type":"string"},"start_at":{"description":"Start of the period as a Unix timestamp in milliseconds, for example 1767225600000.","minimum":0,"title":"Start At","type":"integer"},"end_at":{"description":"End of the period as a Unix timestamp in milliseconds, for example 1769904000000.","minimum":0,"title":"End At","type":"integer"},"compare":{"anyOf":[{"enum":["prev","yoy"],"type":"string"},{"type":"null"}],"default":null,"description":"Add a comparison period: prev (previous period) or yoy (same period last year).","title":"Compare"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA time zone for grouping, for example 'America/New_York'.","title":"Timezone"},"path":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only activity on this URL path.","title":"Path"},"referrer":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only visits from this referring URL.","title":"Referrer"},"country":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors from this country code, for example 'US'.","title":"Country"},"browser":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this browser.","title":"Browser"},"os":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this operating system.","title":"Os"},"device":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this device category.","title":"Device"},"event":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this custom event name.","title":"Event"},"utm_source":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this UTM source.","title":"Utm Source"},"utm_campaign":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this UTM campaign.","title":"Utm Campaign"}},"required":["website_id","start_at","end_at"],"title":"get_website_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_website_pageviews":{"post":{"operationId":"get_website_pageviews","summary":"Get a website's pageviews and sessions as a time series (points with x time and y count) for a period, grouped by minute","description":"Get a website's pageviews and sessions as a time series (points with x time and y count) for a period, grouped by minute, hour, day, month or year, optionally with a comparison period. Use for \"Show my Umami pageviews per day last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"ID of the website (from list_websites), a UUID.","maxLength":200,"title":"Website Id","type":"string"},"start_at":{"description":"Start of the period as a Unix timestamp in milliseconds, for example 1767225600000.","minimum":0,"title":"Start At","type":"integer"},"end_at":{"description":"End of the period as a Unix timestamp in milliseconds, for example 1769904000000.","minimum":0,"title":"End At","type":"integer"},"unit":{"anyOf":[{"enum":["minute","hour","day","month","year"],"type":"string"},{"type":"null"}],"default":"day","description":"Grouping interval: minute, hour, day, month or year.","title":"Unit"},"compare":{"anyOf":[{"enum":["prev","yoy"],"type":"string"},{"type":"null"}],"default":null,"description":"Add a comparison period: prev (previous period) or yoy (same period last year).","title":"Compare"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA time zone for grouping, for example 'America/New_York'.","title":"Timezone"},"path":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only activity on this URL path.","title":"Path"},"referrer":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only visits from this referring URL.","title":"Referrer"},"country":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors from this country code, for example 'US'.","title":"Country"},"browser":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this browser.","title":"Browser"},"os":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this operating system.","title":"Os"},"device":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this device category.","title":"Device"},"event":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this custom event name.","title":"Event"},"utm_source":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this UTM source.","title":"Utm Source"},"utm_campaign":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this UTM campaign.","title":"Utm Campaign"}},"required":["website_id","start_at","end_at"],"title":"get_website_pageviewsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_website_metrics":{"post":{"operationId":"get_website_metrics","summary":"Get the most frequent values of one dimension for a period, such as top pages (path), referrers, countries, browsers, de","description":"Get the most frequent values of one dimension for a period, such as top pages (path), referrers, countries, browsers, devices or events, each with a count (y) of views or unique visitors. Use for \"What are my top Umami pages this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"ID of the website (from list_websites), a UUID.","maxLength":200,"title":"Website Id","type":"string"},"start_at":{"description":"Start of the period as a Unix timestamp in milliseconds, for example 1767225600000.","minimum":0,"title":"Start At","type":"integer"},"end_at":{"description":"End of the period as a Unix timestamp in milliseconds, for example 1769904000000.","minimum":0,"title":"End At","type":"integer"},"type":{"description":"Dimension to rank: path, entry, exit, title, query, hostname, referrer, domain, channel, event, tag, browser, os, device, screen, language, country, region, city, distinctId, utmSource, utmMedium, utmCampaign, utmContent or utmTerm.","enum":["path","entry","exit","title","query","hostname","referrer","domain","channel","event","tag","browser","os","device","screen","language","country","region","city","distinctId","utmSource","utmMedium","utmCampaign","utmContent","utmTerm"],"title":"Type","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many rows to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of rows to skip.","title":"Offset"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA time zone for grouping, for example 'America/New_York'.","title":"Timezone"},"path":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only activity on this URL path.","title":"Path"},"referrer":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only visits from this referring URL.","title":"Referrer"},"country":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors from this country code, for example 'US'.","title":"Country"},"browser":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this browser.","title":"Browser"},"os":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this operating system.","title":"Os"},"device":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this device category.","title":"Device"},"event":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this custom event name.","title":"Event"},"utm_source":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this UTM source.","title":"Utm Source"},"utm_campaign":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this UTM campaign.","title":"Utm Campaign"}},"required":["website_id","start_at","end_at","type"],"title":"get_website_metricsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_active_visitors":{"post":{"operationId":"get_active_visitors","summary":"Get how many unique visitors a website has right now. Use for \"How many people are on my Umami website right now\".","description":"Get how many unique visitors a website has right now. Use for \"How many people are on my Umami website right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"ID of the website (from list_websites), a UUID.","maxLength":200,"title":"Website Id","type":"string"}},"required":["website_id"],"title":"get_active_visitorsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}