# 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 fields API
  version: 1.0.0
extends: openapi/jira-issue-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['/rest/api/3/field'].get
  update:
    x-apievangelist-phrasing:
      intent: List all system and custom issue fields
      effect: read
      questions:
      - What system and custom fields exist on my Jira site?
      - Can I get the full field list in one call without paging?
      instructions:
      - text: List every system and custom issue field.
      - text: Get all issue fields so I can find a custom field's ID.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom field
      effect: write
      questions:
      - How do I add a new custom field to issues?
      - Which searcher can I choose when creating a custom field?
      instructions:
      - text: Create a custom field named {name} of type {type}.
        slots:
          name: requestBody.name
          type: requestBody.type
      - text: Create custom field {name} of type {type} with searcher {searcherKey} and description {description}.
        slots:
          name: requestBody.name
          type: requestBody.type
          searcherKey: requestBody.searcherKey
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search fields page by page
      effect: read
      questions:
      - How do I search for fields whose name contains a word?
      - Can I page through only the custom fields used by certain projects?
      instructions:
      - text: Search fields matching {query}.
        slots:
          query: query.query
      - text: List fields of type {type} for projects {projectIds}, ordered by {orderBy}.
        slots:
          type: query.type
          projectIds: query.projectIds
          orderBy: query.orderBy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/search/trashed'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom fields in the trash
      effect: read
      questions:
      - Which custom fields are currently in the trash?
      - Can I search trashed fields by name?
      instructions:
      - text: List the custom fields in the trash.
      - text: Find trashed fields matching {query}.
        slots:
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom field's name, description or searcher
      effect: write
      questions:
      - How do I rename a custom field?
      - Can I change a custom field's searcher after it's created?
      instructions:
      - text: Rename custom field {fieldId} to {name}.
        slots:
          fieldId: path.fieldId
          name: requestBody.name
      - text: Change custom field {fieldId}'s description to {description} and searcher to {searcherKey}.
        slots:
          fieldId: path.fieldId
          description: requestBody.description
          searcherKey: requestBody.searcherKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldId}/association/project'].get
  update:
    x-apievangelist-phrasing:
      intent: List projects a custom field is associated with
      effect: read
      questions:
      - Which projects is a custom field associated with?
      - Can I page through the project associations of a field?
      instructions:
      - text: List the projects associated with custom field {fieldId}.
        slots:
          fieldId: path.fieldId
      - text: Show project associations for field {fieldId}, {maxResults} per page.
        slots:
          fieldId: path.fieldId
          maxResults: query.maxResults
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{fieldId}/contexts'].get
  update:
    x-apievangelist-phrasing:
      intent: List a field's contexts via the deprecated endpoint
      effect: read
      questions:
      - Is there an older deprecated endpoint that lists the contexts a field is used in?
      - Does the legacy field contexts call still page its results?
      instructions:
      - text: Using the deprecated contexts endpoint, list the contexts field {fieldId} is used in.
        slots:
          fieldId: path.fieldId
      - text: Call the legacy /contexts path for field {fieldId} starting at {startAt}.
        slots:
          fieldId: path.fieldId
          startAt: query.startAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a custom field
      effect: destructive
      questions:
      - How do I permanently delete a custom field, even if it's in the trash?
      - Is deleting a custom field reversible?
      instructions:
      - text: Permanently delete custom field {id}.
        slots:
          id: path.id
      - text: Delete custom field {id} for good, whether trashed or not.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a custom field from the trash
      effect: write
      questions:
      - Can I recover a custom field I moved to the trash?
      - How do I undo trashing a custom field?
      instructions:
      - text: Restore custom field {id} from the trash.
        slots:
          id: path.id
      - text: Bring trashed field {id} back.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/field/{id}/trash'].post
  update:
    x-apievangelist-phrasing:
      intent: Move a custom field to the trash
      effect: write
      questions:
      - How do I move a custom field to the trash without deleting it permanently?
      - What's the recoverable way to retire a custom field?
      instructions:
      - text: Move custom field {id} to the trash.
        slots:
          id: path.id
      - text: Trash field {id} so it can be restored later.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/projects/fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List fields available for projects and work types
      effect: read
      questions:
      - Which fields are available for a given project and work type combination?
      - Can I check whether a specific field is available for certain work types?
      instructions:
      - text: List the fields available in project {projectId} for work type {workTypeId}.
        slots:
          projectId: query.projectId
          workTypeId: query.workTypeId
      - text: Check if field {fieldId} is available for project {projectId} and work type {workTypeId}.
        slots:
          fieldId: query.fieldId
          projectId: query.projectId
          workTypeId: query.workTypeId
      method: generated
      generated: '2026-09-26'