# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Zendesk Ticket Fields API
  version: 1.0.0
extends: openapi/zendesk-ticket-fields-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: 11
- target: $.paths['/api/v2/ticket_fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List system and custom ticket fields
      effect: read
      questions:
      - What custom ticket fields do we have in Zendesk?
      - Which ticket fields can end users see in the help center?
      - Can I get ticket field titles translated into a specific locale?
      instructions:
      - text: List all ticket fields with titles in {locale}.
        slots:
          locale: query.locale
      - text: List every system and custom ticket field in the account.
      - text: Show all ticket fields and sideload their creators when {creator} is set.
        slots:
          creator: query.creator
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/ticket_fields'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom ticket field
      effect: write
      questions:
      - How do I add a drop-down custom field to tickets?
      - What custom field types can I create, like checkbox, date or multi-select?
      instructions:
      - text: Create a drop-down ticket field called Product Area.
      - text: Add a checkbox custom field named Escalated to our tickets.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/ticket_fields/{ticket_field_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one ticket field
      effect: read
      questions:
      - How can I see the settings of one specific ticket field?
      - Can I sideload the user who created a ticket field?
      instructions:
      - text: Show the Product Area ticket field.
      - text: Get that ticket field's configuration and creator.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/ticket_fields/{ticket_field_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a ticket field or its options
      effect: write
      questions:
      - Can I add or remove drop-down options by updating the whole ticket field?
      - What's the catch when replacing options on a multi-select field via update?
      instructions:
      - text: Rename the Product Area ticket field to Product.
      - text: Replace the full option list on that drop-down field in one update.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/ticket_fields/{ticket_field_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom ticket field
      effect: destructive
      questions:
      - Can I delete a custom ticket field we no longer use?
      - Who has permission to remove a ticket field?
      instructions:
      - text: Delete the Legacy SKU ticket field.
      - text: Remove that custom field from tickets entirely.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/ticket_fields/{ticket_field_id}/options'].get
  update:
    x-apievangelist-phrasing:
      intent: List options of a drop-down ticket field
      effect: read
      questions:
      - What choices are in a drop-down ticket field?
      - Can I page through a custom field's options with cursor pagination?
      instructions:
      - text: List the options in the Product Area drop-down.
      - text: Show all choices defined on that custom drop-down field.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/ticket_fields/{ticket_field_id}/options'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or edit one drop-down field option
      effect: write
      questions:
      - How do I add a single new choice to a drop-down field without resending the rest?
      - If an option already exists, does posting it again update it?
      instructions:
      - text: Add a Pineapples option to the Fruit drop-down field.
      - text: Update just that one option's name on the custom field.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/ticket_fields/{ticket_field_id}/options/{ticket_field_option_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one drop-down field option
      effect: read
      questions:
      - How do I look up a single option on a drop-down ticket field?
      - What value tag does a specific field option use?
      instructions:
      - text: Show the Hardware option on the Product Area field.
      - text: Get that one field option's name and value.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/ticket_fields/{ticket_field_id}/options/{ticket_field_option_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a drop-down field option
      effect: destructive
      questions:
      - Can I remove one choice from a drop-down field?
      - Who can delete an option on a custom ticket field?
      instructions:
      - text: Delete the Discontinued option from the Product Area field.
      - text: Remove that single choice from the drop-down.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/ticket_fields/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count ticket fields
      effect: read
      questions:
      - How many ticket fields does our account have?
      - Is the ticket field count cached for very large accounts?
      instructions:
      - text: Count the system and custom ticket fields in our account.
      - text: Give me the approximate number of ticket fields.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/ticket_fields/reorder'].put
  update:
    x-apievangelist-phrasing:
      intent: Reorder ticket fields
      effect: write
      questions:
      - Can I change the order ticket fields appear in?
      - How do I set a new display sequence for ticket fields?
      instructions:
      - text: Reorder the ticket fields so Priority comes before Product Area.
      - text: Set the ticket field order to the id list I give you.
      method: generated
      generated: '2026-09-26'