# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness User Group API
  version: 1.0.0
extends: openapi/harness-user-group-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: 20
- target: $.paths['/ng/api/user-groups/{identifier}/member/{userIdentifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a user belongs to a user group
      effect: read
      questions:
      - Is a specific user a member of this user group?
      - Can I verify a person's membership in a Harness user group?
      instructions:
      - text: Check whether user {userIdentifier} is in user group {identifier}.
        slots:
          userIdentifier: path.userIdentifier
          identifier: path.identifier
      - text: Tell me if {userIdentifier} belongs to group {identifier}.
        slots:
          userIdentifier: path.userIdentifier
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/{identifier}/member/{userIdentifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add a user to a user group
      effect: write
      questions:
      - How do I add one person to a user group?
      - Can I add a user to a group scoped to a project?
      instructions:
      - text: Add user {userIdentifier} to user group {identifier}.
        slots:
          userIdentifier: path.userIdentifier
          identifier: path.identifier
      - text: Put {userIdentifier} into group {identifier} in project {projectIdentifier}.
        slots:
          userIdentifier: path.userIdentifier
          identifier: path.identifier
          projectIdentifier: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/{identifier}/member/{userIdentifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from a user group
      effect: destructive
      questions:
      - How do I take someone out of a user group?
      - Can I remove a single member from a group without deleting it?
      instructions:
      - text: Remove user {userIdentifier} from user group {identifier}.
        slots:
          userIdentifier: path.userIdentifier
          identifier: path.identifier
      - text: Drop {userIdentifier} from group {identifier}.
        slots:
          userIdentifier: path.userIdentifier
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/copy'].put
  update:
    x-apievangelist-phrasing:
      intent: Copy a user group
      effect: write
      questions:
      - Can I copy an existing user group?
      - What's the way to duplicate a user group's setup?
      instructions:
      - text: Copy user group {groupIdentifier}.
        slots:
          groupIdentifier: query.groupIdentifier
      - text: Make a copy of group {groupIdentifier}.
        slots:
          groupIdentifier: query.groupIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List user groups in a scope
      effect: read
      questions:
      - What user groups exist in my account, org or project?
      - Can I find user groups linked to a particular SSO group?
      - How many user groups can I page through at a time?
      instructions:
      - text: List the user groups in project {projectIdentifier}.
        slots:
          projectIdentifier: query.projectIdentifier
      - text: Search user groups by name for {searchTerm}.
        slots:
          searchTerm: query.searchTerm
      - text: List user groups tied to SSO group {ssoGroupId}.
        slots:
          ssoGroupId: query.ssoGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user group by user IDs
      effect: write
      questions:
      - How do I rename a user group or change its member user IDs?
      - Can I update a user group's notification settings?
      instructions:
      - text: Update user group {identifier} to be named {name} with user IDs {users}.
        slots:
          identifier: requestBody.identifier
          name: requestBody.name
          users: requestBody.users
      - text: Change the description of user group {identifier} named {name} to {description}.
        slots:
          identifier: requestBody.identifier
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user group from user IDs
      effect: write
      questions:
      - How do I create a new user group with members given by user ID?
      - Can a new user group be marked as externally managed?
      instructions:
      - text: Create user group {identifier} named {name} with user IDs {users}.
        slots:
          identifier: requestBody.identifier
          name: requestBody.name
          users: requestBody.users
      - text: Create an empty user group {identifier} called {name} in project {projectIdentifier}.
        slots:
          identifier: requestBody.identifier
          name: requestBody.name
          projectIdentifier: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/{identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user group
      effect: read
      questions:
      - What members and settings does a particular user group have?
      - How can I retrieve one user group by its identifier?
      instructions:
      - text: Show user group {identifier}.
        slots:
          identifier: path.identifier
      - text: Get user group {identifier} in org {orgIdentifier}.
        slots:
          identifier: path.identifier
          orgIdentifier: query.orgIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/{identifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user group
      effect: destructive
      questions:
      - How do I delete a user group entirely?
      - Can I remove a user group from a project scope?
      instructions:
      - text: Delete user group {identifier}.
        slots:
          identifier: path.identifier
      - text: Remove group {identifier} from project {projectIdentifier}.
        slots:
          identifier: path.identifier
          projectIdentifier: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/{identifier}/scopes'].get
  update:
    x-apievangelist-phrasing:
      intent: List child scopes inheriting a user group
      effect: read
      questions:
      - Which orgs or projects inherit this user group?
      - Where is an account-level user group being used downstream?
      instructions:
      - text: List the child scopes that inherit user group {identifier}.
        slots:
          identifier: path.identifier
      - text: Show which scopes inherit group {identifier}.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/{identifier}/users'].post
  update:
    x-apievangelist-phrasing:
      intent: List the users in a user group
      effect: read
      questions:
      - Who are the members of a given user group?
      - Can I filter a group's members by email?
      instructions:
      - text: List the users in user group {identifier}.
        slots:
          identifier: path.identifier
      - text: Find members of group {identifier} with emails {emails}.
        slots:
          identifier: path.identifier
          emails: requestBody.emails
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/{userGroupId}/link/ldap/{ldapId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Link an LDAP group to a user group
      effect: write
      questions:
      - How do I sync a user group with an LDAP group?
      - Can a user group be tied to an LDAP group's DN?
      instructions:
      - text: Link user group {userGroupId} to LDAP group {ldapGroupName} ({ldapGroupDN}) on LDAP {ldapId}.
        slots:
          userGroupId: path.userGroupId
          ldapGroupName: requestBody.ldapGroupName
          ldapGroupDN: requestBody.ldapGroupDN
          ldapId: path.ldapId
      - text: Sync group {userGroupId} from LDAP {ldapId} using DN {ldapGroupDN} and name {ldapGroupName}.
        slots:
          userGroupId: path.userGroupId
          ldapId: path.ldapId
          ldapGroupDN: requestBody.ldapGroupDN
          ldapGroupName: requestBody.ldapGroupName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/{userGroupId}/link/oidc/{providerId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Link an OIDC group to a user group
      effect: write
      questions:
      - Can I map a user group to a group from my OIDC provider?
      - How do I link an OIDC group name to a Harness user group?
      instructions:
      - text: Link user group {userGroupId} to OIDC group {oidcGroupName} from provider {providerId}.
        slots:
          userGroupId: path.userGroupId
          oidcGroupName: requestBody.oidcGroupName
          providerId: path.providerId
      - text: Tie group {userGroupId} to OIDC provider {providerId} group {oidcGroupName}.
        slots:
          userGroupId: path.userGroupId
          providerId: path.providerId
          oidcGroupName: requestBody.oidcGroupName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/{userGroupId}/link/saml/{samlId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Link a SAML group to a user group
      effect: write
      questions:
      - How do I connect a user group to a SAML group?
      - Can user group membership come from a SAML assertion group?
      instructions:
      - text: Link user group {userGroupId} to SAML group {samlGroupName} on SAML config {samlId}.
        slots:
          userGroupId: path.userGroupId
          samlGroupName: requestBody.samlGroupName
          samlId: path.samlId
      - text: Map group {userGroupId} to SAML {samlId} group {samlGroupName}.
        slots:
          userGroupId: path.userGroupId
          samlId: path.samlId
          samlGroupName: requestBody.samlGroupName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Batch fetch up to 10K user groups by filter
      effect: read
      questions:
      - Can I pull every user group that contains a given user without paging?
      - What's the maximum number of user groups the batch filter returns?
      instructions:
      - text: Batch fetch all user groups containing users {userIdentifierFilter}.
        slots:
          userIdentifierFilter: requestBody.userIdentifierFilter
      - text: Get the user groups with identifiers {identifierFilter} in one unpaged batch.
        slots:
          identifierFilter: requestBody.identifierFilter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/filter'].post
  update:
    x-apievangelist-phrasing:
      intent: Filter user groups with pagination
      effect: read
      questions:
      - Which user groups include a particular user, page by page?
      - Can I filter user groups by identifier and page through the results?
      instructions:
      - text: Filter user groups containing users {userIdentifierFilter}, page {pageIndex}.
        slots:
          userIdentifierFilter: requestBody.userIdentifierFilter
          pageIndex: query.pageIndex
      - text: Return a paged list of user groups matching {searchTerm}.
        slots:
          searchTerm: requestBody.searchTerm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user-groups/{userGroupId}/unlink'].put
  update:
    x-apievangelist-phrasing:
      intent: Unlink a user group from its SSO group
      effect: write
      questions:
      - How do I disconnect a user group from SSO syncing?
      - When I unlink SSO, can I keep the members that were already synced?
      instructions:
      - text: Unlink user group {userGroupId} from SSO.
        slots:
          userGroupId: path.userGroupId
      - text: Unlink group {userGroupId} from SSO and set retain members to {retainMembers}.
        slots:
          userGroupId: path.userGroupId
          retainMembers: query.retainMembers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/user-groups'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user group by member emails (v2)
      effect: write
      questions:
      - Can I update a user group's members using their email addresses?
      - Is there a v2 user group update that takes emails instead of user IDs?
      instructions:
      - text: Update user group {identifier} named {name} so its members are emails {users} via the v2 endpoint.
        slots:
          identifier: requestBody.identifier
          name: requestBody.name
          users: requestBody.users
      - text: Use v2 to rename user group {identifier} to {name}.
        slots:
          identifier: requestBody.identifier
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/user-groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user group from member emails (v2)
      effect: write
      questions:
      - Can I create a user group by listing members' email addresses?
      - What's the v2 way to create a user group with emails?
      instructions:
      - text: Create user group {identifier} named {name} with member emails {users} using v2.
        slots:
          identifier: requestBody.identifier
          name: requestBody.name
          users: requestBody.users
      - text: Use the v2 create endpoint for group {identifier} called {name}.
        slots:
          identifier: requestBody.identifier
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/user-groups/{identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user group via the v2 endpoint
      effect: read
      questions:
      - Is there a v2 endpoint to fetch a user group with member emails?
      - Can I read a user group through the v2 user groups API?
      instructions:
      - text: Get user group {identifier} from the v2 endpoint.
        slots:
          identifier: path.identifier
      - text: Fetch group {identifier} with the v2 user groups API.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'