# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Service Management Public REST Request API
  version: 1.0.0
extends: openapi/jira-request-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: 29
- target: $.paths['/rest/servicedeskapi/request'].get
  update:
    x-apievangelist-phrasing:
      intent: List my service desk customer requests
      effect: read
      questions:
      - Which customer requests have I raised or participate in across all service desks?
      - Can I filter my Jira Service Management requests to only open ones awaiting approval?
      - What order do my customer requests come back in when I list them?
      instructions:
      - text: List my customer requests in service desk {serviceDeskId}.
        slots:
          serviceDeskId: query.serviceDeskId
      - text: Find my customer requests matching {searchTerm} with status {requestStatus}.
        slots:
          searchTerm: query.searchTerm
          requestStatus: query.requestStatus
      - text: Show the requests I own that are pending my approval.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request'].post
  update:
    x-apievangelist-phrasing:
      intent: Raise a customer request in a service desk
      effect: write
      questions:
      - How do I raise a new customer request in a Jira Service Management desk?
      - Can I open a service desk request on behalf of another customer?
      - What fields do I need to submit when creating a customer request?
      instructions:
      - text: Create a request of type {requestTypeId} in service desk {serviceDeskId}.
        slots:
          requestTypeId: requestBody.requestTypeId
          serviceDeskId: requestBody.serviceDeskId
      - text: Raise a request in service desk {serviceDeskId} on behalf of {raiseOnBehalfOf}.
        slots:
          serviceDeskId: requestBody.serviceDeskId
          raiseOnBehalfOf: requestBody.raiseOnBehalfOf
      - text: Open a new customer request and add {requestParticipants} as participants.
        slots:
          requestParticipants: requestBody.requestParticipants
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a customer request payload without creating it
      effect: read
      questions:
      - Can I test whether a customer request payload is valid before actually submitting it?
      - Is there a dry run that runs the same validations as creating a request, forms included?
      instructions:
      - text: Validate a request of type {requestTypeId} for service desk {serviceDeskId} without saving it.
        slots:
          requestTypeId: requestBody.requestTypeId
          serviceDeskId: requestBody.serviceDeskId
      - text: Dry-run my customer request payload with fields {requestFieldValues} and report any errors.
        slots:
          requestFieldValues: requestBody.requestFieldValues
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one customer request
      effect: read
      questions:
      - How can I look up a single service desk request by its key?
      - What details come back for one customer request, and can I expand extra sections?
      instructions:
      - text: Show customer request {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Get request {issueIdOrKey} with {expand} expanded.
        slots:
          issueIdOrKey: path.issueIdOrKey
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/approval'].get
  update:
    x-apievangelist-phrasing:
      intent: List approvals on a customer request
      effect: read
      questions:
      - Which approvals are attached to this service desk request?
      - Can I see every approval step a customer request has gone through?
      instructions:
      - text: List all approvals on request {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Show the approvals for {issueIdOrKey}, {limit} at a time.
        slots:
          issueIdOrKey: path.issueIdOrKey
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/approval/{approvalId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status and approvers of one approval
      effect: read
      questions:
      - Who are the approvers on a specific approval, and has it been decided yet?
      - How do I check the current status of a single approval on a request?
      instructions:
      - text: Show approval {approvalId} on request {issueIdOrKey}.
        slots:
          approvalId: path.approvalId
          issueIdOrKey: path.issueIdOrKey
      - text: Tell me who still needs to sign off approval {approvalId} for {issueIdOrKey}.
        slots:
          approvalId: path.approvalId
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/approval/{approvalId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve or decline an approval
      effect: write
      questions:
      - How do I approve or decline a pending approval assigned to me on a request?
      - Can I reject an approval request through the API?
      instructions:
      - text: Approve approval {approvalId} on request {issueIdOrKey}.
        slots:
          approvalId: path.approvalId
          issueIdOrKey: path.issueIdOrKey
      - text: Answer approval {approvalId} on {issueIdOrKey} with decision {decision}.
        slots:
          approvalId: path.approvalId
          issueIdOrKey: path.issueIdOrKey
          decision: requestBody.decision
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/attachment'].get
  update:
    x-apievangelist-phrasing:
      intent: List attachments on a customer request
      effect: read
      questions:
      - Which files have been attached to a customer request?
      - Do customers only see public attachments when listing a request's files?
      instructions:
      - text: List attachments on request {issueIdOrKey} starting at {start}, {limit} per page.
        slots:
          issueIdOrKey: path.issueIdOrKey
          start: query.start
          limit: query.limit
      - text: Show the files attached to {issueIdOrKey}, page from {start} with size {limit}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          start: query.start
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/attachment'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a request with uploaded files
      effect: write
      questions:
      - How do I post a comment that includes files I already uploaded as temporary attachments?
      - Can I attach files to a request as a public comment?
      instructions:
      - text: Attach temporary files {temporaryAttachmentIds} to request {issueIdOrKey} as a comment.
        slots:
          temporaryAttachmentIds: requestBody.temporaryAttachmentIds
          issueIdOrKey: path.issueIdOrKey
      - text: Add the uploaded files to {issueIdOrKey} with the note {additionalComment}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          additionalComment: requestBody.additionalComment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/attachment/{attachmentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an attachment's contents
      effect: read
      questions:
      - How do I download the full file of an attachment on a service desk request?
      - Can I fetch the raw contents of a request attachment?
      instructions:
      - text: Download attachment {attachmentId} from request {issueIdOrKey}.
        slots:
          attachmentId: path.attachmentId
          issueIdOrKey: path.issueIdOrKey
      - text: Get the file contents of attachment {attachmentId} on {issueIdOrKey}.
        slots:
          attachmentId: path.attachmentId
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/attachment/{attachmentId}/thumbnail'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a thumbnail of a request attachment
      effect: read
      questions:
      - Can I get a small preview image of an attachment instead of the whole file?
      - Where do I fetch the thumbnail for a request attachment?
      instructions:
      - text: Get the thumbnail for attachment {attachmentId} on request {issueIdOrKey}.
        slots:
          attachmentId: path.attachmentId
          issueIdOrKey: path.issueIdOrKey
      - text: Show a preview image of attachment {attachmentId} in {issueIdOrKey}.
        slots:
          attachmentId: path.attachmentId
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/comment'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on a customer request
      effect: read
      questions:
      - What comments have been left on a customer request?
      - Can I list only the internal comments on a request, or only public ones?
      instructions:
      - text: List the comments on request {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Show only internal comments on {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Show comments on {issueIdOrKey} where public is {public}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          public: query.public
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/comment'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a comment to a customer request
      effect: write
      questions:
      - How do I reply to a customer on their service desk request?
      - Can I add an internal note to a request that the customer can't see?
      instructions:
      - text: Comment {body} on request {issueIdOrKey}.
        slots:
          body: requestBody.body
          issueIdOrKey: path.issueIdOrKey
      - text: Add an internal comment {body} to {issueIdOrKey} with public set to {public}.
        slots:
          body: requestBody.body
          issueIdOrKey: path.issueIdOrKey
          public: requestBody.public
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/comment/{commentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one comment on a customer request
      effect: read
      questions:
      - How do I retrieve a specific comment on a request by its ID?
      - Can customers read an internal comment if they fetch it by ID?
      instructions:
      - text: Show comment {commentId} on request {issueIdOrKey}.
        slots:
          commentId: path.commentId
          issueIdOrKey: path.issueIdOrKey
      - text: Get comment {commentId} from {issueIdOrKey} with {expand} expanded.
        slots:
          commentId: path.commentId
          issueIdOrKey: path.issueIdOrKey
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/comment/{commentId}/attachment'].get
  update:
    x-apievangelist-phrasing:
      intent: List files attached to a request comment
      effect: read
      questions:
      - Which attachments are referenced in a particular comment?
      - Can I see the files someone added along with their comment?
      instructions:
      - text: List the attachments in comment {commentId} on request {issueIdOrKey}.
        slots:
          commentId: path.commentId
          issueIdOrKey: path.issueIdOrKey
      - text: Show files linked to comment {commentId} of {issueIdOrKey}.
        slots:
          commentId: path.commentId
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/notification'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if I'm subscribed to a request's notifications
      effect: read
      questions:
      - Am I currently receiving notifications for this customer request?
      - How can I tell whether I'm subscribed to updates on a request?
      instructions:
      - text: Check whether I'm subscribed to notifications on {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Tell me my notification subscription status for request {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/notification'].put
  update:
    x-apievangelist-phrasing:
      intent: Subscribe to a request's notifications
      effect: write
      questions:
      - How do I start getting notified about updates on a customer request?
      - Can I opt myself back in to notifications for a request?
      instructions:
      - text: Subscribe me to notifications on request {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Turn on update emails for {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/notification'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop notifications from a request
      effect: destructive
      questions:
      - How do I stop getting notifications from a customer request?
      - Can I mute a single service desk request without leaving it?
      instructions:
      - text: Unsubscribe me from notifications on request {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Mute updates for {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/participant'].get
  update:
    x-apievangelist-phrasing:
      intent: List participants on a customer request
      effect: read
      questions:
      - Who is participating in this customer request?
      - Which people besides the reporter are on a service desk request?
      instructions:
      - text: List the participants on request {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Show who has been added to {issueIdOrKey} as a participant.
        slots:
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/participant'].post
  update:
    x-apievangelist-phrasing:
      intent: Add participants to a customer request
      effect: write
      questions:
      - How do I add colleagues as participants on an existing request?
      - Can I share a customer request with other people after it's created?
      instructions:
      - text: Add {accountIds} as participants on request {issueIdOrKey}.
        slots:
          accountIds: requestBody.accountIds
          issueIdOrKey: path.issueIdOrKey
      - text: Share {issueIdOrKey} with users {usernames}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          usernames: requestBody.usernames
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/participant'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove participants from a customer request
      effect: destructive
      questions:
      - How do I take someone off a customer request's participant list?
      - Can I remove several participants from a request at once?
      instructions:
      - text: Remove {accountIds} from the participants on request {issueIdOrKey}.
        slots:
          accountIds: requestBody.accountIds
          issueIdOrKey: path.issueIdOrKey
      - text: Drop users {usernames} from {issueIdOrKey}.
        slots:
          usernames: requestBody.usernames
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/sla'].get
  update:
    x-apievangelist-phrasing:
      intent: List SLA records on a customer request
      effect: read
      questions:
      - What SLAs are running on this service desk request and have any been breached?
      - Can I see completed and ongoing SLA cycles for a request?
      instructions:
      - text: List all SLA records for request {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Show SLA cycles on {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/sla/{slaMetricId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one SLA metric on a customer request
      effect: read
      questions:
      - How do I check a single SLA metric, like time to resolution, on a request?
      - Who is allowed to read the details of one SLA on a request?
      instructions:
      - text: Show SLA metric {slaMetricId} on request {issueIdOrKey}.
        slots:
          slaMetricId: path.slaMetricId
          issueIdOrKey: path.issueIdOrKey
      - text: Get the details of SLA {slaMetricId} for {issueIdOrKey}.
        slots:
          slaMetricId: path.slaMetricId
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a request's status history
      effect: read
      questions:
      - What statuses has a customer request moved through over time?
      - Can I see the status history of a request, most recent first?
      instructions:
      - text: Show the status history of request {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: List every status {issueIdOrKey} has been in.
        slots:
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/transition'].get
  update:
    x-apievangelist-phrasing:
      intent: List transitions I can perform on a request
      effect: read
      questions:
      - Which workflow actions can I take on a customer request right now?
      - What transitions are available to a customer on their request?
      instructions:
      - text: List the transitions available on request {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      - text: Show what status changes I'm allowed to make on {issueIdOrKey}.
        slots:
          issueIdOrKey: path.issueIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{issueIdOrKey}/transition'].post
  update:
    x-apievangelist-phrasing:
      intent: Move a customer request to another status
      effect: write
      questions:
      - How do I move a customer request through its workflow, like resolving it?
      - Can I add a reason comment when transitioning a request?
      instructions:
      - text: Perform transition {id} on request {issueIdOrKey}.
        slots:
          id: requestBody.id
          issueIdOrKey: path.issueIdOrKey
      - text: Transition {issueIdOrKey} using {id} with the comment {additionalComment}.
        slots:
          issueIdOrKey: path.issueIdOrKey
          id: requestBody.id
          additionalComment: requestBody.additionalComment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{requestIdOrKey}/feedback'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the customer feedback on a request
      effect: read
      questions:
      - What satisfaction rating did the customer give on their request?
      - How can I read the feedback left on a resolved request?
      instructions:
      - text: Show the feedback on request {requestIdOrKey}.
        slots:
          requestIdOrKey: path.requestIdOrKey
      - text: Get the satisfaction rating for {requestIdOrKey}.
        slots:
          requestIdOrKey: path.requestIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{requestIdOrKey}/feedback'].post
  update:
    x-apievangelist-phrasing:
      intent: Leave feedback on a request
      effect: write
      questions:
      - How does a reporter leave a satisfaction rating on their request?
      - Can I submit a rating with a written comment on a request?
      instructions:
      - text: Rate request {requestIdOrKey} {rating}.
        slots:
          requestIdOrKey: path.requestIdOrKey
          rating: requestBody.rating
      - text: Leave feedback on {requestIdOrKey} with rating {rating} and comment {comment}.
        slots:
          requestIdOrKey: path.requestIdOrKey
          rating: requestBody.rating
          comment: requestBody.comment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/request/{requestIdOrKey}/feedback'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete the feedback on a request
      effect: destructive
      questions:
      - Can I remove a satisfaction rating I already left on a request?
      - Who is allowed to delete feedback on a customer request?
      instructions:
      - text: Delete the feedback on request {requestIdOrKey}.
        slots:
          requestIdOrKey: path.requestIdOrKey
      - text: Remove my rating from {requestIdOrKey}.
        slots:
          requestIdOrKey: path.requestIdOrKey
      method: generated
      generated: '2026-09-26'