# 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 Servicedesk API
  version: 1.0.0
extends: openapi/jira-servicedesk-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: 22
- target: $.paths['/rest/servicedeskapi/servicedesk'].get
  update:
    x-apievangelist-phrasing:
      intent: List all accessible service desks
      effect: read
      questions:
      - Which service desks can I access in our Jira Service Management instance?
      - Can I page through every service desk when there are hundreds of them?
      instructions:
      - text: List all the service desks I have access to.
      - text: Show the next {limit} service desks starting at index {start}.
        slots:
          limit: query.limit
          start: query.start
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of one service desk
      effect: read
      questions:
      - What are the details of a specific service desk if I only have its ID?
      - Can I look up a service desk using its project key instead of its ID?
      instructions:
      - text: Get the details of service desk {serviceDeskId}.
        slots:
          serviceDeskId: path.serviceDeskId
      - text: Show me the name and project behind service desk {serviceDeskId}.
        slots:
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/attachTemporaryFile'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a temporary attachment to a service desk
      effect: write
      questions:
      - How do I upload a file to a service desk before attaching it to a customer request?
      - Can I stage several temporary attachments on a service desk at once?
      instructions:
      - text: Upload this file as a temporary attachment on service desk {serviceDeskId}.
        slots:
          serviceDeskId: path.serviceDeskId
      - text: Stage these screenshots on service desk {serviceDeskId} so I can attach them to a request later.
        slots:
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/customer'].get
  update:
    x-apievangelist-phrasing:
      intent: List customers on a service desk
      effect: read
      questions:
      - Who are the customers registered on a given service desk?
      - Can I find a service desk customer by part of their name or email?
      instructions:
      - text: List the customers of service desk {serviceDeskId}.
        slots:
          serviceDeskId: path.serviceDeskId
      - text: Find customers on service desk {serviceDeskId} matching {query}.
        slots:
          serviceDeskId: path.serviceDeskId
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/customer'].post
  update:
    x-apievangelist-phrasing:
      intent: Add existing users as service desk customers
      effect: write
      questions:
      - How do I give existing users customer access to a service desk?
      - What happens if I add a customer who is already on the service desk?
      instructions:
      - text: Add account IDs {accountIds} as customers of service desk {serviceDeskId}.
        slots:
          accountIds: requestBody.accountIds
          serviceDeskId: path.serviceDeskId
      - text: Grant customer access on service desk {serviceDeskId} to these existing users.
        slots:
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/customer'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove customers from a service desk
      effect: destructive
      questions:
      - How do I take customers off a closed-access service desk?
      - Does removing customers from a service desk require it to have closed access?
      instructions:
      - text: Remove account IDs {accountIds} from the customers of service desk {serviceDeskId}.
        slots:
          accountIds: requestBody.accountIds
          serviceDeskId: path.serviceDeskId
      - text: Revoke customer access to service desk {serviceDeskId} for these users.
        slots:
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/customer/invite'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite a new customer by email
      effect: write
      questions:
      - How do I email an invitation to someone so they can use our help center?
      - Will inviting a customer create an account if they don't have one yet?
      - Can I get a conflict error when inviting an email that already belongs to a customer?
      instructions:
      - text: Invite {email} to service desk {serviceDeskId} as a customer.
        slots:
          email: requestBody.email
          serviceDeskId: path.serviceDeskId
      - text: Send a customer invitation to {email} named {displayName} for service desk {serviceDeskId}.
        slots:
          email: requestBody.email
          displayName: requestBody.displayName
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/knowledgebase/article'].get
  update:
    x-apievangelist-phrasing:
      intent: Search a service desk's knowledge base articles
      effect: read
      questions:
      - Which knowledge base articles linked to a service desk mention a given topic?
      - Can I get matching terms highlighted in knowledge base search results?
      instructions:
      - text: Search the knowledge base of service desk {serviceDeskId} for {query}.
        slots:
          serviceDeskId: path.serviceDeskId
          query: query.query
      - text: Find help articles about {query} for service desk {serviceDeskId} with highlighting turned on.
        slots:
          query: query.query
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue'].get
  update:
    x-apievangelist-phrasing:
      intent: List the queues in a service desk
      effect: read
      questions:
      - What queues are set up in a service desk?
      - Can I see how many requests are sitting in each queue?
      instructions:
      - text: List the queues in service desk {serviceDeskId}.
        slots:
          serviceDeskId: path.serviceDeskId
      - text: Show every queue in service desk {serviceDeskId} with its request count.
        slots:
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue/{queueId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one service desk queue
      effect: read
      questions:
      - What are the settings of a single queue in my service desk?
      - Can I check the request count for just one queue?
      instructions:
      - text: Get queue {queueId} in service desk {serviceDeskId}.
        slots:
          queueId: path.queueId
          serviceDeskId: path.serviceDeskId
      - text: Get queue {queueId} of service desk {serviceDeskId} including its request count.
        slots:
          queueId: path.queueId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue/{queueId}/issue'].get
  update:
    x-apievangelist-phrasing:
      intent: List customer requests in a queue
      effect: read
      questions:
      - Which customer requests are currently waiting in a particular queue?
      - Why do requests from a queue only show some fields?
      instructions:
      - text: List the requests in queue {queueId} of service desk {serviceDeskId}.
        slots:
          queueId: path.queueId
          serviceDeskId: path.serviceDeskId
      - text: Show the first {limit} tickets sitting in queue {queueId} on service desk {serviceDeskId}.
        slots:
          limit: query.limit
          queueId: path.queueId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype'].get
  update:
    x-apievangelist-phrasing:
      intent: List request types on a service desk
      effect: read
      questions:
      - What kinds of requests can customers raise on a service desk?
      - Can I filter request types by group or by a word in their name?
      - Is it possible to include hidden request types when searching?
      instructions:
      - text: List the request types on service desk {serviceDeskId}.
        slots:
          serviceDeskId: path.serviceDeskId
      - text: Find request types on service desk {serviceDeskId} matching {searchQuery}.
        slots:
          serviceDeskId: path.serviceDeskId
          searchQuery: query.searchQuery
      - text: Show request types in group {groupId} of service desk {serviceDeskId}.
        slots:
          groupId: query.groupId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a request type from an issue type
      effect: write
      questions:
      - How do I add a new request type to a service desk based on an issue type?
      - Why doesn't a newly created request type show up on the customer portal?
      instructions:
      - text: Create a request type called {name} on service desk {serviceDeskId} using issue type {issueTypeId}.
        slots:
          name: requestBody.name
          serviceDeskId: path.serviceDeskId
          issueTypeId: requestBody.issueTypeId
      - text: Add request type {name} to service desk {serviceDeskId} with help text {helpText}.
        slots:
          name: requestBody.name
          serviceDeskId: path.serviceDeskId
          helpText: requestBody.helpText
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/permissions/check'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a user's permissions on request types
      effect: read
      questions:
      - Which request types can a given user submit or administer?
      - How many request types can I check permissions for in one call?
      instructions:
      - text: Check which of request types {requestTypeIds} user {accountId} can submit on service desk {serviceDeskId}.
        slots:
          requestTypeIds: requestBody.requestTypeIds
          accountId: requestBody.accountId
          serviceDeskId: path.serviceDeskId
      - text: Tell me which request types on service desk {serviceDeskId} I'm allowed to administer.
        slots:
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one request type
      effect: read
      questions:
      - What are the details of a single customer request type?
      - Can a request type be read without signing in?
      instructions:
      - text: Get request type {requestTypeId} from service desk {serviceDeskId}.
        slots:
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      - text: Show the name and description of request type {requestTypeId} on service desk {serviceDeskId}.
        slots:
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a request type
      effect: destructive
      questions:
      - How do I delete a request type from a service desk?
      - Does deleting a request type strip it from existing customer requests?
      instructions:
      - text: Delete request type {requestTypeId} from service desk {serviceDeskId}.
        slots:
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      - text: Remove the retired request type {requestTypeId} from service desk {serviceDeskId} entirely.
        slots:
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/field'].get
  update:
    x-apievangelist-phrasing:
      intent: List fields for a request type
      effect: read
      questions:
      - What fields does a customer fill in for a given request type?
      - Can I tell whether I'm allowed to raise a request on behalf of another customer?
      instructions:
      - text: List the fields of request type {requestTypeId} on service desk {serviceDeskId}.
        slots:
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      - text: Show which fields are required when raising request type {requestTypeId} in service desk {serviceDeskId}.
        slots:
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property'].get
  update:
    x-apievangelist-phrasing:
      intent: List property keys on a request type
      effect: read
      questions:
      - What custom property keys are stored against a request type?
      - Which keys of custom data does a service desk request type hold?
      instructions:
      - text: List the property keys on request type {requestTypeId} in service desk {serviceDeskId}.
        slots:
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      - text: Show all custom property keys saved for request type {requestTypeId} of service desk {serviceDeskId}.
        slots:
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a request type property value
      effect: read
      questions:
      - What value is stored in a specific property of a request type?
      - Can I read custom data my app saved on a service desk request type?
      instructions:
      - text: Get property {propertyKey} of request type {requestTypeId} in service desk {serviceDeskId}.
        slots:
          propertyKey: path.propertyKey
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      - text: Read the {propertyKey} value saved on request type {requestTypeId} for service desk {serviceDeskId}.
        slots:
          propertyKey: path.propertyKey
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a request type property value
      effect: write
      questions:
      - How do I store custom data against a service desk request type?
      - How long can a request type property key be?
      instructions:
      - text: Set property {propertyKey} on request type {requestTypeId} in service desk {serviceDeskId} to this JSON.
        slots:
          propertyKey: path.propertyKey
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      - text: Save this config as {propertyKey} on request type {requestTypeId} of service desk {serviceDeskId}.
        slots:
          propertyKey: path.propertyKey
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a request type property
      effect: destructive
      questions:
      - How do I remove a custom property from a request type?
      - Can I clear custom data an app stored on a service desk request type?
      instructions:
      - text: Delete property {propertyKey} from request type {requestTypeId} in service desk {serviceDeskId}.
        slots:
          propertyKey: path.propertyKey
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      - text: Remove the {propertyKey} entry saved on request type {requestTypeId} of service desk {serviceDeskId}.
        slots:
          propertyKey: path.propertyKey
          requestTypeId: path.requestTypeId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttypegroup'].get
  update:
    x-apievangelist-phrasing:
      intent: List request type groups on a service desk
      effect: read
      questions:
      - How are request types grouped on a service desk's customer portal?
      - In what order do request type groups appear on the portal?
      instructions:
      - text: List the request type groups for service desk {serviceDeskId}.
        slots:
          serviceDeskId: path.serviceDeskId
      - text: Show the portal categories that organize request types on service desk {serviceDeskId}.
        slots:
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'