API Evangelist conversational phrasing for Zendesk Tickets API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Zendesk Tickets API
  version: 1.0.0
extends: openapi/zendesk-tickets-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: 35
- target: $.paths['/api/v2/problems/autocomplete'].post
  update:
    x-apievangelist-phrasing:
      intent: Find problem tickets by subject text
      effect: read
      questions:
      - Which problem tickets have a subject containing a word I type?
      - Can I look up problem-type tickets by partial subject to link an incident to one?
      instructions:
      - text: Autocomplete problem tickets whose subject contains {text}.
        slots:
          text: query.text
      - text: Suggest problem tickets matching {text}, sending the text in the request body.
        slots:
          text: requestBody.text
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/deleted_tickets'].get
  update:
    x-apievangelist-phrasing:
      intent: List soft-deleted tickets
      effect: read
      questions:
      - Where can I see tickets that were deleted but not yet purged?
      - Is there a way to review recently deleted tickets before they are scrubbed for good?
      instructions:
      - text: Show me the tickets sitting in the deleted tickets view.
      - text: List soft-deleted tickets that can still be restored.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/deleted_tickets/{ticket_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a soft-deleted ticket
      effect: destructive
      questions:
      - Can I erase a ticket that is already in the deleted view for GDPR reasons?
      - What happens when I purge a previously deleted ticket for good?
      instructions:
      - text: Permanently purge the soft-deleted ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Scrub already-deleted ticket {ticket_id} so it can never be recovered.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/deleted_tickets/{ticket_id}/restore'].put
  update:
    x-apievangelist-phrasing:
      intent: Restore a deleted ticket
      effect: write
      questions:
      - Can I bring back a ticket someone deleted by mistake?
      - Is it possible to undelete a single ticket from the deleted tickets view?
      instructions:
      - text: Restore deleted ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Undelete ticket {ticket_id} and put it back in the queue.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/deleted_tickets/destroy_many'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete many soft-deleted tickets
      effect: destructive
      questions:
      - Can I purge up to 100 already-deleted tickets in one request?
      - What is the batch way to scrub a set of deleted tickets for good?
      instructions:
      - text: Permanently purge this batch of soft-deleted tickets.
      - text: Scrub every deleted ticket in this list of ids so none can be restored.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/deleted_tickets/restore_many'].put
  update:
    x-apievangelist-phrasing:
      intent: Restore many deleted tickets at once
      effect: write
      questions:
      - Can I undelete a whole batch of tickets in a single call?
      - Is there a bulk restore for tickets deleted by accident?
      instructions:
      - text: Restore all of these deleted tickets together.
      - text: Bring back this batch of soft-deleted tickets in one go.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/problems'].get
  update:
    x-apievangelist-phrasing:
      intent: List problem tickets
      effect: read
      questions:
      - Which tickets are marked as problems in my help desk?
      - Can I see all problem tickets ordered by most recently updated?
      instructions:
      - text: List every problem ticket, newest updates first.
      - text: Show me the open problem tickets that incidents can be linked to.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List a ticket's tags
      effect: read
      questions:
      - What tags are currently on a particular ticket?
      - Can I read just the tags of a ticket without fetching the whole record?
      instructions:
      - text: Show the tags on ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: List which tags ticket {ticket_id} carries.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/tags'].put
  update:
    x-apievangelist-phrasing:
      intent: Add tags to a ticket
      effect: write
      questions:
      - Can I append tags to a ticket while keeping the ones it already has?
      - Does adding a tag to a ticket support safe updates to avoid collisions?
      instructions:
      - text: Add these tags to ticket {ticket_id} without removing existing ones.
        slots:
          ticket_id: path.ticket_id
      - text: Append a vip tag to ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace all tags on a ticket
      effect: write
      questions:
      - Can I overwrite a ticket's tag list with a completely new set?
      - What call sets a ticket's tags to exactly the list I provide?
      instructions:
      - text: Replace every tag on ticket {ticket_id} with this new set.
        slots:
          ticket_id: path.ticket_id
      - text: Set the tags of ticket {ticket_id} to exactly billing and urgent.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/tags'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove tags from a ticket
      effect: destructive
      questions:
      - Can I strip specific tags off a ticket?
      - Is removing tags from a ticket protected against concurrent edits?
      instructions:
      - text: Remove the spam tag from ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Take these tags off ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets'].get
  update:
    x-apievangelist-phrasing:
      intent: List tickets via the v2 endpoint
      effect: read
      questions:
      - Can I find a ticket by the external id my own system assigned it?
      - Which call lists all tickets in my account through the v2 API?
      instructions:
      - text: Find the ticket with external id {external_id} using the v2 tickets list.
        slots:
          external_id: query.external_id
      - text: List all tickets in the account from the v2 endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a ticket via the v2 endpoint
      effect: write
      questions:
      - What is the v2 API call to open a single new support ticket?
      - Can I open a ticket on behalf of a customer through the v2 tickets endpoint?
      instructions:
      - text: Open a new support ticket through the v2 tickets endpoint.
      - text: File a v2 ticket for the customer's login problem.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a ticket's properties (v2)
      effect: read
      questions:
      - Does fetching a ticket in v2 include its comments or just its properties?
      - Where do I read the status, priority and assignee of one ticket in the v2 API?
      instructions:
      - text: Get the properties of ticket {ticket_id} from the v2 API.
        slots:
          ticket_id: path.ticket_id
      - text: Look up status and assignee for v2 ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a ticket via the v2 endpoint
      effect: write
      questions:
      - Which v2 call changes fields on an existing ticket?
      - Can I reassign a ticket through the v2 update endpoint?
      instructions:
      - text: Update v2 ticket {ticket_id} with the new assignee.
        slots:
          ticket_id: path.ticket_id
      - text: Edit the fields of ticket {ticket_id} through the v2 update call.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Soft-delete a ticket (v2)
      effect: destructive
      questions:
      - Who is allowed to delete a ticket through the v2 API?
      - If I delete a ticket in v2, does it go to the deleted tickets view first?
      instructions:
      - text: Delete ticket {ticket_id} into the deleted tickets view.
        slots:
          ticket_id: path.ticket_id
      - text: Soft-delete v2 ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/collaborators'].get
  update:
    x-apievangelist-phrasing:
      intent: List a ticket's collaborators
      effect: read
      questions:
      - Who has been added as a collaborator on a ticket?
      - Can I see every collaborator attached to one ticket?
      instructions:
      - text: List the collaborators on ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Show who is collaborating on ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/email_ccs'].get
  update:
    x-apievangelist-phrasing:
      intent: List users CC'd on a ticket
      effect: read
      questions:
      - Which people are copied on the emails for a ticket?
      - Does listing email CCs require the CCs and Followers feature?
      instructions:
      - text: List the users cc'd on ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Show the email CCs for ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/followers'].get
  update:
    x-apievangelist-phrasing:
      intent: List a ticket's followers
      effect: read
      questions:
      - Which agents are following a ticket for updates?
      - Can I see who follows a ticket without being cc'd on it?
      instructions:
      - text: List the followers of ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Show which users follow ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/incidents'].get
  update:
    x-apievangelist-phrasing:
      intent: List incidents linked to a problem ticket
      effect: read
      questions:
      - What incident tickets are attached to a given problem?
      - Can I page through all incidents linked to one problem ticket?
      instructions:
      - text: List the incidents linked to problem ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Show every incident filed under problem {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/mark_as_spam'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark a ticket as spam and suspend its requester
      effect: destructive
      questions:
      - Can I flag one ticket as spam and block the person who sent it?
      - What happens to the requester when a ticket is marked as spam?
      instructions:
      - text: Mark ticket {ticket_id} as spam and suspend the requester.
        slots:
          ticket_id: path.ticket_id
      - text: Flag ticket {ticket_id} as spam.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/merge'].post
  update:
    x-apievangelist-phrasing:
      intent: Merge tickets into another ticket
      effect: destructive
      questions:
      - Can I combine duplicate tickets into a single ticket?
      - What rules apply when merging several tickets into one target?
      instructions:
      - text: Merge these duplicate tickets into ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Fold the other open tickets into target ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/related'].get
  update:
    x-apievangelist-phrasing:
      intent: Get related information for a ticket
      effect: read
      questions:
      - What related data, like incident counts or linked topics, exists for a ticket?
      - Can I see how many incidents and followups relate to a ticket?
      instructions:
      - text: Get the related information for ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Show what is related to ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count tickets in the account
      effect: read
      questions:
      - Roughly how many tickets does my account have?
      - How fresh is the ticket count when there are more than 100,000 tickets?
      instructions:
      - text: Count the tickets in my account.
      - text: Give me the approximate total number of tickets.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/create_many'].post
  update:
    x-apievangelist-phrasing:
      intent: Create up to 100 tickets at once
      effect: write
      questions:
      - Can I create a batch of tickets in one request?
      - Will bulk-created tickets trigger business rules and email end users?
      instructions:
      - text: Create these 50 tickets in one batch.
      - text: Bulk create tickets from this list of customer issues.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/destroy_many'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete many tickets at once
      effect: destructive
      questions:
      - Can I delete up to 100 tickets by id in one call?
      - Who has permission to bulk delete tickets?
      instructions:
      - text: Delete all of these tickets by id in one request.
      - text: Bulk delete the test tickets in this id list.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/mark_many_as_spam'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark many tickets as spam
      effect: destructive
      questions:
      - Can I mark a whole batch of tickets as spam in one go?
      - Does marking many tickets as spam run as a background job?
      instructions:
      - text: Mark all of these tickets as spam and suspend their requesters.
      - text: Flag this list of ticket ids as spam in bulk.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/show_many'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several tickets by id
      effect: read
      questions:
      - Can I fetch a handful of specific tickets by id in one request?
      - What is the most tickets I can retrieve with a comma-separated id list?
      instructions:
      - text: Fetch the tickets with these ids.
      - text: Show me tickets 12, 15 and 21 together.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/update_many'].put
  update:
    x-apievangelist-phrasing:
      intent: Update many tickets at once
      effect: write
      questions:
      - Can I change the status of up to 100 tickets in one request?
      - Is there a bulk update that applies the same change to a list of ticket ids?
      instructions:
      - text: Apply the same update to tickets {ids}.
        slots:
          ids: query.ids
      - text: Set tickets {ids} to solved in bulk.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tickets'].get
  update:
    x-apievangelist-phrasing:
      intent: List tickets with sorting and page size
      effect: read
      questions:
      - Can I sort the ticket list and choose how many come back per page?
      - Are tickets listed oldest-created first by default on the unversioned endpoint?
      instructions:
      - text: List tickets sorted by {sort_by} in {sort_order} order.
        slots:
          sort_by: query.sort_by
          sort_order: query.sort_order
      - text: Show page {page} of tickets with {per_page} per page.
        slots:
          page: query.page
          per_page: query.per_page
      - text: Find tickets whose external id is {external_id}, sideloading users and groups.
        slots:
          external_id: query.external_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tickets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a ticket with full details
      effect: write
      questions:
      - Can I set requester, priority, tags and custom fields while creating a ticket?
      - Is it possible to add a first comment in the same request that opens a ticket?
      instructions:
      - text: 'Create a ticket with these requester, subject and priority details: {ticket}.'
        slots:
          ticket: requestBody.ticket
      - text: 'Open a high-priority ticket with custom fields and an opening comment: {ticket}.'
        slots:
          ticket: requestBody.ticket
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tickets/{ticket_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Show a ticket's details
      effect: read
      questions:
      - Where can I see all the details of one ticket?
      - Can I retrieve one specific ticket by its number?
      instructions:
      - text: Show me ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Retrieve the full details of ticket number {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tickets/{ticket_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update, solve or close a ticket
      effect: write
      questions:
      - Can I mark a ticket solved or closed while adding a comment?
      - Which fields can I change on a ticket, like priority, assignee or tags?
      instructions:
      - text: 'Set ticket {ticket_id} to solved with this change: {ticket}.'
        slots:
          ticket_id: path.ticket_id
          ticket: requestBody.ticket
      - text: Change the priority and assignee of ticket {ticket_id} to {ticket}.
        slots:
          ticket_id: path.ticket_id
          ticket: requestBody.ticket
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tickets/{ticket_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a ticket
      effect: destructive
      questions:
      - Is deleting a ticket through the unversioned endpoint reversible?
      - Can I remove a ticket so it is gone for good in one step?
      instructions:
      - text: Delete ticket {ticket_id} permanently, with no recovery.
        slots:
          ticket_id: path.ticket_id
      - text: Irreversibly remove ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tickets/{ticket_id}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List the comments on a ticket
      effect: read
      questions:
      - What has been said in the conversation on a ticket?
      - Can I read a ticket's comments newest first?
      instructions:
      - text: List the comments on ticket {ticket_id}.
        slots:
          ticket_id: path.ticket_id
      - text: Show page {page} of comments on ticket {ticket_id} in {sort_order} order.
        slots:
          page: query.page
          ticket_id: path.ticket_id
          sort_order: query.sort_order
      method: generated
      generated: '2026-09-26'