# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Close Comments API
  version: 1.0.0
extends: openapi/close-comments-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/comment/'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on an object or thread
      effect: read
      questions:
      - How can I see all comments left on a lead?
      - Do I filter comments by the commented object or by thread?
      instructions:
      - text: List the comments on object {object_id}.
        slots:
          object_id: query.object_id
      - text: Show every comment in thread {thread_id}.
        slots:
          thread_id: query.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comment/'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a comment to a record
      effect: write
      questions:
      - How do I leave a comment on a lead or activity?
      - Does posting a comment start a new thread automatically?
      instructions:
      - text: Comment {body} on object {object_id}.
        slots:
          body: requestBody.body
          object_id: requestBody.object_id
      - text: Add a comment to {object_id} saying {body}.
        slots:
          body: requestBody.body
          object_id: requestBody.object_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comment/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single comment
      effect: read
      questions:
      - Why do I get a 404 fetching a comment I know exists?
      - Can I read one specific comment by its ID?
      instructions:
      - text: Show comment {id}.
        slots:
          id: path.id
      - text: Fetch the text of comment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comment/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a comment's text
      effect: write
      questions:
      - Can I edit a comment someone else wrote?
      - How do I fix a typo in a comment I posted?
      instructions:
      - text: Change comment {id} to read {body}.
        slots:
          id: path.id
          body: requestBody.body
      - text: Edit my comment {id} with the corrected text {body}.
        slots:
          id: path.id
          body: requestBody.body
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comment/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a comment
      effect: destructive
      questions:
      - Does removing a comment delete the whole thread?
      - How do I take down a comment I posted by mistake?
      instructions:
      - text: Remove comment {id}.
        slots:
          id: path.id
      - text: Delete the body of comment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comment_thread/'].get
  update:
    x-apievangelist-phrasing:
      intent: List comment threads
      effect: read
      questions:
      - Which records have comment threads on them?
      - Why do I get a 403 when listing all comment threads?
      instructions:
      - text: List the comment threads on objects {object_ids}.
        slots:
          object_ids: query.object_ids
      - text: Show comment threads {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comment_thread/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single comment thread
      effect: read
      questions:
      - Can I load one comment thread with all its comments?
      - What does a comment thread record contain?
      instructions:
      - text: Show comment thread {id}.
        slots:
          id: path.id
      - text: Fetch the full discussion in thread {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'