API Evangelist conversational phrasing for dotCMS REST Permissions API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST Permissions API
  version: 1.0.0
extends: openapi/dotcms-permissions-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['/api/v1/permissions/{assetId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get permissions on an asset
      effect: read
      questions:
      - Which roles have access to this folder or page?
      - Can I page through the roles on an asset's permission list?
      instructions:
      - text: Get permissions for asset {assetId}.
        slots:
          assetId: path.assetId
      - text: Show page {page} of the roles with access to asset {assetId}.
        slots:
          page: query.page
          assetId: path.assetId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/permissions/{assetId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all permissions on an asset
      effect: write
      questions:
      - How do I overwrite every permission on an asset?
      - Can I cascade new asset permissions down to its children?
      instructions:
      - text: Replace permissions on asset {assetId} with {permissions}.
        slots:
          assetId: path.assetId
          permissions: requestBody.permissions
      - text: Set asset {assetId} permissions to {permissions} and cascade them.
        slots:
          assetId: path.assetId
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/permissions/_bycontent'].get
  update:
    x-apievangelist-phrasing:
      intent: Get permissions on a contentlet
      effect: read
      questions:
      - Who can read, edit or publish this piece of content?
      - Can I check only the publish permissions on a contentlet?
      instructions:
      - text: Get permissions for contentlet {contentletId}.
        slots:
          contentletId: query.contentletId
      - text: Show {type} permissions on content {contentletId}.
        slots:
          type: query.type
          contentletId: query.contentletId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/permissions/_bycontent/_groupbytype'].get
  update:
    x-apievangelist-phrasing:
      intent: Get contentlet permissions grouped by type
      effect: read
      questions:
      - Can I see a contentlet's roles grouped by READ, WRITE and PUBLISH?
      - Which roles fall under each permission type for this content?
      instructions:
      - text: Group the permissions on contentlet {contentletId} by type.
        slots:
          contentletId: query.contentletId
      - text: Show roles per permission type for content {contentletId}.
        slots:
          contentletId: query.contentletId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List available permission levels and scopes
      effect: read
      questions:
      - What permission levels and scopes can I assign in dotCMS?
      - Which scopes exist for granting roles access?
      instructions:
      - text: List the available permission levels and scopes.
      - text: Show the permission metadata.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/permissions/_bypermissiontype'].get
  update:
    x-apievangelist-phrasing:
      intent: Map permissions by permission type for a user
      effect: read
      questions:
      - Which permissionable types does a user have a given permission on?
      - Can I look up permissions filtered by permission type?
      instructions:
      - text: Get permissions of type {permissiontype} for user {userid}.
        slots:
          permissiontype: query.permissiontype
          userid: query.userid
      - text: Map {permission} permissions by type for user {userid}.
        slots:
          permission: query.permission
          userid: query.userid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/permissions/role/{roleId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a role's permissions across sites and folders
      effect: read
      questions:
      - Where does a role have permissions defined?
      - Which sites and folders can members of a role access?
      instructions:
      - text: Get the permissions of role {roleId}.
        slots:
          roleId: path.roleId
      - text: List every host and folder where role {roleId} has permissions.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/permissions/user/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's individual permissions
      effect: read
      questions:
      - What can a specific user access through their own role?
      - Can I page through a user's permissions by site and folder?
      instructions:
      - text: Get permissions for user {userId}.
        slots:
          userId: path.userId
      - text: Show page {page} of user {userId}'s permissions.
        slots:
          page: query.page
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/permissions/{assetId}/_reset'].put
  update:
    x-apievangelist-phrasing:
      intent: Reset an asset to inherited permissions
      effect: destructive
      questions:
      - How do I make a folder go back to inheriting its parent's permissions?
      - Can I remove all individual permissions from an asset?
      instructions:
      - text: Reset asset {assetId} to inherited permissions.
        slots:
          assetId: path.assetId
      - text: Remove custom permissions on {assetId} so it inherits again.
        slots:
          assetId: path.assetId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/permissions/role/{roleId}/asset/{assetId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a role's permissions on a site or folder
      effect: write
      questions:
      - How do I give a role access to a specific folder?
      - Can I change a role's permissions on a host and cascade them?
      instructions:
      - text: Set role {roleId} permissions on asset {assetId} to {permissions}.
        slots:
          roleId: path.roleId
          assetId: path.assetId
          permissions: requestBody.permissions
      - text: Grant role {roleId} {permissions} on folder {assetId} and cascade.
        slots:
          roleId: path.roleId
          permissions: requestBody.permissions
          assetId: path.assetId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/permissions/user/{userId}/asset/{assetId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a user's permissions on a site or folder
      effect: write
      questions:
      - How do I give one user direct access to a folder?
      - Can I assign permissions to a user's individual role on a host?
      instructions:
      - text: Set user {userId} permissions on asset {assetId} to {permissions}.
        slots:
          userId: path.userId
          assetId: path.assetId
          permissions: requestBody.permissions
      - text: Grant user {userId} {permissions} on folder {assetId}, cascading {cascade}.
        slots:
          userId: path.userId
          permissions: requestBody.permissions
          assetId: path.assetId
          cascade: requestBody.cascade
      method: generated
      generated: '2026-09-26'