# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Acquia Cloud API Documentation Teams and Permissions API
  version: 1.0.0
extends: openapi/acquia-teams-and-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: 17
- target: $.paths['/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List all available permissions
      effect: read
      questions:
      - What permissions exist in the Acquia Cloud Platform?
      - Can I see every permission a role could grant, even ones I don't have?
      instructions:
      - text: List every permission available in the system.
      - text: Show the full catalog of role permissions.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{roleUuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a role
      effect: read
      questions:
      - Which permissions does a particular role grant?
      - Can I look up a role by its UUID?
      instructions:
      - text: Show role {roleUuid}.
        slots:
          roleUuid: path.roleUuid
      - text: Get the permissions granted by role {roleUuid}.
        slots:
          roleUuid: path.roleUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{roleUuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a role
      effect: write
      questions:
      - Can I change which permissions a role grants?
      - How do I rename a custom role or edit its description?
      instructions:
      - text: Set role {roleUuid} permissions to {permissions}.
        slots:
          roleUuid: path.roleUuid
          permissions: requestBody.permissions
      - text: Rename role {roleUuid} to {name} with description {description}.
        slots:
          roleUuid: path.roleUuid
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{roleUuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a role
      effect: destructive
      questions:
      - How do I delete a custom role we no longer use?
      - Can I remove a role from my organization?
      instructions:
      - text: Delete role {roleUuid}.
        slots:
          roleUuid: path.roleUuid
      - text: Remove the role {roleUuid} from the organization.
        slots:
          roleUuid: path.roleUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams'].get
  update:
    x-apievangelist-phrasing:
      intent: List the teams I can access
      effect: read
      questions:
      - Which teams do I have access to?
      - Can I search my teams by name?
      instructions:
      - text: List all teams I have access to.
      - text: Show my teams matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a team
      effect: read
      questions:
      - What details are stored about a specific team?
      - Can I look up a team by UUID?
      instructions:
      - text: Show team {teamUuid}.
        slots:
          teamUuid: path.teamUuid
      - text: Get the details of team {teamUuid}.
        slots:
          teamUuid: path.teamUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a team
      effect: write
      questions:
      - Can I change a team's name?
      - How do I rename a team?
      instructions:
      - text: Rename team {teamUuid} to {name}.
        slots:
          teamUuid: path.teamUuid
          name: requestBody.name
      - text: Change the name of team {teamUuid} to {name}.
        slots:
          teamUuid: path.teamUuid
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a team
      effect: destructive
      questions:
      - How do I delete a team entirely?
      - Can I remove a team that's no longer needed?
      instructions:
      - text: Delete team {teamUuid}.
        slots:
          teamUuid: path.teamUuid
      - text: Permanently remove team {teamUuid}.
        slots:
          teamUuid: path.teamUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}/actions/leave'].post
  update:
    x-apievangelist-phrasing:
      intent: Leave a team
      effect: write
      questions:
      - Can I remove myself from a team?
      - How do I leave a team I was added to?
      instructions:
      - text: Take me off team {teamUuid}.
        slots:
          teamUuid: path.teamUuid
      - text: Leave team {teamUuid}.
        slots:
          teamUuid: path.teamUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}/applications'].get
  update:
    x-apievangelist-phrasing:
      intent: List applications a team can access
      effect: read
      questions:
      - Which applications does this team have access to?
      - Can I filter a team's applications by name?
      instructions:
      - text: List applications available to team {teamUuid}.
        slots:
          teamUuid: path.teamUuid
      - text: Show team {teamUuid} applications matching {filter}.
        slots:
          teamUuid: path.teamUuid
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}/applications'].post
  update:
    x-apievangelist-phrasing:
      intent: Give a team access to an application
      effect: write
      questions:
      - How do I grant a team access to one of my applications?
      - Can I add an application to an existing team?
      instructions:
      - text: Add application {uuid} to team {teamUuid}.
        slots:
          uuid: requestBody.uuid
          teamUuid: path.teamUuid
      - text: Grant team {teamUuid} access to application {uuid}.
        slots:
          teamUuid: path.teamUuid
          uuid: requestBody.uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}/applications/{applicationUuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an application from a team
      effect: destructive
      questions:
      - Can I revoke a team's access to an application?
      - Will team members lose access immediately if I remove an app from their team?
      instructions:
      - text: Remove application {applicationUuid} from team {teamUuid}.
        slots:
          applicationUuid: path.applicationUuid
          teamUuid: path.teamUuid
      - text: Revoke team {teamUuid}'s access to application {applicationUuid}.
        slots:
          teamUuid: path.teamUuid
          applicationUuid: path.applicationUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}/invites'].get
  update:
    x-apievangelist-phrasing:
      intent: List a team's pending invitations
      effect: read
      questions:
      - Who has been invited to this team but not joined yet?
      - Can I filter a team's invitations by email?
      instructions:
      - text: List invitations for team {teamUuid}.
        slots:
          teamUuid: path.teamUuid
      - text: Show team {teamUuid} invites matching {filter}.
        slots:
          teamUuid: path.teamUuid
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}/invites'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite a user to a team
      effect: write
      questions:
      - How do I invite a colleague to join a team?
      - Can I pick their roles when I send a team invite?
      instructions:
      - text: Invite {email} to team {teamUuid} with roles {roles}.
        slots:
          email: requestBody.email
          teamUuid: path.teamUuid
          roles: requestBody.roles
      - text: Send a team {teamUuid} invitation to {email} granting {roles}.
        slots:
          teamUuid: path.teamUuid
          email: requestBody.email
          roles: requestBody.roles
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List a team's members
      effect: read
      questions:
      - Who are the members of this team?
      - Can I filter team members by last name or permission?
      instructions:
      - text: List members of team {teamUuid}.
        slots:
          teamUuid: path.teamUuid
      - text: Show team {teamUuid} members matching {filter}.
        slots:
          teamUuid: path.teamUuid
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}/members/{userUuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a team member's roles
      effect: write
      questions:
      - How do I change the roles a teammate holds?
      - Can I grant additional roles to an existing team member?
      instructions:
      - text: Give member {userUuid} of team {teamUuid} the roles {roles}.
        slots:
          userUuid: path.userUuid
          teamUuid: path.teamUuid
          roles: requestBody.roles
      - text: Set roles {roles} for user {userUuid} in team {teamUuid}.
        slots:
          roles: requestBody.roles
          userUuid: path.userUuid
          teamUuid: path.teamUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/teams/{teamUuid}/members/{userUuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a member from a team
      effect: destructive
      questions:
      - How do I remove someone else from a team?
      - Can I kick a user off a team I administer?
      instructions:
      - text: Remove user {userUuid} from team {teamUuid}.
        slots:
          userUuid: path.userUuid
          teamUuid: path.teamUuid
      - text: Kick member {userUuid} out of team {teamUuid}.
        slots:
          userUuid: path.userUuid
          teamUuid: path.teamUuid
      method: generated
      generated: '2026-09-26'