# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for DoiT Users API
  version: 1.0.0
extends: openapi/doit-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: 6
- target: $.paths['/iam/v1/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in the organization
      effect: read
      questions:
      - Who has access to our DoiT organization, including pending invites?
      - Can I look up a user by email?
      instructions:
      - text: List all users and invited users.
      - text: Find the user with email {email}.
        slots:
          email: query.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/iam/v1/users/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user
      effect: destructive
      questions:
      - How do I remove someone from our organization?
      - Can I delete a user account?
      instructions:
      - text: Delete user {id}.
        slots:
          id: path.id
      - text: Remove user {id} from the organization.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/iam/v1/users/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's profile or role
      effect: write
      questions:
      - How do I change a user's role?
      - Can I update someone's job title or phone number?
      instructions:
      - text: Change user {id} role to {roleId}.
        slots:
          id: path.id
          roleId: requestBody.roleId
      - text: Set user {id} job title to {jobTitle}.
        slots:
          id: path.id
          jobTitle: requestBody.jobTitle
      method: generated
      generated: '2026-10-01'
- target: $.paths['/iam/v1/users/invite'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite a new user
      effect: write
      questions:
      - How do I invite a teammate to DoiT?
      - Can I assign a role when inviting someone?
      instructions:
      - text: Invite {email} to our organization.
        slots:
          email: requestBody.email
      - text: Invite {email} with role {roleId} into organization {organizationId}.
        slots:
          email: requestBody.email
          roleId: requestBody.roleId
          organizationId: requestBody.organizationId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/iam/v1/users/{id}/actions/resend'].post
  update:
    x-apievangelist-phrasing:
      intent: Resend a pending invite
      effect: write
      questions:
      - How do I resend an invitation that expired?
      - Do old invite links still work after resending?
      instructions:
      - text: Resend the invite for user {id}.
        slots:
          id: path.id
      - text: Send a fresh invitation to pending user {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/iam/v1/users/{id}/actions/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a pending invite
      effect: destructive
      questions:
      - How do I revoke an invitation that hasn't been accepted?
      - Can I preview cancelling an invite with a dry run?
      instructions:
      - text: Cancel the invite for user {id}.
        slots:
          id: path.id
      - text: Dry-run cancelling invite {id} ({dryRun}).
        slots:
          id: path.id
          dryRun: query.dryRun
      method: generated
      generated: '2026-10-01'