# 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 (apps)…
  version: 1.0.0
extends: openapi/jira-issue-custom-field-options-apps-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: 8
- target: $.paths['/rest/api/3/field/{fieldKey}/option'].get
  update:
    x-apievangelist-phrasing:
      intent: List all options of an app's select field
      effect: read
      questions:
      - How do I list every option my Connect app added to its select list issue field?
      - Does the full option list work for select fields created in Jira itself?
      instructions:
      - text: List all options of app issue field {fieldKey}.
        slots:
          fieldKey: path.fieldKey
      - text: Show {maxResults} options of select field {fieldKey} starting at {startAt}.
        slots:
          maxResults: query.maxResults
          fieldKey: path.fieldKey
          startAt: query.startAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldKey}/option'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an option to an app's select field
      effect: write
      questions:
      - How can my Connect app add a new choice to its select list issue field?
      - Can I limit a new field option to certain projects when creating it?
      instructions:
      - text: Add option {value} to app issue field {fieldKey}.
        slots:
          value: requestBody.value
          fieldKey: path.fieldKey
      - text: Create option {value} in select field {fieldKey}, available only in {config}.
        slots:
          value: requestBody.value
          fieldKey: path.fieldKey
          config: requestBody.config
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/suggestions/edit'].get
  update:
    x-apievangelist-phrasing:
      intent: List field options the user can select
      effect: read
      questions:
      - Which options of an app select field can the current user pick when editing an issue?
      - Can I narrow selectable field options to a single project?
      instructions:
      - text: List options the user can select for field {fieldKey}.
        slots:
          fieldKey: path.fieldKey
      - text: Show selectable options of field {fieldKey} in project {projectId}.
        slots:
          fieldKey: path.fieldKey
          projectId: query.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/suggestions/search'].get
  update:
    x-apievangelist-phrasing:
      intent: List field options the user can view
      effect: read
      questions:
      - Which options of an app select field is the current user allowed to see, even ones they cannot select?
      - Can I list viewable field options for one project only?
      instructions:
      - text: List the options of field {fieldKey} the user can view.
        slots:
          fieldKey: path.fieldKey
      - text: Show visible options of select field {fieldKey} for project {projectId}.
        slots:
          fieldKey: path.fieldKey
          projectId: query.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/{optionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one option of an app's select field
      effect: read
      questions:
      - How do I read a single option's name and properties from my app's select field?
      - Which projects is a specific field option available in?
      instructions:
      - text: Get option {optionId} of field {fieldKey}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
      - text: Show the configuration of option {optionId} in app field {fieldKey}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/{optionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update or create a field option by ID
      effect: write
      questions:
      - How do I rename an existing option in my app's select field?
      - Can I create a field option with an ID I choose myself?
      instructions:
      - text: Rename option {optionId} of field {fieldKey} to {value}, with body id {id}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
          value: requestBody.value
          id: requestBody.id
      - text: Upsert option {optionId} named {value} in field {fieldKey}, using the same {id} in the body.
        slots:
          optionId: path.optionId
          value: requestBody.value
          fieldKey: path.fieldKey
          id: requestBody.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/{optionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an option from an app's select field
      effect: destructive
      questions:
      - How do I remove a choice from my app's select list field?
      - Can a Connect app delete options it previously added to its field?
      instructions:
      - text: Delete option {optionId} from field {fieldKey}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
      - text: Remove the {optionId} choice from app select field {fieldKey}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/{optionId}/issue'].delete
  update:
    x-apievangelist-phrasing:
      intent: Deselect an option on issues, optionally replacing it
      effect: destructive
      questions:
      - How do I swap one select option for another on every issue that uses it?
      - Can I limit the option replacement to issues matching a JQL query?
      - Is it possible to edit hidden fields while replacing a field option on issues?
      instructions:
      - text: Deselect option {optionId} of field {fieldKey} on all issues and select {replaceWith} instead.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
          replaceWith: query.replaceWith
      - text: Replace option {optionId} in field {fieldKey} with {replaceWith} only on issues matching {jql}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
          replaceWith: query.replaceWith
          jql: query.jql
      method: generated
      generated: '2026-09-26'