# 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 Permission Schemes…
  version: 1.0.0
extends: openapi/atlassian-permission-schemes-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/permissionscheme'].get
  update:
    x-apievangelist-phrasing:
      intent: List all permission schemes
      effect: read
      questions:
      - Which permission schemes are defined in my Jira site?
      - Can I list permission schemes with their grants expanded?
      instructions:
      - text: List all permission schemes.
      - text: Show every permission scheme with {expand} expanded.
        slots:
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- 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 Jira permission scheme?
      - Can I create a permission scheme with no grants and add them later?
      instructions:
      - text: Create permission scheme {name}.
        slots:
          name: requestBody.name
      - text: Create permission scheme {name} with grants {permissions}.
        slots:
          name: requestBody.name
          permissions: requestBody.permissions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a permission scheme
      effect: read
      questions:
      - How do I look up a single permission scheme by id?
      - What name and description does this permission scheme have?
      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-10-01'
- 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 overwrite all existing grants in the scheme?
      - How do 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 scheme {schemeId} named {name} with {permissions}.
        slots:
          schemeId: path.schemeId
          name: requestBody.name
          permissions: requestBody.permissions
      method: generated
      generated: '2026-10-01'
- 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 used?
      - Who is allowed to remove a Jira permission scheme?
      instructions:
      - text: Delete permission scheme {schemeId}.
        slots:
          schemeId: path.schemeId
      - text: Remove the unused permission scheme {schemeId}.
        slots:
          schemeId: path.schemeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}/permission'].get
  update:
    x-apievangelist-phrasing:
      intent: List the grants in a permission scheme
      effect: read
      questions:
      - Who has which permission under this scheme?
      - What grants does a permission scheme contain?
      instructions:
      - text: List all permission grants in scheme {schemeId}.
        slots:
          schemeId: path.schemeId
      - text: Show the holders and permissions granted by scheme {schemeId}.
        slots:
          schemeId: path.schemeId
      method: generated
      generated: '2026-10-01'
- 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 a permission inside a permission scheme?
      - Can I add a single grant without rewriting the whole scheme?
      instructions:
      - text: Grant {permission} to holder {holder} in scheme {schemeId}.
        slots:
          permission: requestBody.permission
          holder: requestBody.holder
          schemeId: path.schemeId
      - text: Add a new grant of {permission} to permission scheme {schemeId}.
        slots:
          permission: requestBody.permission
          schemeId: path.schemeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}/permission/{permissionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one permission grant
      effect: read
      questions:
      - How do I inspect a single grant inside a permission scheme?
      - Which holder does this permission grant apply to?
      instructions:
      - text: Get grant {permissionId} in permission scheme {schemeId}.
        slots:
          permissionId: path.permissionId
          schemeId: path.schemeId
      - text: Show me permission grant {permissionId} of scheme {schemeId}.
        slots:
          permissionId: path.permissionId
          schemeId: path.schemeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/permissionscheme/{schemeId}/permission/{permissionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a permission grant from a scheme
      effect: destructive
      questions:
      - How do I revoke one grant from a permission scheme?
      - Can I remove a single holder's permission without editing the whole scheme?
      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-10-01'