# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Jira Cloud platform REST Issue custom field options API
  version: 1.0.0
extends: openapi/jira-issue-custom-field-options-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['/rest/api/3/customFieldOption/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom field option by ID
      effect: read
      questions:
      - How do I look up a single select list option by its option ID?
      - Which custom field and value does an option ID belong to?
      instructions:
      - text: Show custom field option {id}.
        slots:
          id: path.id
      - text: Look up the value of select option {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldId}/context/{contextId}/option'].get
  update:
    x-apievangelist-phrasing:
      intent: List options of a custom field context
      effect: read
      questions:
      - What options are available in a select field for a given context?
      - Can I list only top-level options and skip cascading ones?
      instructions:
      - text: List options for field {fieldId} in context {contextId}.
        slots:
          fieldId: path.fieldId
          contextId: path.contextId
      - text: Show options of field {fieldId} context {contextId} with onlyOptions {onlyOptions}.
        slots:
          fieldId: path.fieldId
          contextId: path.contextId
          onlyOptions: query.onlyOptions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldId}/context/{contextId}/option'].put
  update:
    x-apievangelist-phrasing:
      intent: Update select options in a field context
      effect: write
      questions:
      - How do I rename or disable existing options in a select field?
      - What happens if one of the options I update isn't found?
      instructions:
      - text: Update options {options} on field {fieldId} context {contextId}.
        slots:
          options: requestBody.options
          fieldId: path.fieldId
          contextId: path.contextId
      - text: Rename existing select options in field {fieldId}, context {contextId}.
        slots:
          fieldId: path.fieldId
          contextId: path.contextId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldId}/context/{contextId}/option'].post
  update:
    x-apievangelist-phrasing:
      intent: Add options to a select field context
      effect: write
      questions:
      - How do I add new choices to a dropdown custom field?
      - Can I create cascading options too?
      instructions:
      - text: Add options {options} to field {fieldId} in context {contextId}.
        slots:
          options: requestBody.options
          fieldId: path.fieldId
          contextId: path.contextId
      - text: Create new dropdown choices for field {fieldId}, context {contextId}.
        slots:
          fieldId: path.fieldId
          contextId: path.contextId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldId}/context/{contextId}/option/move'].put
  update:
    x-apievangelist-phrasing:
      intent: Reorder options in a field context
      effect: write
      questions:
      - How do I change the order options appear in a select field?
      - Can I move options to the first or last position?
      instructions:
      - text: Move options {customFieldOptionIds} to {position} in field {fieldId} context {contextId}.
        slots:
          customFieldOptionIds: requestBody.customFieldOptionIds
          position: requestBody.position
          fieldId: path.fieldId
          contextId: path.contextId
      - text: Place options {customFieldOptionIds} after {after} in field {fieldId} context {contextId}.
        slots:
          customFieldOptionIds: requestBody.customFieldOptionIds
          after: requestBody.after
          fieldId: path.fieldId
          contextId: path.contextId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldId}/context/{contextId}/option/{optionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a select option from a field context
      effect: destructive
      questions:
      - How do I remove a choice from a dropdown custom field?
      - Can I delete an option that still has cascading options?
      instructions:
      - text: Delete option {optionId} from field {fieldId} context {contextId}.
        slots:
          optionId: path.optionId
          fieldId: path.fieldId
          contextId: path.contextId
      - text: Remove choice {optionId} in field {fieldId}, context {contextId}.
        slots:
          optionId: path.optionId
          fieldId: path.fieldId
          contextId: path.contextId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldId}/context/{contextId}/option/{optionId}/issue'].delete
  update:
    x-apievangelist-phrasing:
      intent: Replace an option's value on issues
      effect: destructive
      questions:
      - How do I swap one select option for another on all issues that use it?
      - Can I limit which issues get the replacement option with JQL?
      instructions:
      - text: Replace option {optionId} with {replaceWith} on issues for field {fieldId} context {contextId}.
        slots:
          optionId: path.optionId
          replaceWith: query.replaceWith
          fieldId: path.fieldId
          contextId: path.contextId
      - text: Swap option {optionId} in field {fieldId} context {contextId} on issues matching {jql}.
        slots:
          optionId: path.optionId
          fieldId: path.fieldId
          contextId: path.contextId
          jql: query.jql
      method: generated
      generated: '2026-09-26'