# 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 Fields API
  version: 1.0.0
extends: openapi/atlassian-issue-fields-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: 9
- target: $.paths['/rest/api/3/field'].get
  update:
    x-apievangelist-phrasing:
      intent: List all system and custom issue fields
      effect: read
      questions:
      - What fields, system and custom, exist on Jira issues in my site?
      - Where can I find the ID of a custom field like Story Points?
      instructions:
      - text: List every system and custom issue field in Jira.
      - text: Give me the full unpaginated field list so I can find custom field IDs.
      method: generated
      generated: '2026-10-01'
- 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 Jira issues?
      - Which searcher should I attach when creating a custom field?
      instructions:
      - text: Create a custom field named {name} of type {type}.
        slots:
          name: requestBody.name
          type: requestBody.type
      - text: Add 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-10-01'
- target: $.paths['/rest/api/3/field/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search fields with filters and paging
      effect: read
      questions:
      - Can I search Jira fields by name and only get custom ones?
      - Is there a paginated way to list fields ordered by how often they're used?
      instructions:
      - text: Search fields whose name or description contains {query}.
        slots:
          query: query.query
      - text: List {type} fields ordered by {orderBy}, {maxResults} per page.
        slots:
          type: query.type
          orderBy: query.orderBy
          maxResults: query.maxResults
      method: generated
      generated: '2026-10-01'
- 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 sitting in the trash right now?
      - Can I search trashed fields by name before restoring one?
      instructions:
      - text: List the custom fields currently in the trash.
      - text: Find trashed custom fields matching {query}.
        slots:
          query: query.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/field/{fieldId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom field's name or searcher
      effect: write
      questions:
      - How do I rename an existing custom field?
      - Can I change the searcher on a custom field after it's created?
      instructions:
      - text: Rename custom field {fieldId} to {name}.
        slots:
          fieldId: path.fieldId
          name: requestBody.name
      - text: Change the searcher of custom field {fieldId} to {searcherKey}.
        slots:
          fieldId: path.fieldId
          searcherKey: requestBody.searcherKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/field/{fieldId}/contexts'].get
  update:
    x-apievangelist-phrasing:
      intent: List a field's contexts (deprecated)
      effect: read
      questions:
      - Which contexts is a custom field used in, using the older contexts endpoint?
      - Is the older per-field contexts list deprecated in favour of the newer custom field contexts call?
      instructions:
      - text: List the contexts field {fieldId} is used in via the deprecated endpoint.
        slots:
          fieldId: path.fieldId
      - text: Get {maxResults} legacy contexts for custom field {fieldId}.
        slots:
          maxResults: query.maxResults
          fieldId: path.fieldId
      method: generated
      generated: '2026-10-01'
- 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 not in the trash?
      - Is deleting a custom field done as an asynchronous task?
      instructions:
      - text: Permanently delete custom field {id}.
        slots:
          id: path.id
      - text: Erase custom field {id} for good, bypassing the trash.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/field/{id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a custom field from trash
      effect: write
      questions:
      - Can I bring back a custom field I moved to the trash?
      - How do I undo trashing a Jira custom field?
      instructions:
      - text: Restore custom field {id} from the trash.
        slots:
          id: path.id
      - text: Recover trashed field {id} so it's usable again.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/field/{id}/trash'].post
  update:
    x-apievangelist-phrasing:
      intent: Move a custom field to trash
      effect: write
      questions:
      - What's the recoverable way to get rid of a custom field?
      - Can I trash a custom field instead of deleting it outright?
      instructions:
      - text: Move custom field {id} to the trash.
        slots:
          id: path.id
      - text: Trash field {id} so it can still be restored later.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'