{"openapi":"3.1.0","info":{"title":"Databuddy (BYOK) API","version":"0.1.0","description":"Databuddy (BYOK) lets an AI assistant read your own Databuddy data through the Databuddy API with a key you supply (Databuddy API key (scopes read:data, read:links, read:monitors)). Read-only: 10 tools (list_websites, list_query_types, run_analytics_query, list_funnels, get_funnel_analytics, list_goals, get_goal_analytics, list_feature_flags, list_uptime_monitors, list_short_links). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-databuddy.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-databuddy/docs"},"termsOfService":"https://connectorbay.com/byok-databuddy/terms"},"servers":[{"url":"https://byok-databuddy.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-databuddy/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/list_websites":{"post":{"operationId":"list_websites","summary":"List the websites the key can read, with id, name, domain, public flag and creation date. Needs the read:data scope. Use","description":"List the websites the key can read, with id, name, domain, public flag and creation date. Needs the read:data scope. Use for \"Which websites do I track in Databuddy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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/list_query_types":{"post":{"operationId":"list_query_types","summary":"List the analytics query types that run_analytics_query accepts (for example summary_metrics, top_pages, traffic_sources","description":"List the analytics query types that run_analytics_query accepts (for example summary_metrics, top_pages, traffic_sources) with their allowed filters. Use for \"Which analytics reports can I ask Databuddy for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_meta":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include a description and output fields for each type.","title":"Include Meta"}},"title":"list_query_typesArguments","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/run_analytics_query":{"post":{"operationId":"run_analytics_query","summary":"Run one aggregate analytics report for a website over a date preset, for example summary_metrics, top_pages, traffic_sou","description":"Run one aggregate analytics report for a website over a date preset, for example summary_metrics, top_pages, traffic_sources, top_referrers, country or device_types. Returns aggregated rows only. Needs the read:data scope. Use for \"What were my top pages in Databuddy over the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (starts with 'web_').","maxLength":200,"title":"Website Id","type":"string"},"query_type":{"description":"Report to run, one of the names from list_query_types, for example top_pages.","maxLength":60,"title":"Query Type","type":"string"},"preset":{"anyOf":[{"enum":["today","yesterday","last_7d","last_14d","last_30d","last_90d","this_week","last_week","this_month","last_month","this_year"],"type":"string"},{"type":"null"}],"default":"last_30d","description":"Date range: today, yesterday, last_7d, last_14d, last_30d, last_90d, this_week, last_week, this_month, last_month or this_year.","title":"Preset"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Maximum rows for the report (1 to 1000).","title":"Limit"}},"required":["website_id","query_type"],"title":"run_analytics_queryArguments","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_funnels":{"post":{"operationId":"list_funnels","summary":"List the conversion funnels defined for a website with their steps and active flag. Use for \"What funnels do I have on w","description":"List the conversion funnels defined for a website with their steps and active flag. Use for \"What funnels do I have on website web_123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (starts with 'web_'; take it from list_websites).","maxLength":200,"title":"Website Id","type":"string"}},"required":["website_id"],"title":"list_funnelsArguments","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_funnel_analytics":{"post":{"operationId":"get_funnel_analytics","summary":"Get conversion analytics of one funnel: overall conversion rate, users entered and completed, per-step drop-off and a da","description":"Get conversion analytics of one funnel: overall conversion rate, users entered and completed, per-step drop-off and a daily series. Dates are optional. Use for \"How is funnel fn_1 converting on website web_123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (starts with 'web_'; take it from list_websites).","maxLength":200,"title":"Website Id","type":"string"},"funnel_id":{"description":"Id of the funnel from list_funnels.","maxLength":200,"title":"Funnel Id","type":"string"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start date as YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End date as YYYY-MM-DD.","title":"End Date"}},"required":["website_id","funnel_id"],"title":"get_funnel_analyticsArguments","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_goals":{"post":{"operationId":"list_goals","summary":"List the conversion goals defined for a website with type, target and active flag. Use for \"What goals are set up on web","description":"List the conversion goals defined for a website with type, target and active flag. Use for \"What goals are set up on website web_123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (starts with 'web_'; take it from list_websites).","maxLength":200,"title":"Website Id","type":"string"}},"required":["website_id"],"title":"list_goalsArguments","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_goal_analytics":{"post":{"operationId":"get_goal_analytics","summary":"Get conversion analytics of one goal: conversion rate, users entered and completed and a daily series. Dates are optiona","description":"Get conversion analytics of one goal: conversion rate, users entered and completed and a daily series. Dates are optional. Use for \"How is goal gl_1 converting on website web_123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (starts with 'web_'; take it from list_websites).","maxLength":200,"title":"Website Id","type":"string"},"goal_id":{"description":"Id of the goal from list_goals.","maxLength":200,"title":"Goal Id","type":"string"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start date as YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End date as YYYY-MM-DD.","title":"End Date"}},"required":["website_id","goal_id"],"title":"get_goal_analyticsArguments","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_feature_flags":{"post":{"operationId":"list_feature_flags","summary":"List feature flags of a website with key, type, status, rollout percentage and default value. Use for \"Which feature fla","description":"List feature flags of a website with key, type, status, rollout percentage and default value. Use for \"Which feature flags are active on website web_123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the website (starts with 'web_').","title":"Website Id"},"status":{"anyOf":[{"enum":["active","inactive","archived"],"type":"string"},{"type":"null"}],"default":null,"description":"Only flags with this status.","title":"Status"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum flags to return (1 to 200).","title":"Limit"}},"title":"list_feature_flagsArguments","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_uptime_monitors":{"post":{"operationId":"list_uptime_monitors","summary":"List uptime monitors (URL, interval, paused state) for the organization. Needs the read:monitors scope. Use for \"Which U","description":"List uptime monitors (URL, interval, paused state) for the organization. Needs the read:monitors scope. Use for \"Which URLs does Databuddy monitor for uptime\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Organization id; leave out to use the key's organization.","title":"Organization Id"}},"title":"list_uptime_monitorsArguments","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_short_links":{"post":{"operationId":"list_short_links","summary":"List short links of the organization with slug, name, target URL and expiry, newest first. Needs the read:links scope. U","description":"List short links of the organization with slug, name, target URL and expiry, newest first. Needs the read:links scope. Use for \"Which short links exist in Databuddy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Links per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of links to skip.","title":"Offset"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only links matching this text.","title":"Search"}},"title":"list_short_linksArguments","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}}}}