# 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 Permission schemes API
  version: 1.0.0
extends: openapi/jira-permission-schemes-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: 9
- target: $.paths['/rest/api/3/permissionscheme'].get
  update:
    x-apievangelist-phrasing:
      intent: List all permission schemes
      effect: read
      questions:
      - What permission schemes exist on my Jira site?
      - Can I list permission schemes with their grants expanded?
      instructions:
      - text: List every permission scheme.
      - text: Show all permission schemes with {expand} expanded.
        slots:
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/permissionscheme'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a permission scheme
      effect: write
      questions:
      - How do I create a new permission scheme for a set of projects?
      - Can I create a permission scheme without any grants and add them later?
      instructions:
      - text: Create a permission scheme named {name}.
        slots:
          name: requestBody.name
      - text: Create permission scheme {name} with grants {permissions}.
        slots:
          name: requestBody.name
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a permission scheme
      effect: read
      questions:
      - What does a particular permission scheme contain?
      - Can I view one permission scheme's name and description by ID?
      instructions:
      - text: Get permission scheme {schemeId}.
        slots:
          schemeId: path.schemeId
      - text: Show permission scheme {schemeId} with {expand} expanded.
        slots:
          schemeId: path.schemeId
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a permission scheme
      effect: write
      questions:
      - Will sending a permissions list when updating a scheme overwrite all existing grants?
      - Can I rename a permission scheme without touching its grants?
      instructions:
      - text: Rename permission scheme {schemeId} to {name}.
        slots:
          schemeId: path.schemeId
          name: requestBody.name
      - text: Replace all grants in permission scheme {schemeId} ({name}) with {permissions}.
        slots:
          schemeId: path.schemeId
          name: requestBody.name
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a permission scheme
      effect: destructive
      questions:
      - How do I delete a permission scheme that's no longer needed?
      - Is deleting a permission scheme limited to Jira administrators?
      instructions:
      - text: Delete permission scheme {schemeId}.
        slots:
          schemeId: path.schemeId
      - text: Remove the permission scheme with ID {schemeId}.
        slots:
          schemeId: path.schemeId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}/permission'].get
  update:
    x-apievangelist-phrasing:
      intent: List grants in a permission scheme
      effect: read
      questions:
      - Who is granted which permissions in a given scheme?
      - Can I see every holder and permission pair in a permission scheme?
      instructions:
      - text: List all grants in permission scheme {schemeId}.
        slots:
          schemeId: path.schemeId
      - text: Show the permission holders for scheme {schemeId} with {expand} expanded.
        slots:
          schemeId: path.schemeId
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}/permission'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a permission grant to a scheme
      effect: write
      questions:
      - How do I give a group Browse Projects permission in a scheme?
      - Can I add a single grant to a permission scheme without replacing the others?
      instructions:
      - text: Grant {permission} to {holder} in permission scheme {schemeId}.
        slots:
          permission: requestBody.permission
          holder: requestBody.holder
          schemeId: path.schemeId
      - text: Add a new grant of {permission} for holder {holder} to scheme {schemeId}.
        slots:
          permission: requestBody.permission
          holder: requestBody.holder
          schemeId: path.schemeId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}/permission/{permissionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one permission grant
      effect: read
      questions:
      - What holder and permission does a specific grant define?
      - Can I look up a single grant within a permission scheme by its ID?
      instructions:
      - text: Get grant {permissionId} in permission scheme {schemeId}.
        slots:
          permissionId: path.permissionId
          schemeId: path.schemeId
      - text: Show the details of permission grant {permissionId} from scheme {schemeId}.
        slots:
          permissionId: path.permissionId
          schemeId: path.schemeId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}/permission/{permissionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a grant from a permission scheme
      effect: destructive
      questions:
      - How do I revoke one permission grant from a scheme?
      - Can I delete a single grant while leaving the rest of the scheme intact?
      instructions:
      - text: Delete grant {permissionId} from permission scheme {schemeId}.
        slots:
          permissionId: path.permissionId
          schemeId: path.schemeId
      - text: Revoke permission grant {permissionId} in scheme {schemeId}.
        slots:
          permissionId: path.permissionId
          schemeId: path.schemeId
      method: generated
      generated: '2026-09-26'