# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Birdeye Competitor API
  version: 1.0.0
extends: openapi/birdeye-competitor-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/v1/business/{EnterpriseBusinessNumber}/child'].get
  update:
    x-apievangelist-phrasing:
      intent: List an enterprise's competitor businesses
      effect: read
      questions:
      - Which competitor businesses are tracked for my enterprise?
      - Can I list the competitors attached to an enterprise account?
      instructions:
      - text: List competitor businesses for enterprise {EnterpriseBusinessNumber} with isCompetitor {isCompetitor}.
        slots:
          EnterpriseBusinessNumber: path.EnterpriseBusinessNumber
          isCompetitor: query.isCompetitor
      - text: Show enterprise {EnterpriseBusinessNumber}'s competitor businesses.
        slots:
          EnterpriseBusinessNumber: path.EnterpriseBusinessNumber
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/business/{EnterpriseCompetitorBusinessId}/child'].get
  update:
    x-apievangelist-phrasing:
      intent: List a competitor enterprise's locations
      effect: read
      questions:
      - Can I list the child locations under a competitor enterprise?
      - What locations belong to a competitor brand I track?
      instructions:
      - text: List the child locations of competitor enterprise {EnterpriseCompetitorBusinessId} with isCompetitor {isCompetitor}.
        slots:
          EnterpriseCompetitorBusinessId: path.EnterpriseCompetitorBusinessId
          isCompetitor: query.isCompetitor
      - text: Get the locations inside tracked competitor brand {EnterpriseCompetitorBusinessId}.
        slots:
          EnterpriseCompetitorBusinessId: path.EnterpriseCompetitorBusinessId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v1/business/{businessId}/competitors'].get
  update:
    x-apievangelist-phrasing:
      intent: List competitors for one location
      effect: read
      questions:
      - Who are the competitors configured for a single location?
      - Can I see the competitor list for one business rather than the whole enterprise?
      instructions:
      - text: Get the competitors of business {businessId}.
        slots:
          businessId: path.businessId
      - text: List competitors configured for location {businessId}.
        slots:
          businessId: path.businessId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/signup/competitor/{businessNumber}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a competitor to track
      effect: write
      questions:
      - Can I add a new competitor to track for my account?
      - What details do I need to create a competitor enterprise?
      instructions:
      - text: Create competitor enterprise {businessName} under account {businessNumber}.
        slots:
          businessName: requestBody.businessName
          businessNumber: path.businessNumber
      - text: Add competitor {businessName} with zip {zip} to account {businessNumber}.
        slots:
          businessName: requestBody.businessName
          zip: requestBody.zip
          businessNumber: path.businessNumber
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/signup/competitor/{businessId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a location to a competitor enterprise
      effect: write
      questions:
      - Can I add another location to a competitor I already track?
      - Is it possible to create a child business inside a competitor enterprise?
      instructions:
      - text: Create a child business in competitor enterprise {businessId}.
        slots:
          businessId: path.businessId
      - text: Add a new location to competitor enterprise {businessId}.
        slots:
          businessId: path.businessId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/aggregation/competitor/{compAccountId}/{businessNumber}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a review source URL for a competitor
      effect: write
      questions:
      - Can I point Birdeye at a competitor's review site page to collect their reviews?
      - What do I need to add a review source URL for a competitor account?
      instructions:
      - text: Add competitor aggregation URL {url} for {sourceAlias} to competitor {compAccountId} of business {businessNumber}.
        slots:
          url: requestBody.url
          sourceAlias: requestBody.sourceAlias
          compAccountId: path.compAccountId
          businessNumber: path.businessNumber
      - text: Start collecting {sourceAlias} reviews for competitor account {compAccountId} under {businessNumber}.
        slots:
          sourceAlias: requestBody.sourceAlias
          compAccountId: path.compAccountId
          businessNumber: path.businessNumber
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/review/businessId/{CompetitorEnterpriseBusinessId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a competitor enterprise's reviews
      effect: read
      questions:
      - Can I read a competitor enterprise's reviews filtered by rating and source?
      - Is there a way to search competitor review text for a keyword?
      instructions:
      - text: Get {count} reviews of competitor enterprise {CompetitorEnterpriseBusinessId} starting at {sindex} with isCompetitor {isCompetitor}.
        slots:
          count: query.count
          CompetitorEnterpriseBusinessId: path.CompetitorEnterpriseBusinessId
          sindex: query.sindex
          isCompetitor: query.isCompetitor
      - text: Search reviews of competitor {CompetitorEnterpriseBusinessId} for {searchStr} with ratings {ratings}.
        slots:
          CompetitorEnterpriseBusinessId: path.CompetitorEnterpriseBusinessId
          searchStr: requestBody.searchStr
          ratings: requestBody.ratings
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v1/competitors/competitive-insight/categories/{businessNumber}'].post
  update:
    x-apievangelist-phrasing:
      intent: Get competitive category scores
      effect: read
      questions:
      - What is my competitive insight score by category compared with competitors?
      - Can I compare category scores against specific competitors for a time period?
      instructions:
      - text: Get competitive category scores for {businessNumber} against {competitors}.
        slots:
          businessNumber: path.businessNumber
          competitors: requestBody.competitors
      - text: Show category scores for {businessNumber} from {startDate} to {endDate}.
        slots:
          businessNumber: path.businessNumber
          startDate: requestBody.startDate
          endDate: requestBody.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/competitors/competitive-insight/themes/{businessNumber}'].post
  update:
    x-apievangelist-phrasing:
      intent: Compare review themes with competitors
      effect: read
      questions:
      - Which review themes come up most for me versus my competitors?
      - Can I filter competitive themes by positive or negative sentiment?
      instructions:
      - text: Get the top {topThm} competitive themes for {businessNumber}.
        slots:
          topThm: requestBody.topThm
          businessNumber: path.businessNumber
      - text: Show {sentiment} theme statistics for {businessNumber} against {competitors}.
        slots:
          sentiment: requestBody.sentiment
          businessNumber: path.businessNumber
          competitors: requestBody.competitors
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/competitors/competitive-insight/keywords/{businessNumber}'].post
  update:
    x-apievangelist-phrasing:
      intent: Compare review keywords with competitors
      effect: read
      questions:
      - Which keywords do reviewers use about me compared with competitors?
      - Can I limit competitive keyword stats to the top keywords by sentiment?
      instructions:
      - text: Get the top {topKW} competitive keywords for {businessNumber}.
        slots:
          topKW: requestBody.topKW
          businessNumber: path.businessNumber
      - text: Show {sentiment} keyword statistics for {businessNumber} versus {competitors}.
        slots:
          sentiment: requestBody.sentiment
          businessNumber: path.businessNumber
          competitors: requestBody.competitors
      method: generated
      generated: '2026-09-26'