API Evangelist conversational phrasing for Shopify Comments API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Shopify Comments API
  version: 1.0.0
extends: openapi/shopify-comments-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/admin/api/2020-01/comments.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List blog article comments
      effect: read
      questions:
      - Which comments are waiting for moderation on my store's blog?
      - Can I pull only the comments left on one blog article?
      - How many blog comments can one page of results return?
      instructions:
      - text: List blog comments with status {status}.
        slots:
          status: query.status
      - text: Show the comments on article {article_id} in blog {blog_id}.
        slots:
          article_id: query.article_id
          blog_id: query.blog_id
      - text: List up to {limit} comments created after {created_at_min}.
        slots:
          limit: query.limit
          created_at_min: query.created_at_min
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-01/comments/count.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Count blog comments
      effect: read
      questions:
      - How many comments has my blog received in total?
      - Can I count just the unapproved comments on a single article?
      instructions:
      - text: Count all comments across my blogs.
      - text: Count comments on article {article_id} whose status is {status}.
        slots:
          article_id: query.article_id
          status: query.status
      - text: Count blog comments published between {published_at_min} and {published_at_max}.
        slots:
          published_at_min: query.published_at_min
          published_at_max: query.published_at_max
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-01/comments/{comment_id}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single blog comment
      effect: read
      questions:
      - What exactly did a reader write in one particular blog comment?
      - Can I fetch a single comment and return only certain fields?
      instructions:
      - text: Show blog comment {comment_id}.
        slots:
          comment_id: path.comment_id
      - text: Get only the fields {fields} of comment {comment_id}.
        slots:
          fields: query.fields
          comment_id: path.comment_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-01/comments/{comment_id}/spam.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a blog comment as spam
      effect: write
      questions:
      - What's the way to flag a junk comment on my blog as spam?
      - Can I tag an existing comment as spam so it stops showing on the article?
      instructions:
      - text: Mark comment {comment_id} as spam.
        slots:
          comment_id: path.comment_id
      - text: Flag blog comment {comment_id} as spam.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-01/comments/{comment_id}/not_spam.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a blog comment as not spam
      effect: write
      questions:
      - A real reader's comment got caught as spam; can I mark it as legitimate?
      - Is there a way to undo a spam flag on a blog comment?
      instructions:
      - text: Mark comment {comment_id} as not spam.
        slots:
          comment_id: path.comment_id
      - text: Clear the spam flag on blog comment {comment_id}.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-01/comments/{comment_id}/remove.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a blog comment
      effect: destructive
      questions:
      - Can I take down an inappropriate comment from a blog article?
      - Is a removed blog comment gone for good, or can it come back later?
      instructions:
      - text: Remove comment {comment_id} from the blog.
        slots:
          comment_id: path.comment_id
      - text: Take blog comment {comment_id} off the article.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/admin/api/2020-01/comments/{comment_id}/restore.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a removed blog comment
      effect: write
      questions:
      - I removed a comment by mistake; can I put it back?
      - What brings a previously removed blog comment back onto the article?
      instructions:
      - text: Restore removed comment {comment_id}.
        slots:
          comment_id: path.comment_id
      - text: Bring blog comment {comment_id} back after it was removed.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-09-24'