# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Atlassian The Jira Cloud platform REST Issue Custom Field…
  version: 1.0.0
extends: openapi/atlassian-issue-custom-field-options-apps-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      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-list field
      effect: read
      questions:
      - What options exist in my Connect app's select list issue field?
      - Can I page through every option of an app-defined issue field?
      instructions:
      - text: List all options for issue field {fieldKey}.
        slots:
          fieldKey: path.fieldKey
      - text: Page through options of app field {fieldKey} starting at {startAt}.
        slots:
          fieldKey: path.fieldKey
          startAt: query.startAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/field/{fieldKey}/option'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an option to an app's select-list field
      effect: write
      questions:
      - How does my Connect app add a new choice to its select list issue field?
      - Can I attach properties to an option when creating it?
      instructions:
      - text: Create option {value} on issue field {fieldKey}.
        slots:
          value: requestBody.value
          fieldKey: path.fieldKey
      - text: Add option {value} to app field {fieldKey} with properties {properties}.
        slots:
          value: requestBody.value
          fieldKey: path.fieldKey
          properties: requestBody.properties
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/suggestions/edit'].get
  update:
    x-apievangelist-phrasing:
      intent: List options a user can select when editing
      effect: read
      questions:
      - Which app field options can the current user pick when editing an issue?
      - Can I limit selectable options to those valid in one project?
      instructions:
      - text: List the selectable options for field {fieldKey}.
        slots:
          fieldKey: path.fieldKey
      - text: Show options of {fieldKey} I can select in project {projectId}.
        slots:
          fieldKey: path.fieldKey
          projectId: query.projectId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/suggestions/search'].get
  update:
    x-apievangelist-phrasing:
      intent: List options a user can view
      effect: read
      questions:
      - Which app field options is the current user allowed to see, even if not select?
      - Can I list viewable options for a field within one project?
      instructions:
      - text: List the visible options for field {fieldKey}.
        slots:
          fieldKey: path.fieldKey
      - text: Show options of {fieldKey} viewable in project {projectId}.
        slots:
          fieldKey: path.fieldKey
          projectId: query.projectId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/{optionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one option of an app's select-list field
      effect: read
      questions:
      - How do I fetch a single app field option by id?
      - What value and config does this select list option have?
      instructions:
      - text: Get option {optionId} of issue field {fieldKey}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
      - text: Show me app field option {optionId} on {fieldKey}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/{optionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update or upsert an app field option by id
      effect: write
      questions:
      - How do I change the label of an existing app field option?
      - Can I create an option with an id I choose myself?
      instructions:
      - text: Set option {optionId} on field {fieldKey} to value {value} with body id {id}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
          value: requestBody.value
          id: requestBody.id
      - text: Upsert option {optionId} of {fieldKey} with value {value}, matching id {id}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
          value: requestBody.value
          id: requestBody.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/field/{fieldKey}/option/{optionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an option from an app's select-list field
      effect: destructive
      questions:
      - How do I remove an option from my app's select list field?
      - Can a Connect app delete a field option it created?
      instructions:
      - text: Delete option {optionId} from issue field {fieldKey}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
      - text: Remove app field option {optionId} on {fieldKey}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
      method: generated
      generated: '2026-10-01'
- 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 app field option for another across all issues?
      - Can I limit an option replacement to issues matching a JQL query?
      instructions:
      - text: Replace option {optionId} of field {fieldKey} with {replaceWith} on all issues.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
          replaceWith: query.replaceWith
      - text: Deselect option {optionId} of {fieldKey} only on issues matching {jql}.
        slots:
          optionId: path.optionId
          fieldKey: path.fieldKey
          jql: query.jql
      method: generated
      generated: '2026-10-01'