{"openapi":"3.1.0","info":{"title":"Mouseflow (BYOK) API","version":"0.1.0","description":"Mouseflow (BYOK) lets an AI assistant read your own Mouseflow data through the Mouseflow API with a key you supply (account email address). Read-only: 10 tools (list_websites, get_website, list_recordings, get_recording, list_heatmap_pages, list_funnels, get_funnel_report, list_forms, list_journeys, list_feedback_surveys). The BYOK key travels with each request, is used for that one call only and...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-mouseflow.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-mouseflow/docs"},"termsOfService":"https://connectorbay.com/byok-mouseflow/terms"},"servers":[{"url":"https://byok-mouseflow.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-mouseflow/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 (projects) of the account with id, name, status, access level and creation date. Use for \"Which websit","description":"List the websites (projects) of the account with id, name, status, access level and creation date. Use for \"Which websites do I have in Mouseflow\".","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/get_website":{"post":{"operationId":"get_website","summary":"Get one website's recording status, installation status, whitelisted domains, recording rate and monthly recording cap. ","description":"Get one website's recording status, installation status, whitelisted domains, recording rate and monthly recording cap. IP exclusions and CSS selector lists are left out. Use for \"Is Mouseflow recording on my shop site and at what rate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (from list_websites), a UUID such as 8fc2ace2-75bc-8ba4-b424-c8916670b990.","maxLength":200,"title":"Website Id","type":"string"}},"required":["website_id"],"title":"get_websiteArguments","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_recordings":{"post":{"operationId":"list_recordings","summary":"List the latest session recordings of a website (newest first) with duration, engagement, friction score, pages, country","description":"List the latest session recordings of a website (newest first) with duration, engagement, friction score, pages, country, device, browser, entry page and tags, plus the total count. IP addresses and coordinates are left out. Use for \"Which Mouseflow recordings from mobile visitors had high friction last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (from list_websites), a UUID such as 8fc2ace2-75bc-8ba4-b424-c8916670b990.","maxLength":200,"title":"Website Id","type":"string"},"fromdate":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day to include, YYYY-MM-DD (midnight in your time zone).","title":"Fromdate"},"todate":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Day to stop at, YYYY-MM-DD (not included).","title":"Todate"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search over user agent, city, region and similar fields.","title":"Search"},"device":{"anyOf":[{"enum":["desktop","tablet","phone"],"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors on this device type.","title":"Device"},"country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors from this two-letter country code, for example us.","title":"Country"},"browser":{"anyOf":[{"enum":["chrome","firefox","safari","ie","edge","opera","android"],"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors using this browser: chrome, firefox, safari, ie, edge, opera or android.","title":"Browser"},"visitortype":{"anyOf":[{"enum":["first","returning"],"type":"string"},{"type":"null"}],"default":null,"description":"Only first-time (first) or returning visitors.","title":"Visitortype"},"referrer":{"anyOf":[{"enum":["searchengines","links","direct","social","email"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this referral type.","title":"Referrer"},"entry":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Only sessions that landed on this page path.","title":"Entry"},"tags":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated tags that must be present, for example form-interact,submit.","title":"Tags"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many recordings to return (API default 50).","title":"Limit"}},"required":["website_id"],"title":"list_recordingsArguments","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_recording":{"post":{"operationId":"get_recording","summary":"Get one session recording's summary: times, pages, duration, engagement, friction, location, device, browser, referrer, ","description":"Get one session recording's summary: times, pages, duration, engagement, friction, location, device, browser, referrer, entry page, tags and the playback link. Use for \"Tell me about Mouseflow recording a180\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (from list_websites), a UUID such as 8fc2ace2-75bc-8ba4-b424-c8916670b990.","maxLength":200,"title":"Website Id","type":"string"},"recording_id":{"description":"Id of the recording (from list_recordings).","maxLength":200,"title":"Recording Id","type":"string"}},"required":["website_id","recording_id"],"title":"get_recordingArguments","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_heatmap_pages":{"post":{"operationId":"list_heatmap_pages","summary":"List pages that have heatmap data with views, visit and engagement time, clicks, friction, scroll reach, entries and exi","description":"List pages that have heatmap data with views, visit and engagement time, clicks, friction, scroll reach, entries and exits, plus the total page count. Use for \"Which pages on my site get the most views in Mouseflow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (from list_websites), a UUID such as 8fc2ace2-75bc-8ba4-b424-c8916670b990.","maxLength":200,"title":"Website Id","type":"string"},"fromdate":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day to include, YYYY-MM-DD (midnight in your time zone).","title":"Fromdate"},"todate":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Day to stop at, YYYY-MM-DD (not included).","title":"Todate"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only pages whose URL contains this text.","title":"Search"},"device":{"anyOf":[{"enum":["desktop","tablet","phone"],"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors on this device type.","title":"Device"},"country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors from this two-letter country code, for example us.","title":"Country"},"browser":{"anyOf":[{"enum":["chrome","firefox","safari","ie","edge","opera","android"],"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors using this browser: chrome, firefox, safari, ie, edge, opera or android.","title":"Browser"},"visitortype":{"anyOf":[{"enum":["first","returning"],"type":"string"},{"type":"null"}],"default":null,"description":"Only first-time (first) or returning visitors.","title":"Visitortype"},"referrer":{"anyOf":[{"enum":["searchengines","links","direct","social","email"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this referral type.","title":"Referrer"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many pages to return (API default 50).","title":"Limit"}},"required":["website_id"],"title":"list_heatmap_pagesArguments","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 of a website with name, step order, lock state and last update (step data is in get_funnel_r","description":"List the conversion funnels of a website with name, step order, lock state and last update (step data is in get_funnel_report). Use for \"Which funnels are set up in Mouseflow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (from list_websites), a UUID such as 8fc2ace2-75bc-8ba4-b424-c8916670b990.","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_report":{"post":{"operationId":"get_funnel_report","summary":"Get a funnel's report: per step, how many sessions and visitors converted or dropped and median durations, friction and ","description":"Get a funnel's report: per step, how many sessions and visitors converted or dropped and median durations, friction and click counts. Use for \"Where do visitors drop out of my Mouseflow checkout funnel\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (from list_websites), a UUID such as 8fc2ace2-75bc-8ba4-b424-c8916670b990.","maxLength":200,"title":"Website Id","type":"string"},"funnel_id":{"description":"Id of the funnel (from list_funnels).","maxLength":200,"title":"Funnel Id","type":"string"},"fromdate":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day to include, YYYY-MM-DD (midnight in your time zone).","title":"Fromdate"},"todate":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Day to stop at, YYYY-MM-DD (not included).","title":"Todate"},"device":{"anyOf":[{"enum":["desktop","tablet","phone"],"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors on this device type.","title":"Device"},"country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors from this two-letter country code, for example us.","title":"Country"},"referrer":{"anyOf":[{"enum":["searchengines","links","direct","social","email"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this referral type.","title":"Referrer"}},"required":["website_id","funnel_id"],"title":"get_funnel_reportArguments","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_forms":{"post":{"operationId":"list_forms","summary":"List tracked forms with URL, alias, visits, interactions, submits, successes and per-field interaction counts. Use for \"","description":"List tracked forms with URL, alias, visits, interactions, submits, successes and per-field interaction counts. Use for \"Which Mouseflow forms have the lowest submit rate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (from list_websites), a UUID such as 8fc2ace2-75bc-8ba4-b424-c8916670b990.","maxLength":200,"title":"Website Id","type":"string"},"fromdate":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day to include, YYYY-MM-DD (midnight in your time zone).","title":"Fromdate"},"todate":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Day to stop at, YYYY-MM-DD (not included).","title":"Todate"},"device":{"anyOf":[{"enum":["desktop","tablet","phone"],"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors on this device type.","title":"Device"},"country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Only visitors from this two-letter country code, for example us.","title":"Country"},"referrer":{"anyOf":[{"enum":["searchengines","links","direct","social","email"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this referral type.","title":"Referrer"}},"required":["website_id"],"title":"list_formsArguments","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_journeys":{"post":{"operationId":"list_journeys","summary":"List the saved journey (flow) reports of a website: focus page, steps before and after, metric and last update. Use for ","description":"List the saved journey (flow) reports of a website: focus page, steps before and after, metric and last update. Use for \"Which journey reports exist in Mouseflow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (from list_websites), a UUID such as 8fc2ace2-75bc-8ba4-b424-c8916670b990.","maxLength":200,"title":"Website Id","type":"string"}},"required":["website_id"],"title":"list_journeysArguments","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_feedback_surveys":{"post":{"operationId":"list_feedback_surveys","summary":"List feedback surveys with name, enabled flag, trigger, impressions and response counts. Survey steps and answers are le","description":"List feedback surveys with name, enabled flag, trigger, impressions and response counts. Survey steps and answers are left out. Use for \"How many responses did my Mouseflow feedback survey get\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"website_id":{"description":"Id of the website (from list_websites), a UUID such as 8fc2ace2-75bc-8ba4-b424-c8916670b990.","maxLength":200,"title":"Website Id","type":"string"}},"required":["website_id"],"title":"list_feedback_surveysArguments","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}}}}