{"openapi":"3.1.0","info":{"title":"Birdeye (BYOK) API","version":"0.1.0","description":"Birdeye (BYOK) lets an AI assistant read your own Birdeye data through the Birdeye API with a key you supply (Birdeye API key). Read-only: 12 tools (get_user_details, get_business, list_child_businesses, get_review_summary, list_reviews, list_review_tags, get_dashboard, list_surveys, list_review_sources, count_reviews_by_source, list_competitors, get_listing). The BYOK key travels with each...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-birdeye.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-birdeye/docs"},"termsOfService":"https://connectorbay.com/byok-birdeye/terms"},"servers":[{"url":"https://byok-birdeye.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-birdeye/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_user_details":{"post":{"operationId":"get_user_details","summary":"Look up a Birdeye user by email: name, role and the businesses the user can access. Use for \"Which Birdeye businesses ca","description":"Look up a Birdeye user by email: name, role and the businesses the user can access. Use for \"Which Birdeye businesses can jane@example.com access\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email":{"description":"Email address of the Birdeye user.","maxLength":200,"title":"Email","type":"string"}},"required":["email"],"title":"get_user_detailsArguments","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_business":{"post":{"operationId":"get_business","summary":"Get a business profile: name, contact details, address, category, status, review count, average rating and social profil","description":"Get a business profile: name, contact details, address, category, status, review count, average rating and social profile links. Use for \"What are the review count and rating of Birdeye business 12345678\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Birdeye business id (the business number shown in the account), for example '12345678'.","maxLength":30,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"get_businessArguments","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_child_businesses":{"post":{"operationId":"list_child_businesses","summary":"List the businesses and sub-accounts under a reseller, sub-reseller or enterprise account with type, status and city. Us","description":"List the businesses and sub-accounts under a reseller, sub-reseller or enterprise account with type, status and city. Use for \"Which locations sit under my Birdeye enterprise account 12345678\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pid":{"description":"Id of the reseller, sub-reseller or enterprise account whose children to list.","minimum":1,"title":"Pid","type":"integer"}},"required":["pid"],"title":"list_child_businessesArguments","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_review_summary":{"post":{"operationId":"get_review_summary","summary":"Get a business's review counts and average rating per review site, plus the count per star rating. Use for \"How many rev","description":"Get a business's review counts and average rating per review site, plus the count per star rating. Use for \"How many reviews does Birdeye business 12345678 have on each site\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Birdeye business id (the business number shown in the account), for example '12345678'.","maxLength":30,"title":"Business Id","type":"string"},"statuses":{"anyOf":[{"enum":["published","parked"],"type":"string"},{"type":"null"}],"default":null,"description":"Review status filter: published (featured reviews) or parked (non-featured); empty uses the account default.","title":"Statuses"}},"required":["business_id"],"title":"get_review_summaryArguments","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_reviews":{"post":{"operationId":"list_reviews","summary":"List a business's reviews with rating, text, reviewer name, source, date and any reply. Runs a search; nothing is change","description":"List a business's reviews with rating, text, reviewer name, source, date and any reply. Runs a search; nothing is changed. Page with sindex and count. Use for \"Show the latest reviews that mention parking for Birdeye business 12345678\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Birdeye business id, for example '12345678'.","maxLength":30,"title":"Business Id","type":"string"},"sindex":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Start index of the first review (default 0); sindex plus count must stay at or below 100000.","title":"Sindex"},"count":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many reviews to return (default 25).","title":"Count"},"search_text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only reviews containing this text.","title":"Search Text"},"statuses":{"anyOf":[{"enum":["published","parked","all"],"type":"string"},{"type":"null"}],"default":"published","description":"Which reviews: published (featured, the default), parked (non-featured) or all.","title":"Statuses"},"from_timestamp":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only reviews on or after this Unix time in milliseconds.","title":"From Timestamp"},"to_timestamp":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only reviews on or before this Unix time in milliseconds.","title":"To Timestamp"}},"required":["business_id"],"title":"list_reviewsArguments","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_review_tags":{"post":{"operationId":"list_review_tags","summary":"List the review tags defined for a business. Use for \"Which review tags exist for Birdeye business 12345678\".","description":"List the review tags defined for a business. Use for \"Which review tags exist for Birdeye business 12345678\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Birdeye business id (business number).","maxLength":30,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"list_review_tagsArguments","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_dashboard":{"post":{"operationId":"get_dashboard","summary":"Get the reputation dashboard of a business: all-time and last-30-day rating and review counts, sentiment split, industry","description":"Get the reputation dashboard of a business: all-time and last-30-day rating and review counts, sentiment split, industry benchmark, and recent positive and negative reviews. Use for \"How is Birdeye business 12345678 doing on ratings and sentiment\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Birdeye business id.","maxLength":30,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"get_dashboardArguments","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_surveys":{"post":{"operationId":"list_surveys","summary":"List a business's surveys with status, creation and modification time, response count and question count. Use for \"Which","description":"List a business's surveys with status, creation and modification time, response count and question count. Use for \"Which surveys does Birdeye business 12345678 run and how many answers did each get\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Birdeye business id (the business number shown in the account), for example '12345678'.","maxLength":30,"title":"Business Id","type":"string"},"sort_by":{"anyOf":[{"enum":["modified","created","response"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by modified, created or response (response count).","title":"Sort By"},"sort_order":{"anyOf":[{"enum":["0","1"],"type":"string"},{"type":"null"}],"default":null,"description":"0 for ascending, 1 for descending.","title":"Sort Order"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only surveys whose name or location matches this text.","title":"Search"}},"required":["business_id"],"title":"list_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}},"/v1/tools/list_review_sources":{"post":{"operationId":"list_review_sources","summary":"List the review sites (aggregation sources) connected to a business with the profile URL on each. Use for \"Which review ","description":"List the review sites (aggregation sources) connected to a business with the profile URL on each. Use for \"Which review sites is Birdeye business 12345678 connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Birdeye business id (the business number shown in the account), for example '12345678'.","maxLength":30,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"list_review_sourcesArguments","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/count_reviews_by_source":{"post":{"operationId":"count_reviews_by_source","summary":"Count reviews per review site for a business and optionally selected locations over the last N months. Runs a report; no","description":"Count reviews per review site for a business and optionally selected locations over the last N months. Runs a report; nothing is changed. Use for \"How many reviews per site did Birdeye business 12345678 get in the last 6 months\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Birdeye business id.","maxLength":30,"title":"Business Id","type":"string"},"months":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":12,"description":"How many past months to cover (default 12).","title":"Months"}},"required":["business_id"],"title":"count_reviews_by_sourceArguments","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_competitors":{"post":{"operationId":"list_competitors","summary":"List the competitor enterprises and their locations tracked for a business. Use for \"Which competitors does Birdeye trac","description":"List the competitor enterprises and their locations tracked for a business. Use for \"Which competitors does Birdeye track for business 12345678\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Birdeye business id (the business number shown in the account), for example '12345678'.","maxLength":30,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"list_competitorsArguments","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_listing":{"post":{"operationId":"get_listing","summary":"Get a location's online listing data: name, phone, website, address, timezone, hours and business status. Use for \"What ","description":"Get a location's online listing data: name, phone, website, address, timezone, hours and business status. Use for \"What listing information is stored for Birdeye location 169744180007807\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Birdeye business id (the business number shown in the account), for example '12345678'.","maxLength":30,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"get_listingArguments","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}}}}