API Evangelist conversational phrasing for Confluence Comment API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Confluence Comment API
  version: 1.0.0
extends: openapi/confluence-comment-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: 22
- target: $.paths['/pages/{id}/footer-comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List the footer comments on a page
      effect: read
      questions:
      - How do I read the comments left at the bottom of a Confluence page?
      - Can I page through a page's footer comments with a limit and cursor?
      instructions:
      - text: Show the footer comments on page {id}.
        slots:
          id: path.id
      - text: Get the first {limit} footer comments on page {id} in storage format.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/pages/{id}/inline-comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List the inline comments on a page
      effect: read
      questions:
      - Where can I see the comments people highlighted inside a specific page's text?
      - Which inline comments exist on one particular page?
      instructions:
      - text: List the inline comments anchored in page {id}.
        slots:
          id: path.id
      - text: Fetch up to {limit} inline comments from page {id}.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/footer-comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List footer comments across the whole site
      effect: read
      questions:
      - Can I pull every footer comment across the site, not just one page?
      - Is there a way to sort all footer comments site-wide by creation date?
      instructions:
      - text: List all footer comments across the site.
      - text: Get all footer comments sorted by {sort}.
        slots:
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/footer-comments'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a footer comment to a page or blog post
      effect: write
      questions:
      - How do I post a comment at the bottom of a Confluence page?
      - Can I reply to an existing footer comment by giving its parent comment?
      instructions:
      - text: Add a footer comment saying {body} to page {pageId}.
        slots:
          body: requestBody.body
          pageId: requestBody.pageId
      - text: Comment {body} at the bottom of blog post {blogPostId}.
        slots:
          body: requestBody.body
          blogPostId: requestBody.blogPostId
      - text: Reply {body} to footer comment {parentCommentId}.
        slots:
          body: requestBody.body
          parentCommentId: requestBody.parentCommentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inline-comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List inline comments across the whole site
      effect: read
      questions:
      - Can I get every inline comment in the site in one list?
      - What does a site-wide listing of highlighted-text comments return?
      instructions:
      - text: List all inline comments across every page and blog post.
      - text: Get all inline comments sorted by {sort}, {limit} at a time.
        slots:
          sort: query.sort
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inline-comments'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an inline comment to selected text
      effect: write
      questions:
      - How do I comment on a specific highlighted sentence in a page?
      - Can an inline comment be anchored to text in a blog post too?
      instructions:
      - text: Add an inline comment {body} on page {pageId} anchored to {inlineCommentProperties}.
        slots:
          body: requestBody.body
          pageId: requestBody.pageId
          inlineCommentProperties: requestBody.inlineCommentProperties
      - text: Highlight {inlineCommentProperties} in blog post {blogPostId} and comment {body}.
        slots:
          inlineCommentProperties: requestBody.inlineCommentProperties
          blogPostId: requestBody.blogPostId
          body: requestBody.body
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a comment by its id
      effect: read
      questions:
      - How do I look up a single comment when I only know its id, without knowing if it is footer or inline?
      - Can I fetch an older version of a comment?
      instructions:
      - text: Get comment {id} using the generic comments endpoint.
        slots:
          id: path.id
      - text: Show version {version} of comment {id}.
        slots:
          version: query.version
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a comment through the generic comments endpoint
      effect: write
      questions:
      - How do I change the text of a comment by id when the version number must go up?
      - What version number do I need to send when editing a comment through the generic endpoint?
      instructions:
      - text: Change comment {id} to say {body} as version {version}.
        slots:
          id: path.id
          body: requestBody.body
          version: requestBody.version
      - text: Rewrite the text of comment {id} to {body}, bumping it to version {version}.
        slots:
          id: path.id
          body: requestBody.body
          version: requestBody.version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a comment through the generic endpoint
      effect: destructive
      questions:
      - How do I remove a comment by id without knowing whether it's footer or inline?
      - Can I delete any comment through the generic comments path?
      instructions:
      - text: Delete comment {id} via the generic comments endpoint.
        slots:
          id: path.id
      - text: Remove comment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments/{id}/children'].get
  update:
    x-apievangelist-phrasing:
      intent: List replies to a comment
      effect: read
      questions:
      - How can I see the replies under a comment when I don't know its type?
      - Which reply comments hang off a given comment id?
      instructions:
      - text: List the replies to comment {id} using the generic comments path.
        slots:
          id: path.id
      - text: Get up to {limit} child replies of comment {id}.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/attachments/{id}/footer-comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on an attachment
      effect: read
      questions:
      - How do I read the comments people left on an uploaded file?
      - Can I see comments on a specific version of an attachment?
      instructions:
      - text: Show the comments on attachment {id}.
        slots:
          id: path.id
      - text: List comments on version {version} of attachment {id}.
        slots:
          version: query.version
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/custom-content/{id}/footer-comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on custom content
      effect: read
      questions:
      - How do I get the comments attached to an app's custom content item?
      - Can I sort the comments on a custom content item?
      instructions:
      - text: List the comments on custom content {id}.
        slots:
          id: path.id
      - text: Get comments on custom content {id} sorted by {sort}.
        slots:
          id: path.id
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/blogposts/{id}/footer-comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List the footer comments on a blog post
      effect: read
      questions:
      - How do I read the comments at the bottom of a Confluence blog post?
      - Can I filter a blog post's footer comments by status?
      instructions:
      - text: Show the footer comments on blog post {id}.
        slots:
          id: path.id
      - text: List {status} footer comments on blog post {id}.
        slots:
          status: query.status
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/blogposts/{id}/inline-comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List the inline comments on a blog post
      effect: read
      questions:
      - Which highlighted-text comments are on a blog post?
      - Can I see only the unresolved inline comments on a blog post?
      instructions:
      - text: List the inline comments on blog post {id}.
        slots:
          id: path.id
      - text: Get inline comments on blog post {id} with resolution status {resolution-status}.
        slots:
          id: path.id
          resolution-status: query.resolution-status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/footer-comments/{comment-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a footer comment by id
      effect: read
      questions:
      - How do I retrieve one footer comment along with its likes and versions?
      - Can I include a footer comment's properties and permitted operations when fetching it?
      instructions:
      - text: Get footer comment {comment-id}.
        slots:
          comment-id: path.comment-id
      - text: Fetch footer comment {comment-id} with its likes included.
        slots:
          comment-id: path.comment-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/footer-comments/{comment-id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit the text of a footer comment
      effect: write
      questions:
      - How do I edit what a footer comment says?
      - Do I need to bump the version when updating a footer comment?
      instructions:
      - text: Update footer comment {comment-id} to read {body}.
        slots:
          comment-id: path.comment-id
          body: requestBody.body
      - text: Save footer comment {comment-id} as version {version} with text {body}.
        slots:
          comment-id: path.comment-id
          version: requestBody.version
          body: requestBody.body
      method: generated
      generated: '2026-10-01'
- target: $.paths['/footer-comments/{comment-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a footer comment
      effect: destructive
      questions:
      - Can a deleted footer comment be recovered afterwards?
      - How do I permanently remove a comment from the bottom of a page?
      instructions:
      - text: Permanently delete footer comment {comment-id}.
        slots:
          comment-id: path.comment-id
      - text: Remove footer comment {comment-id} from its page.
        slots:
          comment-id: path.comment-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/footer-comments/{id}/children'].get
  update:
    x-apievangelist-phrasing:
      intent: List replies to a footer comment
      effect: read
      questions:
      - How do I see the reply thread under a footer comment?
      - Can I sort the replies to a footer comment?
      instructions:
      - text: List the replies to footer comment {id}.
        slots:
          id: path.id
      - text: Get replies to footer comment {id} sorted by {sort}.
        slots:
          id: path.id
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inline-comments/{comment-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an inline comment by id
      effect: read
      questions:
      - How do I retrieve a single inline comment and the text it's anchored to?
      - Can I fetch an inline comment together with its version history?
      instructions:
      - text: Get inline comment {comment-id}.
        slots:
          comment-id: path.comment-id
      - text: Show version {version} of inline comment {comment-id}.
        slots:
          version: query.version
          comment-id: path.comment-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inline-comments/{comment-id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit or resolve an inline comment
      effect: write
      questions:
      - How do I mark an inline comment as resolved?
      - Can I change the wording of an inline comment after posting it?
      instructions:
      - text: Resolve inline comment {comment-id}.
        slots:
          comment-id: path.comment-id
      - text: Set resolved to {resolved} on inline comment {comment-id}.
        slots:
          resolved: requestBody.resolved
          comment-id: path.comment-id
      - text: Change inline comment {comment-id} to say {body}.
        slots:
          comment-id: path.comment-id
          body: requestBody.body
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inline-comments/{comment-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete an inline comment
      effect: destructive
      questions:
      - How do I permanently delete a highlighted-text comment?
      - Is deleting an inline comment reversible?
      instructions:
      - text: Permanently delete inline comment {comment-id}.
        slots:
          comment-id: path.comment-id
      - text: Remove the inline comment {comment-id} from its page.
        slots:
          comment-id: path.comment-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inline-comments/{id}/children'].get
  update:
    x-apievangelist-phrasing:
      intent: List replies to an inline comment
      effect: read
      questions:
      - How do I read the reply thread on an inline comment?
      - Can I limit how many inline comment replies come back per page?
      instructions:
      - text: List the replies to inline comment {id}.
        slots:
          id: path.id
      - text: Get the first {limit} replies under inline comment {id}.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-10-01'