# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Zendesk Requests API
  version: 1.0.0
extends: openapi/zendesk-requests-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['/api/v2/requests'].get
  update:
    x-apievangelist-phrasing:
      intent: List an end user's support requests
      effect: read
      questions:
      - As an end user, how do I see all the support requests I've submitted?
      - Can I sort my requests by when they were last updated?
      instructions:
      - text: List my support requests sorted by {sort_by}.
        slots:
          sort_by: query.sort_by
      - text: Show my requests in {sort_order} order.
        slots:
          sort_order: query.sort_order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/requests'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a support request as an end user
      effect: write
      questions:
      - How can a customer open a support request from our own app?
      - Can anonymous users submit requests, and is there a rate limit?
      instructions:
      - text: Submit a support request saying my printer won't connect.
      - text: Open a new request on behalf of the signed-in end user with this subject and comment.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/requests/{request_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of my support requests
      effect: read
      questions:
      - How do I check the status of a request I submitted?
      - Can I see who is cc'd on a request by sideloading users?
      instructions:
      - text: Show my request about the broken printer.
      - text: Get that request's status and cc'd users.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/requests/{request_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Comment on or solve my request
      effect: write
      questions:
      - Can an end user add a comment or cc someone on their existing request?
      - How do I mark my own request as solved?
      instructions:
      - text: Add a comment to my printer request saying it works now and mark it solved.
      - text: CC my manager on that request.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/requests/{request_id}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on a request
      effect: read
      questions:
      - How do I read the conversation on one of my requests?
      - Can I get only comments made by agents, or only since a certain date?
      instructions:
      - text: List comments on this request posted since {since}.
        slots:
          since: query.since
      - text: Show only the {role} comments on my request.
        slots:
          role: query.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/requests/{request_id}/comments/{ticket_comment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one comment on a request
      effect: read
      questions:
      - How do I fetch a single comment from a request's thread?
      - Can an end user open one specific reply on their request?
      instructions:
      - text: Show that one comment from my printer request.
      - text: Get the specific agent reply on this request.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/requests/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search my support requests
      effect: read
      questions:
      - Can I search my requests for a keyword like printer?
      - Is it possible to search requests within my organization or ones I'm cc'd on?
      instructions:
      - text: Search my requests for {query}.
        slots:
          query: query.query
      - text: Find requests mentioning {query} that are on hold.
        slots:
          query: query.query
      method: generated
      generated: '2026-09-26'