# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Identity.SignIns Policies.unified Role Management Policy API
  version: 1.0.0
extends: openapi/azure-ad-policies-unifiedrolemanagementpolicy-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: 18
- target: $.paths['/policies/roleManagementPolicies'].get
  update:
    x-apievangelist-phrasing:
      intent: List PIM role management policies
      effect: read
      questions:
      - Which PIM policies apply to Microsoft Entra roles or group membership in my tenant?
      - Can I filter role management policies by scope?
      instructions:
      - text: List all PIM role management policies.
      - text: Show role management policies where {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a role management policy
      effect: write
      questions:
      - Is it possible to add a new role management policy for a scope?
      - What fields go into a new PIM policy, like scope ID and scope type?
      instructions:
      - text: Create a role management policy named {displayName} for scope {scopeId} of type {scopeType}.
        slots:
          displayName: requestBody.displayName
          scopeId: requestBody.scopeId
          scopeType: requestBody.scopeType
      - text: Add a new PIM policy described as {description}.
        slots:
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one role management policy
      effect: read
      questions:
      - What are the details of a specific PIM role management policy?
      - Can I read one policy together with its rules expanded?
      instructions:
      - text: Get role management policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
      - text: Show policy {policy} with {expand} expanded.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          expand: query.$expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a role management policy
      effect: destructive
      questions:
      - Can I delete a role management policy I created?
      - What happens when a PIM policy is removed from policies?
      instructions:
      - text: Delete role management policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
      - text: Remove the PIM policy with ID {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a role management policy
      effect: write
      questions:
      - How do I rename or re-describe an existing PIM policy?
      - Can I change whether a role management policy is the organization default?
      instructions:
      - text: Rename role management policy {policy} to {displayName}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          displayName: requestBody.displayName
      - text: Set isOrganizationDefault to {isOrganizationDefault} on PIM policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          isOrganizationDefault: requestBody.isOrganizationDefault
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/effectiveRules'].get
  update:
    x-apievangelist-phrasing:
      intent: List a policy's effective rules
      effect: read
      questions:
      - Which approval and expiration rules actually take effect after inherited tenant-wide rules are applied?
      - Why is approval enforced even though my policy disables it?
      instructions:
      - text: List the effective rules for role management policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
      - text: Show the evaluated effective rules on PIM policy {policy} matching {filter}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/effectiveRules'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an effective rule to a policy
      effect: write
      questions:
      - Can I create an effective rule entry on a role management policy?
      - What does a new effective rule need besides its target?
      instructions:
      - text: Add an effective rule with target {target} to policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          target: requestBody.target
      - text: Create effective rule {ruleId} on role management policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          ruleId: requestBody.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/effectiveRules/{unifiedRoleManagementPolicyRule-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one effective rule of a policy
      effect: read
      questions:
      - What is the effective, inheritance-evaluated value of one specific rule on a PIM policy?
      - Is a particular expiration rule effectively enabled after tenant-wide settings?
      instructions:
      - text: Get effective rule {rule} on role management policy {policy}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
      - text: Show how rule {rule} is evaluated in effect for PIM policy {policy}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/effectiveRules/{unifiedRoleManagementPolicyRule-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an effective rule from a policy
      effect: destructive
      questions:
      - Can an effective rule be deleted from a role management policy?
      - Is it possible to drop one entry from a policy's effective rules collection?
      instructions:
      - text: Delete effective rule {rule} from role management policy {policy}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
      - text: Remove {rule} from the effective rules of PIM policy {policy}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/effectiveRules/{unifiedRoleManagementPolicyRule-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an effective rule on a policy
      effect: write
      questions:
      - Can I change the target of an effective rule on a PIM policy?
      - Is patching an effective rule entry supported?
      instructions:
      - text: Set the target of effective rule {rule} on policy {policy} to {target}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
          target: requestBody.target
      - text: Patch effective rule {rule} in role management policy {policy}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/effectiveRules/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a policy's effective rules
      effect: read
      questions:
      - How many effective rules does a role management policy have?
      - Can I get a total of effective rules matching a filter on one policy?
      instructions:
      - text: Count the effective rules on role management policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
      - text: Tell me how many effective rules on PIM policy {policy} match {filter}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/rules'].get
  update:
    x-apievangelist-phrasing:
      intent: List the rules configured on a policy
      effect: read
      questions:
      - What approval, expiration, notification and enablement settings are configured on a PIM policy?
      - Where do I see the raw rules defined on one role management policy?
      instructions:
      - text: List the configured rules of role management policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
      - text: Show the defined settings rules for PIM policy {policy}, top {top}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          top: query.$top
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/rules'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a rule to a policy
      effect: write
      questions:
      - Can I add a new configured rule to a role management policy?
      - What target does a newly created PIM policy rule apply to?
      instructions:
      - text: Add a rule with target {target} to role management policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          target: requestBody.target
      - text: Create rule {ruleId} in the rules of PIM policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          ruleId: requestBody.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/rules/{unifiedRoleManagementPolicyRule-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one configured rule of a policy
      effect: read
      questions:
      - What is the configured setting of one specific rule, like an approval rule, on a PIM policy?
      - Which rule type is a given rule ID on my role management policy?
      instructions:
      - text: Get configured rule {rule} of role management policy {policy}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
      - text: Show the settings of rule {rule} as defined on PIM policy {policy}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/rules/{unifiedRoleManagementPolicyRule-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a rule from a policy
      effect: destructive
      questions:
      - Can I delete a configured rule from a role management policy?
      - Is removing one setting rule from a PIM policy allowed?
      instructions:
      - text: Delete configured rule {rule} from role management policy {policy}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
      - text: Remove setting rule {rule} from PIM policy {policy}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/rules/{unifiedRoleManagementPolicyRule-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a rule on a policy
      effect: write
      questions:
      - How do I change an approval or expiration rule on a PIM policy?
      - Can I require approval for role activation by updating a policy rule?
      instructions:
      - text: Update configured rule {rule} on role management policy {policy} with target {target}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
          target: requestBody.target
      - text: Change the settings of rule {rule} in PIM policy {policy}.
        slots:
          rule: path.unifiedRoleManagementPolicyRule-id
          policy: path.unifiedRoleManagementPolicy-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/{unifiedRoleManagementPolicy-id}/rules/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a policy's configured rules
      effect: read
      questions:
      - How many configured rules are on a role management policy?
      - Can I count a PIM policy's defined rules matching a filter?
      instructions:
      - text: Count the configured rules of role management policy {policy}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
      - text: Tell me how many defined rules on PIM policy {policy} match {filter}.
        slots:
          policy: path.unifiedRoleManagementPolicy-id
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/policies/roleManagementPolicies/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count role management policies
      effect: read
      questions:
      - How many PIM role management policies exist in the tenant?
      - Can I get a total of policies for a given scope type?
      instructions:
      - text: Count all role management policies.
      - text: Tell me how many PIM policies match {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'