# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Attribute Based Access Control Roles API
  version: 1.0.0
extends: openapi/adobe-suite-attribute-based-access-control-roles-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: 8
- target: $.paths['/administration/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List access control roles
      effect: read
      questions:
      - What roles exist in our Experience Platform access control setup?
      - How do I see all attribute-based access control roles for our organization?
      instructions:
      - text: List all roles in organization {org}.
        slots:
          org: header.x-gw-ims-org-id
      - text: Show every existing access control role.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/administration/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a role
      effect: write
      questions:
      - How do I create a new access control role?
      - Can I set a role's type and description when creating it?
      instructions:
      - text: Create a role named {name}.
        slots:
          name: requestBody.name
      - text: Create role {name} of type {roleType} described as {description}.
        slots:
          name: requestBody.name
          roleType: requestBody.roleType
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/administration/roles/{ROLE_ID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a role
      effect: read
      questions:
      - What are the details of one access control role, looked up by ID?
      - Can I look up a role by its ID?
      instructions:
      - text: Get role {ROLE_ID}.
        slots:
          ROLE_ID: path.ROLE_ID
      - text: Show me the details of role {ROLE_ID}.
        slots:
          ROLE_ID: path.ROLE_ID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/administration/roles/{ROLE_ID}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a role's name, description and type
      effect: write
      questions:
      - How do I fully update a role's name, description and type together?
      - Can I overwrite all of a role's properties at once?
      instructions:
      - text: Update role {ROLE_ID} to name {name}, description {description}, type {roleType}.
        slots:
          ROLE_ID: path.ROLE_ID
          name: requestBody.name
          description: requestBody.description
          roleType: requestBody.roleType
      - text: Replace role {ROLE_ID} with the name {name} and description {description} and type {roleType}.
        slots:
          ROLE_ID: path.ROLE_ID
          name: requestBody.name
          description: requestBody.description
          roleType: requestBody.roleType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/administration/roles/{ROLE_ID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a role
      effect: destructive
      questions:
      - Can I delete an access control role we no longer use?
      - Can I remove a role we no longer use?
      instructions:
      - text: Delete role {ROLE_ID}.
        slots:
          ROLE_ID: path.ROLE_ID
      - text: Remove access control role {ROLE_ID} permanently.
        slots:
          ROLE_ID: path.ROLE_ID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/administration/roles/{ROLE_ID}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch a single role property
      effect: write
      questions:
      - Can I change just one property of a role with a patch operation?
      - What's the way to update a role's description without touching the rest?
      instructions:
      - text: 'Patch role {ROLE_ID}: {op} {path} with value {value}.'
        slots:
          ROLE_ID: path.ROLE_ID
          op: requestBody.op
          path: requestBody.path
          value: requestBody.value
      - text: Replace the property at {path} on role {ROLE_ID} with {value} using op {op}.
        slots:
          ROLE_ID: path.ROLE_ID
          op: requestBody.op
          path: requestBody.path
          value: requestBody.value
      method: generated
      generated: '2026-09-26'
- target: $.paths['/administration/roles/{ROLE_ID}/subjects'].get
  update:
    x-apievangelist-phrasing:
      intent: List the users assigned to a role
      effect: read
      questions:
      - Which users are assigned to a given role?
      - Where do I see the subjects attached to an access control role?
      instructions:
      - text: List the subjects assigned to role {ROLE_ID}.
        slots:
          ROLE_ID: path.ROLE_ID
      - text: Show who has role {ROLE_ID}.
        slots:
          ROLE_ID: path.ROLE_ID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/administration/roles/{ROLE_ID}/subjects'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add or remove users on a role
      effect: write
      questions:
      - How do I add a user to an access control role?
      - Can I remove subjects from a role with a patch?
      instructions:
      - text: 'Update subjects on role {ROLE_ID}: {op} {path} with {value}.'
        slots:
          ROLE_ID: path.ROLE_ID
          op: requestBody.op
          path: requestBody.path
          value: requestBody.value
      - text: Add subject {value} to role {ROLE_ID} at path {path} using op {op}.
        slots:
          value: requestBody.value
          ROLE_ID: path.ROLE_ID
          path: requestBody.path
          op: requestBody.op
      method: generated
      generated: '2026-09-26'