# 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 Screens API
  version: 1.0.0
extends: openapi/atlassian-screens-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: 7
- target: $.paths['/rest/api/3/field/{fieldId}/screens'].get
  update:
    x-apievangelist-phrasing:
      intent: List the screens a field appears on
      effect: read
      questions:
      - Which Jira screens is this custom field used on?
      - Before removing a field, how can I see every screen that shows it?
      instructions:
      - text: List the screens that use field {fieldId}.
        slots:
          fieldId: path.fieldId
      - text: Show where field {fieldId} appears, with {expand} expanded.
        slots:
          fieldId: path.fieldId
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/screens'].get
  update:
    x-apievangelist-phrasing:
      intent: List or search screens
      effect: read
      questions:
      - What screens are configured in my Jira site?
      - Can I search screens by name or restrict them by scope?
      instructions:
      - text: List all Jira screens.
      - text: Find screens whose name contains {queryString}.
        slots:
          queryString: query.queryString
      - text: Get screens with ids {id}.
        slots:
          id: query.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/screens'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a screen
      effect: write
      questions:
      - How do I create a new Jira screen?
      - Does a newly created screen come with a field tab?
      instructions:
      - text: Create a screen named {name}.
        slots:
          name: requestBody.name
      - text: Create screen {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/screens/addToDefault/{fieldId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a field to the default screen
      effect: write
      questions:
      - How do I put a custom field on Jira's default screen?
      - Can I add a field to the default tab without picking a screen?
      instructions:
      - text: Add field {fieldId} to the default screen.
        slots:
          fieldId: path.fieldId
      - text: Put custom field {fieldId} on the default tab of the default screen.
        slots:
          fieldId: path.fieldId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/screens/{screenId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe a screen
      effect: write
      questions:
      - How do I rename a Jira screen?
      - Can screens in team-managed projects be updated?
      instructions:
      - text: Rename screen {screenId} to {name}.
        slots:
          screenId: path.screenId
          name: requestBody.name
      - text: Update the description of screen {screenId} to {description}.
        slots:
          screenId: path.screenId
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/screens/{screenId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a screen
      effect: destructive
      questions:
      - How do I delete a Jira screen I no longer need?
      - Why can't a screen be deleted while a workflow uses it?
      instructions:
      - text: Delete screen {screenId}.
        slots:
          screenId: path.screenId
      - text: Remove unused screen {screenId}.
        slots:
          screenId: path.screenId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/screens/{screenId}/availableFields'].get
  update:
    x-apievangelist-phrasing:
      intent: List fields that can be added to a screen
      effect: read
      questions:
      - Which fields aren't on this screen yet and can be added?
      - What fields are available to put on a screen tab?
      instructions:
      - text: List the fields available to add to screen {screenId}.
        slots:
          screenId: path.screenId
      - text: Show which fields I could add to a tab on screen {screenId}.
        slots:
          screenId: path.screenId
      method: generated
      generated: '2026-10-01'