# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for DaaS IQ Tenants API
  version: 1.0.0
extends: openapi/controlup-tenants-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: 31
- target: $.paths['/cloud/tenants/{tenantId}/credentials'].get
  update:
    x-apievangelist-phrasing:
      intent: List the credentials in a tenant pool
      effect: read
      questions:
      - Which service principals are in my cloud tenant's credential pool?
      - Can I see every credential a DaaS tenant uses, with secrets masked?
      instructions:
      - text: List all credentials for tenant {tenantId}.
        slots:
          tenantId: path.tenantId
      - text: Show the credential pool for tenant {tenantId}, including the default one.
        slots:
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a credential to a tenant pool
      effect: write
      questions:
      - Can I add another service principal to a tenant to spread API calls for load balancing?
      - What do I need to supply to add an extra credential to a ControlUp cloud tenant?
      instructions:
      - text: Add a {authType} credential to tenant {tenantId} using {credentials}.
        slots:
          authType: requestBody.authType
          tenantId: path.tenantId
          credentials: requestBody.credentials
      - text: Register an additional service principal in the credential pool of tenant {tenantId}.
        slots:
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one tenant credential configuration
      effect: read
      questions:
      - What auth type and enabled flag does a specific tenant credential have?
      - Can I look up one credential's configuration without checking its health?
      instructions:
      - text: Show the configuration of credential {credentialId} in tenant {tenantId}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      - text: Get credential {credentialId} for tenant {tenantId} with its masked secret fields.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a tenant credential's auth details
      effect: write
      questions:
      - Can I fully replace the authentication details of an existing tenant credential?
      - Does replacing a credential's secret clear its cooldown and health metrics?
      instructions:
      - text: Replace credential {credentialId} in tenant {tenantId} with auth type {authType} and {credentials}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
          authType: requestBody.authType
          credentials: requestBody.credentials
      - text: Overwrite all auth settings of credential {credentialId} on tenant {tenantId}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tenant credential
      effect: destructive
      questions:
      - What happens to the default when I delete a tenant's default credential?
      - Can I remove a service principal from a tenant's credential pool?
      instructions:
      - text: Delete credential {credentialId} from tenant {tenantId}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      - text: Remove credential {credentialId} from the pool of tenant {tenantId} and let another be promoted to default.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a tenant credential
      effect: write
      questions:
      - Can I change just the client secret on a credential without resending everything?
      - Is there a partial update for a tenant credential where only sent fields change?
      instructions:
      - text: Patch credential {credentialId} in tenant {tenantId} with new {credentials} only.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
          credentials: requestBody.credentials
      - text: Change only the auth type of credential {credentialId} on tenant {tenantId} to {authType}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
          authType: requestBody.authType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}/enable'].post
  update:
    x-apievangelist-phrasing:
      intent: Enable a credential in the pool
      effect: write
      questions:
      - How do I put a disabled tenant credential back into round-robin rotation?
      - Can a credential be re-enabled so it gets picked for API operations again?
      instructions:
      - text: Enable credential {credentialId} for tenant {tenantId}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      - text: Turn credential {credentialId} back on in the rotation for tenant {tenantId}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}/disable'].post
  update:
    x-apievangelist-phrasing:
      intent: Disable a credential in the pool
      effect: write
      questions:
      - Can I take a credential out of rotation without deleting it?
      - Why can't I disable the only enabled credential on a tenant?
      instructions:
      - text: Disable credential {credentialId} for tenant {tenantId}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      - text: Stop credential {credentialId} from being selected for tenant {tenantId} API calls, but keep it.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check live status of all tenant credentials
      effect: read
      questions:
      - Are any of my tenant's credentials rate-limited or in cooldown right now?
      - Which credentials in the pool are currently healthy and working?
      instructions:
      - text: Show live health and cooldown status for every credential in tenant {tenantId}.
        slots:
          tenantId: path.tenantId
      - text: Check usage metrics across the whole credential pool of tenant {tenantId}.
        slots:
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check live status of one credential
      effect: read
      questions:
      - Is a specific tenant credential in a rate-limit cooldown?
      - What are the usage metrics for one particular credential?
      instructions:
      - text: Show live health for credential {credentialId} in tenant {tenantId}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      - text: Check whether credential {credentialId} on tenant {tenantId} is currently working.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a tenant default credential live
      effect: write
      questions:
      - Can I test my tenant's default credential against Azure AD and get step-by-step results?
      - Does verifying the default credential clear its stale error state?
      instructions:
      - text: Verify the default credential of tenant {tenantId} against Azure AD.
        slots:
          tenantId: path.tenantId
      - text: Run a live structured check of tenant {tenantId}'s default credential.
        slots:
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a specific credential live
      effect: write
      questions:
      - Can I test one exact non-default credential's Azure AD authentication?
      - Will verifying a chosen credential bypass the round-robin selection?
      instructions:
      - text: Verify credential {credentialId} for tenant {tenantId} against Azure AD.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      - text: Test authentication and tenant access using exactly credential {credentialId} on tenant {tenantId}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/verify/transcript'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify default credential as readable transcript
      effect: write
      questions:
      - Can I get a human-readable transcript when verifying a tenant's default credential?
      - Where's the IsSuccess flag for a formatted default-credential check?
      instructions:
      - text: Verify tenant {tenantId}'s default credential and give me the formatted transcript lines.
        slots:
          tenantId: path.tenantId
      - text: Print a line-by-line verification transcript for the default credential of tenant {tenantId}.
        slots:
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}/verify/transcript'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify one credential as readable transcript
      effect: write
      questions:
      - Can I get formatted output lines when verifying one specific credential?
      - Is there a transcript version of the per-credential verification?
      instructions:
      - text: Verify credential {credentialId} on tenant {tenantId} and return the transcript lines.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      - text: Give me a readable verification transcript for credential {credentialId} in tenant {tenantId}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/verify/stream'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream default credential check over WebSocket (old)
      effect: write
      questions:
      - Is there a deprecated WebSocket stream that reports progress while my tenant's default credential is verified?
      - What replaced the WebSocket verify stream for a tenant's default credential?
      instructions:
      - text: Open the deprecated WebSocket stream verifying tenant {tenantId}'s default credential.
        slots:
          tenantId: path.tenantId
      - text: Watch default-credential verification for tenant {tenantId} over the legacy WebSocket connection.
        slots:
          tenantId: path.tenantId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}/verify/stream'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream one credential's check over WebSocket (old)
      effect: write
      questions:
      - Can existing UI clients still stream a specific credential's verification over a WebSocket?
      - Which endpoint replaces the WebSocket stream for verifying one credential by ID?
      instructions:
      - text: Open the legacy WebSocket verification stream for credential {credentialId} in tenant {tenantId}.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      - text: Stream step progress over WebSocket while credential {credentialId} on tenant {tenantId} is verified, using the deprecated endpoint.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/verify/sse'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream default credential check as server-sent events
      effect: write
      questions:
      - Can I follow each step of my tenant's default credential verification live as server-sent events?
      - What does each SSE event look like when streaming a default-credential check?
      instructions:
      - text: Stream the default credential verification for tenant {tenantId} as server-sent events.
        slots:
          tenantId: path.tenantId
      - text: Verify tenant {tenantId}'s default credential and send me step_started events as they happen over SSE.
        slots:
          tenantId: path.tenantId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/cloud/tenants/{tenantId}/credentials/{credentialId}/verify/sse'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream one credential's check as server-sent events
      effect: write
      questions:
      - Can I watch a specific tenant credential being verified step by step over SSE?
      - Is there an SSE stream for checking one credential by its ID instead of the default?
      instructions:
      - text: Stream SSE progress while credential {credentialId} in tenant {tenantId} is verified.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      - text: Verify credential {credentialId} on tenant {tenantId} and push each step to me as server-sent events.
        slots:
          credentialId: path.credentialId
          tenantId: path.tenantId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/cloud/tenants/{tenantId}/discover/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: Discover subscriptions a tenant can reach
      effect: read
      questions:
      - Which Azure subscriptions can my tenant's service principal access?
      - Which reachable subscriptions are already managed and which are new?
      instructions:
      - text: Discover the subscriptions accessible to tenant {tenantId}'s default credential.
        slots:
          tenantId: path.tenantId
      - text: List reachable subscriptions for tenant {tenantId}, {pageSize} per page.
        slots:
          tenantId: path.tenantId
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/discover/resources'].get
  update:
    x-apievangelist-phrasing:
      intent: Discover cloud resources by type
      effect: read
      questions:
      - Can I discover several resource types at once across my Azure subscriptions?
      - Which cloud resources haven't been imported into DaaS IQ yet?
      instructions:
      - text: Discover {types} resources in tenant {tenantId}.
        slots:
          types: query.types
          tenantId: path.tenantId
      - text: Discover {types} resources for tenant {tenantId} only in subscriptions {subscriptionIds}.
        slots:
          types: query.types
          tenantId: path.tenantId
          subscriptionIds: query.subscriptionIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/discover/resources/hostpools'].get
  update:
    x-apievangelist-phrasing:
      intent: Discover Azure host pools in a tenant
      effect: read
      questions:
      - What host pools exist in Azure for my tenant, including ones never imported?
      - Can I see the load balancer setup and session limits of discoverable host pools?
      instructions:
      - text: Discover all Azure Virtual Desktop host pools in tenant {tenantId}.
        slots:
          tenantId: path.tenantId
      - text: Find host pools in tenant {tenantId} matching {filter}.
        slots:
          tenantId: path.tenantId
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/discover/resources/images'].get
  update:
    x-apievangelist-phrasing:
      intent: Discover images in a tenant (deprecated)
      effect: read
      questions:
      - Is the old tenant image discovery endpoint still supported?
      - Can I still list VM images with their source type across a tenant's subscriptions?
      instructions:
      - text: Run the deprecated image discovery for tenant {tenantId}.
        slots:
          tenantId: path.tenantId
      - text: List discovered images in tenant {tenantId} using the legacy image discovery.
        slots:
          tenantId: path.tenantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{tenantId}/resources/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import cloud resources for a tenant
      effect: write
      questions:
      - Can I import every resource from all subscriptions under a tenant in one job?
      - Is it possible to selectively import specific resources from chosen subscriptions?
      instructions:
      - text: Import all resources from every subscription in tenant {tenantId}.
        slots:
          tenantId: path.tenantId
      - text: Import the resources in {subscriptions} for tenant {tenantId}.
        slots:
          subscriptions: requestBody.subscriptions
          tenantId: path.tenantId
      - text: Start a tenant {tenantId} import in {importMode} mode.
        slots:
          tenantId: path.tenantId
          importMode: requestBody.importMode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants'].get
  update:
    x-apievangelist-phrasing:
      intent: List cloud provider tenants
      effect: read
      questions:
      - Which cloud tenants are connected to my ControlUp organization?
      - Can I filter my connected tenants to just AWS or just Azure?
      instructions:
      - text: List all cloud tenants in my organization.
      - text: Show only the {provider} tenants.
        slots:
          provider: query.provider
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants'].post
  update:
    x-apievangelist-phrasing:
      intent: Connect a new cloud tenant
      effect: write
      questions:
      - What do I need to connect a new Azure AD tenant with its default credential?
      - Can I create a tenant and its default credential in one call?
      instructions:
      - text: Create a {provider} tenant named {name} for provider tenant ID {providerTenantId} with default credential {defaultCredential}.
        slots:
          provider: requestBody.provider
          name: requestBody.name
          providerTenantId: requestBody.providerTenantId
          defaultCredential: requestBody.defaultCredential
      - text: Connect Azure directory {providerTenantId} as a new tenant called {name}.
        slots:
          providerTenantId: requestBody.providerTenantId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tenant by ID
      effect: read
      questions:
      - What provider and identifiers does a specific tenant have?
      - Can I look up one tenant's configuration and masked default credential?
      instructions:
      - text: Show tenant {id}.
        slots:
          id: path.id
      - text: Get the configuration of tenant {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a tenant configuration
      effect: write
      questions:
      - Can I rename a tenant and replace its default credential in one full update?
      - When am I allowed to change a tenant's cloud provider?
      instructions:
      - text: Update tenant {id} with name {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Fully replace tenant {id}'s settings with name {name} and default credential {defaultCredential}.
        slots:
          id: path.id
          name: requestBody.name
          defaultCredential: requestBody.defaultCredential
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tenant
      effect: destructive
      questions:
      - Can I remove a cloud tenant and its credentials from ControlUp?
      - Does deleting a tenant also delete its credentials?
      instructions:
      - text: Delete tenant {id}.
        slots:
          id: path.id
      - text: Remove tenant {id} along with its credentials.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a tenant
      effect: write
      questions:
      - Can I change just a tenant's display name without touching anything else?
      - Is it possible to update only part of a tenant's default credential, like the secret?
      instructions:
      - text: Rename tenant {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Patch only the default credential of tenant {id} with {defaultCredential}.
        slots:
          id: path.id
          defaultCredential: requestBody.defaultCredential
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{id}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tenant's last known health
      effect: read
      questions:
      - What was my tenant's health at its last evaluation?
      - Can I see stored tenant health with per-subscription details without re-testing?
      instructions:
      - text: Show the stored health status of tenant {id}.
        slots:
          id: path.id
      - text: Get tenant {id} status including {include}.
        slots:
          id: path.id
          include: query.include
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cloud/tenants/{id}/status/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-test a tenant's health now
      effect: write
      questions:
      - Can I force a fresh connectivity check of a tenant and all its subscriptions?
      - Is there a way to re-evaluate tenant health right now instead of reading the cached result?
      instructions:
      - text: Refresh the status of tenant {id} now.
        slots:
          id: path.id
      - text: Re-test tenant {id} against the cloud provider and include {include}.
        slots:
          id: path.id
          include: query.include
      method: generated
      generated: '2026-09-26'