# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Cohesity Active Directory API
  version: 1.0.0
extends: openapi/cohesity-active-directory-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: 19
- target: $.paths['/public/activeDirectory'].get
  update:
    x-apievangelist-phrasing:
      intent: List AD domains the cluster has joined (legacy)
      effect: read
      questions:
      - Which Active Directory domains is my Cohesity cluster joined to, using the older public endpoint?
      - Can I see the joined AD domains for a particular tenant?
      instructions:
      - text: List the joined Active Directory entries for domains {domains} via the public API.
        slots:
          domains: query.domains
      - text: Show the legacy AD join entries for tenants {tenantIds}.
        slots:
          tenantIds: query.tenantIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory'].post
  update:
    x-apievangelist-phrasing:
      intent: Join the cluster to an AD domain (legacy)
      effect: write
      questions:
      - Can I join the cluster to an Active Directory domain through the older public API so domain users can log in?
      - Which OU and machine accounts are used when joining the cluster to a domain the legacy way?
      instructions:
      - text: Join the cluster to domain {domainName} as {userName} using the public activeDirectory endpoint.
        slots:
          domainName: requestBody.domainName
          userName: requestBody.userName
      - text: Join {domainName} with machine accounts {machineAccounts} in OU {ouName} via the legacy join.
        slots:
          domainName: requestBody.domainName
          machineAccounts: requestBody.machineAccounts
          ouName: requestBody.ouName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory'].delete
  update:
    x-apievangelist-phrasing:
      intent: Leave an AD domain (legacy)
      effect: destructive
      questions:
      - What happens to domain users' access if the cluster leaves an Active Directory domain?
      - Can I remove the cluster's join to a domain with the older public endpoint?
      instructions:
      - text: Remove the cluster's legacy join to domain {domainName}.
        slots:
          domainName: requestBody.domainName
      - text: Unjoin {domainName} using admin {userName} through the public activeDirectory API.
        slots:
          domainName: requestBody.domainName
          userName: requestBody.userName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory/centrifyZones'].get
  update:
    x-apievangelist-phrasing:
      intent: List Centrify zones of an AD domain
      effect: read
      questions:
      - Which Centrify zones exist in my Active Directory domain?
      - Can I see Centrify zone options before configuring UNIX identity mapping?
      instructions:
      - text: List Centrify zones in domain {domainName}.
        slots:
          domainName: query.domainName
      - text: Show the Centrify zones available for {domainName}.
        slots:
          domainName: query.domainName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory/domainControllers'].get
  update:
    x-apievangelist-phrasing:
      intent: List a joined domain's controllers (legacy)
      effect: read
      questions:
      - Which domain controllers does the cluster see for a joined domain via the public endpoint?
      - Can I check which DCs are reachable for a domain using the legacy activeDirectory path?
      instructions:
      - text: List the domain controllers for joined domain {domainName} via the public API.
        slots:
          domainName: query.domainName
      - text: Show the DCs the legacy activeDirectory endpoint finds for {domainName}.
        slots:
          domainName: query.domainName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory/principals'].get
  update:
    x-apievangelist-phrasing:
      intent: Search AD users and groups
      effect: read
      questions:
      - Can I search Active Directory for a user or group by part of their name?
      - Which AD principals match a list of SIDs, and can computer accounts be included?
      instructions:
      - text: Search domain {domain} for principals matching {search}.
        slots:
          domain: query.domain
          search: query.search
      - text: Look up the AD principals with SIDs {sids}.
        slots:
          sids: query.sids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory/principals'].post
  update:
    x-apievangelist-phrasing:
      intent: Add AD users or groups with Cohesity roles
      effect: write
      questions:
      - How do I give an Active Directory group access to the cluster with a specific Cohesity role?
      - Can I add several AD users at once and map them to roles?
      instructions:
      - text: Add these Active Directory groups to the cluster and assign them Cohesity roles.
      - text: Grant AD users access to the cluster with the Viewer role.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory/{name}/enableTrustedDomainState'].post
  update:
    x-apievangelist-phrasing:
      intent: Turn trusted domain discovery on or off
      effect: write
      questions:
      - Can I stop the cluster from discovering trusted domains of a joined AD domain?
      - Is trusted domain discovery something I can toggle per Active Directory?
      instructions:
      - text: Enable trusted domain discovery for {name}.
        slots:
          name: path.name
      - text: Set trusted domain discovery on {name} to {trustedDomainsEnabled}.
        slots:
          name: path.name
          trustedDomainsEnabled: requestBody.trustedDomainsEnabled
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory/{name}/idMappingInfo'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an AD domain's user ID mapping
      effect: write
      questions:
      - How are AD users mapped to UNIX user IDs, and can I change that mapping for a domain?
      - Can I set a fallback ID mapping or UNIX root SID for an Active Directory?
      instructions:
      - text: Update user ID mapping for {name} to {userIdMappingInfo}.
        slots:
          name: path.name
          userIdMappingInfo: requestBody.userIdMappingInfo
      - text: Set the UNIX root SID of {name} to {unixRootSid}.
        slots:
          name: path.name
          unixRootSid: requestBody.unixRootSid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory/{name}/ignoredTrustedDomains'].put
  update:
    x-apievangelist-phrasing:
      intent: Set trusted domains to ignore
      effect: write
      questions:
      - Can I exclude certain trusted domains from discovery on a joined AD domain?
      - Which trusted domains are skipped during discovery, and can I change the list?
      instructions:
      - text: Ignore trusted domains {ignoredTrustedDomains} for {name}.
        slots:
          ignoredTrustedDomains: requestBody.ignoredTrustedDomains
          name: path.name
      - text: Update the ignored trusted domain list of {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory/{name}/ldapProvider'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the LDAP provider for an AD domain
      effect: write
      questions:
      - Can I associate an LDAP provider with a joined Active Directory domain?
      - What changes if I swap the LDAP provider used by an AD domain?
      instructions:
      - text: Set the LDAP provider of {name} to {ldapProviderId}.
        slots:
          name: path.name
          ldapProviderId: requestBody.ldapProviderId
      - text: Link LDAP provider {ldapProviderId} to Active Directory {name}.
        slots:
          ldapProviderId: requestBody.ldapProviderId
          name: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory/{name}/machineAccounts'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a domain's machine accounts (legacy)
      effect: write
      questions:
      - Can I add machine accounts to an Active Directory the cluster already joined, via the older endpoint?
      - Will existing machine accounts be overwritten when I update them for a domain?
      instructions:
      - text: Set machine accounts {machineAccounts} on joined domain {name} using admin {userName}.
        slots:
          machineAccounts: requestBody.machineAccounts
          name: path.name
          userName: requestBody.userName
      - text: Update the machine accounts of {name}, overwriting existing ones.
        slots:
          name: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/activeDirectory/{name}/preferredDomainControllers'].put
  update:
    x-apievangelist-phrasing:
      intent: Set preferred domain controllers for AD
      effect: write
      questions:
      - Can I tell the cluster which domain controllers to prefer for a joined domain?
      - Which DCs does the cluster talk to first, and can I pin that list?
      instructions:
      - text: Update the preferred domain controllers of {name}.
        slots:
          name: path.name
      - text: Make the cluster prefer specific domain controllers for {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/active-directories'].get
  update:
    x-apievangelist-phrasing:
      intent: List Active Directories (v2)
      effect: read
      questions:
      - Which Active Directories are configured on the cluster under the newer active-directories API?
      - Can I filter configured Active Directories by domain name or tenant?
      instructions:
      - text: List configured Active Directories for domains {domainNames}.
        slots:
          domainNames: query.domainNames
      - text: Show Active Directories with ids {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/active-directories'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an Active Directory (v2)
      effect: write
      questions:
      - What do I need to provide to configure a new Active Directory with the active-directories API?
      - Can I join a domain in a specific organizational unit with overwrite of machine accounts?
      instructions:
      - text: Create an Active Directory for {domainName} with machine accounts {machineAccounts} and admin credentials {activeDirectoryAdminParams}.
        slots:
          domainName: requestBody.domainName
          machineAccounts: requestBody.machineAccounts
          activeDirectoryAdminParams: requestBody.activeDirectoryAdminParams
      - text: Add domain {domainName} in OU {organizationalUnitName} with machine accounts {machineAccounts} and admin {activeDirectoryAdminParams}.
        slots:
          domainName: requestBody.domainName
          organizationalUnitName: requestBody.organizationalUnitName
          machineAccounts: requestBody.machineAccounts
          activeDirectoryAdminParams: requestBody.activeDirectoryAdminParams
      method: generated
      generated: '2026-10-01'
- target: $.paths['/active-directories/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one Active Directory's details
      effect: read
      questions:
      - Can I see a configured Active Directory's domain controllers and Centrify zones in one call?
      - What security principals with a given prefix exist in one configured Active Directory?
      instructions:
      - text: Get Active Directory {id}.
        slots:
          id: path.id
      - text: Show Active Directory {id} with principals starting {prefix}.
        slots:
          id: path.id
          prefix: query.prefix
      method: generated
      generated: '2026-10-01'
- target: $.paths['/active-directories/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an Active Directory (v2)
      effect: write
      questions:
      - Can I change the preferred domain controllers or trust settings of a configured Active Directory?
      - How deep can transitive AD trusts go, and can I change that limit?
      instructions:
      - text: Update Active Directory {id} with machine accounts {machineAccounts}.
        slots:
          id: path.id
          machineAccounts: requestBody.machineAccounts
      - text: Set the transitive trust level limit of Active Directory {id} to {transitiveAdTrustLevelLimit}, keeping machine accounts {machineAccounts}.
        slots:
          id: path.id
          transitiveAdTrustLevelLimit: requestBody.transitiveAdTrustLevelLimit
          machineAccounts: requestBody.machineAccounts
      method: generated
      generated: '2026-10-01'
- target: $.paths['/active-directories/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an Active Directory (v2)
      effect: destructive
      questions:
      - What credentials are needed to remove a configured Active Directory from the cluster?
      - Can I delete an Active Directory configuration by its id?
      instructions:
      - text: Delete Active Directory {id} using admin {activeDirectoryAdminUsername} and password {activeDirectoryAdminPassword}.
        slots:
          id: path.id
          activeDirectoryAdminUsername: header.activeDirectoryAdminUsername
          activeDirectoryAdminPassword: header.activeDirectoryAdminPassword
      - text: Remove the Active Directory configuration {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/domain-controllers'].get
  update:
    x-apievangelist-phrasing:
      intent: Get domain controllers for domains
      effect: read
      questions:
      - Which domain controllers serve the domains I list, even before the cluster joins them?
      - Can I discover DCs for several domains through a specific connection?
      instructions:
      - text: Get domain controllers for domains {domainNames}.
        slots:
          domainNames: query.domainNames
      - text: Find the DCs for {domainNames} through connection {connectionId}.
        slots:
          domainNames: query.domainNames
          connectionId: query.connectionId
      method: generated
      generated: '2026-10-01'