# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Reputation Review Service API
  version: 1.0.0
extends: openapi/vendasta-reviewservice-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/v1/reputation/reviews/can-respond'].post
  update:
    x-apievangelist-phrasing:
      intent: Check whether a review can be responded to
      effect: read
      questions:
      - Can this business actually post a reply to a particular review?
      - Is there a way to tell if a review is eligible for an owner response before I write one?
      instructions:
      - text: Check whether business {business} is able to respond to review {review}.
        slots:
          business: requestBody.businessId
          review: requestBody.reviewId
      - text: Tell me if review {review} accepts a reply from {business}.
        slots:
          review: requestBody.reviewId
          business: requestBody.businessId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reputation/reviews/comments/create'].post
  update:
    x-apievangelist-phrasing:
      intent: Post a reply comment on a review
      effect: write
      questions:
      - How do I reply to a customer review from the reputation tools?
      - Can a reply be saved without publishing it right away?
      - Can a review comment be attributed to the business owner or to a digital agent?
      instructions:
      - text: 'Reply to review {review} with: {text}.'
        slots:
          review: requestBody.reviewId
          text: requestBody.commentText
      - text: Add an owner reply {text} to review {review} but don't publish it yet.
        slots:
          text: requestBody.commentText
          review: requestBody.reviewId
      - text: Post comment {text} on review {review} signed as {name} ({email}).
        slots:
          text: requestBody.commentText
          review: requestBody.reviewId
          name: requestBody.commenterName
          email: requestBody.commenterEmail
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reputation/reviews/comments/update'].post
  update:
    x-apievangelist-phrasing:
      intent: Edit an existing reply on a review
      effect: write
      questions:
      - Can I change the wording of a reply I already posted to a review?
      - What do I need to edit an existing review comment?
      instructions:
      - text: Change the text of review comment {comment} to {content}.
        slots:
          comment: requestBody.reviewCommentId
          content: requestBody.reviewCommentContent
      - text: Fix the typo in my existing reply {comment} so it reads {content}.
        slots:
          comment: requestBody.reviewCommentId
          content: requestBody.reviewCommentContent
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reputation/reviews/get-multi'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch several reviews by their IDs
      effect: read
      questions:
      - Can I pull the full details for a handful of reviews when I already have their IDs?
      - Is it possible to include the replies when fetching reviews by ID?
      instructions:
      - text: Fetch reviews {ids} with their comments included.
        slots:
          ids: requestBody.reviewIds
      - text: Get the review records for IDs {ids}.
        slots:
          ids: requestBody.reviewIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reputation/reviews/history'].post
  update:
    x-apievangelist-phrasing:
      intent: Get the change history of a review
      effect: read
      questions:
      - What has changed on a review over time, and when?
      - Where can I see the edit history for a single review?
      instructions:
      - text: Show the history of review {review}.
        slots:
          review: requestBody.reviewId
      - text: List every recorded change to review {review}.
        slots:
          review: requestBody.reviewId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reputation/reviews/review-metrics'].post
  update:
    x-apievangelist-phrasing:
      intent: Get review metrics for a partner's namespaces
      effect: read
      questions:
      - What review metrics can I get across all the accounts a partner manages?
      - Can review metrics be limited to a date range or particular review sources?
      - Is it possible to break group-level review metrics out per account?
      instructions:
      - text: Get review metrics for partner {partner} across namespaces {namespaces}.
        slots:
          partner: requestBody.partnerId
          namespaces: requestBody.namespaces
      - text: Pull review metrics for partner {partner}, namespaces {namespaces}, between {start} and {end}.
        slots:
          partner: requestBody.partnerId
          namespaces: requestBody.namespaces
          start: requestBody.minDateTime
          end: requestBody.maxDateTime
      - text: Show partner {partner} review metrics for {namespaces} from sources {sources} only.
        slots:
          partner: requestBody.partnerId
          namespaces: requestBody.namespaces
          sources: requestBody.sourceNames
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reputation/reviews/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search a business's reviews by rating, source or text
      effect: read
      questions:
      - How can I find all the one-star reviews a business received last month?
      - Can I search a location's reviews for a word or phrase customers mentioned?
      - Which filters are available when searching reviews, such as source or date?
      instructions:
      - text: Search reviews for account {account} that mention {phrase}.
        slots:
          account: requestBody.accountGroupId
          phrase: requestBody.phrase
      - text: Find {rating}-star reviews for account {account} posted between {start} and {end}.
        slots:
          rating: requestBody.rating
          account: requestBody.accountGroupId
          start: requestBody.minDateTime
          end: requestBody.maxDateTime
      - text: List the newest reviews from source {source} for account {account}.
        slots:
          source: requestBody.sourceName
          account: requestBody.accountGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reputation/reviews/third-party-publish-settings'].post
  update:
    x-apievangelist-phrasing:
      intent: Get third-party review publish settings
      effect: read
      questions:
      - Are third-party reviews set to be published for these accounts?
      - Where do I check the third-party review publishing settings for several businesses at once?
      instructions:
      - text: Get the third-party review publish settings for accounts {accounts}.
        slots:
          accounts: requestBody.accountGroupIds
      - text: Check whether accounts {accounts} publish third-party reviews.
        slots:
          accounts: requestBody.accountGroupIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reputation/reviews/update'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a review's status or publish flags
      effect: write
      questions:
      - Can I mark a review as actioned or change whether it's published?
      - Is it possible to flag a review as shared by the reviewer?
      instructions:
      - text: Set the action status of review {review} to {status}.
        slots:
          review: requestBody.reviewId
          status: requestBody.actionStatus
      - text: Unpublish review {review}.
        slots:
          review: requestBody.reviewId
      - text: Mark review {review} as a published third-party review.
        slots:
          review: requestBody.reviewId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reputation/reviews/user-deleted-info'].post
  update:
    x-apievangelist-phrasing:
      intent: Record that a user deleted a review
      effect: write
      questions:
      - How do I record that a review was deleted and by which user?
      - Can I update the deleted status stored on a review?
      instructions:
      - text: Set the deleted status of review {review} to {status} for user {user}.
        slots:
          review: requestBody.reviewId
          status: requestBody.deletedStatus
          user: requestBody.userId
      - text: Record user {user} as having deleted review {review} with status {status}.
        slots:
          user: requestBody.userId
          review: requestBody.reviewId
          status: requestBody.deletedStatus
      method: generated
      generated: '2026-10-01'