# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Role Assignments API
  version: 1.0.0
extends: openapi/harness-role-assignments-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: 10
- target: $.paths['/authz/api/roleassignments/delete/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete several role assignments at once
      effect: destructive
      questions:
      - Can I revoke a batch of role assignments in one request?
      - Is there a bulk way to remove role assignments by their identifiers?
      instructions:
      - text: Bulk delete role assignments in account {account}.
        slots:
          account: query.accountIdentifier
      - text: Remove a batch of role assignments from project {project}.
        slots:
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authz/api/roleassignments/multi'].post
  update:
    x-apievangelist-phrasing:
      intent: Create multiple role assignments in a scope
      effect: write
      questions:
      - How do I grant roles to many users or groups in one call?
      - What happens to duplicates when I create several role assignments together?
      instructions:
      - text: 'Create these role assignments in project {project}: {assignments}.'
        slots:
          project: query.projectIdentifier
          assignments: requestBody.roleAssignments
      - text: 'Grant multiple roles at once in account {account}: {assignments}.'
        slots:
          account: query.accountIdentifier
          assignments: requestBody.roleAssignments
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authz/api/roleassignments'].get
  update:
    x-apievangelist-phrasing:
      intent: List role assignments in a scope
      effect: read
      questions:
      - Who has which roles in my account?
      - Can I page through every role assignment in a project?
      instructions:
      - text: List role assignments in account {account}.
        slots:
          account: query.accountIdentifier
      - text: Show all role assignments in org {org}, project {project}.
        slots:
          org: query.orgIdentifier
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authz/api/roleassignments'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign a role to a principal
      effect: write
      questions:
      - How do I give a user a role on a resource group?
      - Can I create a role assignment that starts out disabled?
      instructions:
      - text: Assign role {role} on resource group {resource_group} to {principal}.
        slots:
          role: requestBody.roleIdentifier
          resource_group: requestBody.resourceGroupIdentifier
          principal: requestBody.principal
      - text: Grant {principal} the {role} role over {resource_group} in project {project}.
        slots:
          principal: requestBody.principal
          role: requestBody.roleIdentifier
          resource_group: requestBody.resourceGroupIdentifier
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authz/api/roleassignments/{identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one role assignment
      effect: read
      questions:
      - What role and resource group does a particular role assignment grant?
      - Can I look up a role assignment by its identifier?
      instructions:
      - text: Get role assignment {assignment}.
        slots:
          assignment: path.identifier
      - text: Show details of role assignment {assignment} in account {account}.
        slots:
          assignment: path.identifier
          account: query.accountIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authz/api/roleassignments/{identifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a role assignment
      effect: destructive
      questions:
      - How do I revoke a single role assignment from a user?
      - Does deleting a role assignment remove access immediately?
      instructions:
      - text: Delete role assignment {assignment}.
        slots:
          assignment: path.identifier
      - text: Revoke role assignment {assignment} in project {project}.
        slots:
          assignment: path.identifier
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authz/api/roleassignments/filter'].post
  update:
    x-apievangelist-phrasing:
      intent: Filter role assignments by role, principal or group
      effect: read
      questions:
      - Which users hold a specific role in this scope?
      - Can I list only disabled or Harness-managed role assignments?
      instructions:
      - text: List role assignments filtered to roles {roles} in account {account}.
        slots:
          roles: requestBody.roleFilter
          account: query.accountIdentifier
      - text: Find role assignments for principals {principals}.
        slots:
          principals: requestBody.principalFilter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authz/api/roleassignments/aggregate'].post
  update:
    x-apievangelist-phrasing:
      intent: List role assignments with role and group metadata
      effect: read
      questions:
      - Can I get role assignments together with the role and resource group details in one response?
      - What aggregated view of role assignments includes extra metadata?
      instructions:
      - text: Get aggregated role assignments with metadata for account {account}.
        slots:
          account: query.accountIdentifier
      - text: Show aggregate role assignments for resource groups {groups} with their role details.
        slots:
          groups: requestBody.resourceGroupFilter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authz/api/roleassignments/v2/filter'].post
  update:
    x-apievangelist-phrasing:
      intent: Filter role assignments across scopes
      effect: read
      questions:
      - Can I filter role assignments across several orgs or projects at once?
      - Which role assignments exist in a set of child scopes?
      instructions:
      - text: List role assignments across scopes {scopes}.
        slots:
          scopes: requestBody.scopeFilters
      - text: Filter role assignments by scopes {scopes} and principals {principals} in account {account}.
        slots:
          scopes: requestBody.scopeFilters
          principals: requestBody.principalFilter
          account: query.accountIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authz/api/roleassignments/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Check whether a proposed role assignment is valid
      effect: read
      questions:
      - Will this role assignment be accepted before I actually create it?
      - Can I check that the principal, role and resource group in an assignment exist?
      instructions:
      - text: Validate role assignment {assignment} in account {account}.
        slots:
          assignment: requestBody.roleAssignment
          account: query.accountIdentifier
      - text: Dry-run check {assignment}, validating the principal and role.
        slots:
          assignment: requestBody.roleAssignment
      method: generated
      generated: '2026-09-26'