# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Graph API (Azure AD) Users API
  version: 1.0.0
extends: openapi/azure-ad-users-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: 7
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in the directory
      effect: read
      questions:
      - How do I get a list of all the users in my Entra ID tenant?
      - Can I filter the user list to only accounts in one department or with a certain job title?
      - Is there a way to return just the first 50 users with only their names and emails?
      instructions:
      - text: List all users in the directory.
      - text: List users matching {filter}.
        slots:
          filter: query.$filter
      - text: Show the first {top} users with only {select}.
        slots:
          top: query.$top
          select: query.$select
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new user account
      effect: write
      questions:
      - How do I add a new employee account to Microsoft Entra ID through Graph?
      - Can I create a user that starts out disabled until their start date?
      - What do I need to supply to set up a new user with a sign-in name and display name?
      instructions:
      - text: Create a new user {displayName} with sign-in name {userPrincipalName}.
        slots:
          displayName: requestBody.displayName
          userPrincipalName: requestBody.userPrincipalName
      - text: Add a user named {givenName} {surname} with job title {jobTitle} and mail {mail}.
        slots:
          givenName: requestBody.givenName
          surname: requestBody.surname
          jobTitle: requestBody.jobTitle
          mail: requestBody.mail
      - text: Create user {userPrincipalName} with the account enabled set to {accountEnabled}.
        slots:
          userPrincipalName: requestBody.userPrincipalName
          accountEnabled: requestBody.accountEnabled
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a single user's profile
      effect: read
      questions:
      - How can I look up one user's profile by their sign-in name?
      - What details does the directory hold for a specific user account?
      instructions:
      - text: Get the profile of user {id}.
        slots:
          id: path.id
      - text: Look up the directory account for {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user account
      effect: destructive
      questions:
      - How do I remove a departed employee's account from the directory?
      - Can I delete a user by their user principal name instead of their object id?
      instructions:
      - text: Delete user {id} from the directory.
        slots:
          id: path.id
      - text: Remove the account belonging to {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing user's profile
      effect: write
      questions:
      - How do I change an existing user's job title or display name?
      - Can I disable sign-in for a user who already exists without deleting them?
      - Is it possible to update someone's email address on their existing account?
      instructions:
      - text: Change the job title of user {id} to {jobTitle}.
        slots:
          id: path.id
          jobTitle: requestBody.jobTitle
      - text: Set account enabled to {accountEnabled} for existing user {id}.
        slots:
          id: path.id
          accountEnabled: requestBody.accountEnabled
      - text: Rename existing user {id} to display name {displayName}.
        slots:
          id: path.id
          displayName: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/manager'].get
  update:
    x-apievangelist-phrasing:
      intent: Find a user's manager
      effect: read
      questions:
      - Who does a particular employee report to?
      - Can I look up the manager assigned to a user in the directory?
      instructions:
      - text: Find the manager of user {id}.
        slots:
          id: path.id
      - text: Tell me who {id} reports to.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/directReports'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's direct reports
      effect: read
      questions:
      - Which people report directly to a given manager?
      - How do I see everyone on a manager's team in Entra ID?
      instructions:
      - text: List the direct reports of user {id}.
        slots:
          id: path.id
      - text: Show everyone who reports to {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'