# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for CData Connect AI Management Users API
  version: 1.0.0
extends: openapi/cdata-users-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: 15
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List the organization's human users
      effect: read
      questions:
      - Which people have user accounts in our Connect AI organization?
      - Can I list only users provisioned through SCIM versus ones created by API?
      - Is there a way to find a user by their exact email address?
      instructions:
      - text: List all human users in the organization.
      - text: Find the user with email {email}.
        slots:
          email: query.email
      - text: List users with status {status} who hold role {role_id}.
        slots:
          status: query.status
          role_id: query.role_id
      - text: Show only users where SCIM managed is {scim_managed}, {limit} per page.
        slots:
          scim_managed: query.scim_managed
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a single user outside SCIM
      effect: write
      questions:
      - How do I add a contractor or break-glass user when we don't use SCIM?
      - Does creating a user twice with the same external Id make a duplicate?
      instructions:
      - text: Create a user {first_name} {last_name} with email {email}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          email: requestBody.email
      - text: Add one user {first_name} at {email} with HR employee Id {external_id}.
        slots:
          first_name: requestBody.first_name
          email: requestBody.email
          external_id: requestBody.external_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk create or update up to 500 users
      effect: write
      questions:
      - Can I import hundreds of users in one request?
      - What happens in a bulk user import when some records fail?
      - Will a bulk load update existing users that share an external Id?
      instructions:
      - text: 'Bulk create or update these users: {users}.'
        slots:
          users: requestBody.users
      - text: 'Import this batch of up to 500 user records in one call: {users}.'
        slots:
          users: requestBody.users
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one user and their direct permissions
      effect: read
      questions:
      - How do I look up a single user's profile and directly assigned permissions?
      - What status is a given user in right now?
      instructions:
      - text: Get user {id}.
        slots:
          id: path.id
      - text: Show me the profile of person {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Deprovision a user
      effect: destructive
      questions:
      - What happens to a user's direct roles and permissions when I delete them?
      - How do I permanently offboard a person from the organization?
      instructions:
      - text: Delete user {id}.
        slots:
          id: path.id
      - text: Permanently deprovision the person {id} from our org.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's name or status
      effect: write
      questions:
      - Why can't I change the name of a user that comes from our identity provider?
      - Does deactivating a user revoke their personal access tokens immediately?
      instructions:
      - text: Set the status of user {id} to {status}.
        slots:
          id: path.id
          status: requestBody.status
      - text: Rename user {id} to {first_name} {last_name}.
        slots:
          id: path.id
          first_name: requestBody.first_name
          last_name: requestBody.last_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List all roles a user holds, however inherited
      effect: read
      questions:
      - Which roles does a person have across all workspaces, including ones from groups?
      - Is a user's access coming from a direct grant, a group, or a workspace?
      instructions:
      - text: List every role user {id} holds across all workspaces.
        slots:
          id: path.id
      - text: Show all direct, group and workspace role grants for person {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant the account-wide admin role to a user
      effect: write
      questions:
      - How do I make a person an organization-wide admin?
      - Which role can be given to a user at the account level rather than per workspace?
      instructions:
      - text: Grant account-wide role {role_id} to user {id}.
        slots:
          role_id: requestBody.role_id
          id: path.id
      - text: Make person {id} an organization admin using role {role_id}.
        slots:
          id: path.id
          role_id: requestBody.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}/roles/{role_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a direct account-level role from a user
      effect: destructive
      questions:
      - How do I take the admin role away from a person?
      - Can I remove a role a user inherited from an identity provider group this way?
      instructions:
      - text: Remove direct role {role_id} from user {id}.
        slots:
          role_id: path.role_id
          id: path.id
      - text: Revoke the org-wide admin role {role_id} held directly by person {id}.
        slots:
          role_id: path.role_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's direct resource permissions
      effect: read
      questions:
      - Which connections can a person access through permissions granted straight to them?
      - What direct resource permissions does a user have outside their roles?
      instructions:
      - text: List the direct permissions of user {id}.
        slots:
          id: path.id
      - text: Show which connections person {id} has direct access to.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}/permissions'].post
  update:
    x-apievangelist-phrasing:
      intent: Give a user access to a connection
      effect: write
      questions:
      - How do I let one person query a specific connection without giving them a role?
      - Can I restrict a user to particular operations on a connection?
      instructions:
      - text: Give user {id} {operations} access to connection {resource} as a {type} permission.
        slots:
          id: path.id
          operations: requestBody.operations
          resource: requestBody.resource
          type: requestBody.type
      - text: Grant person {id} permission of type {type} to perform {operations} on {resource}.
        slots:
          id: path.id
          type: requestBody.type
          operations: requestBody.operations
          resource: requestBody.resource
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}/permissions/{permission_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a direct permission from a user
      effect: destructive
      questions:
      - How do I cut off a person's access to one connection without deleting their account?
      - Can I revoke a single direct permission from a user?
      instructions:
      - text: Remove permission {permission_id} from user {id}.
        slots:
          permission_id: path.permission_id
          id: path.id
      - text: Revoke direct permission {permission_id} held by person {id}.
        slots:
          permission_id: path.permission_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}/workspaces/{workspace_id}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's roles in one workspace
      effect: read
      questions:
      - Which roles does a person hold inside one particular workspace?
      - Is a user a workspace admin in a given workspace?
      instructions:
      - text: List the roles user {id} holds in workspace {workspace_id}.
        slots:
          id: path.id
          workspace_id: path.workspace_id
      - text: Show workspace-scoped role grants for person {id} in {workspace_id}.
        slots:
          id: path.id
          workspace_id: path.workspace_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}/workspaces/{workspace_id}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a workspace role to a user
      effect: write
      questions:
      - How do I make a person a workspace_admin in one workspace?
      - Can I assign a custom access role to a user for a single workspace?
      instructions:
      - text: Grant role {role_id} to user {id} in workspace {workspace_id}.
        slots:
          role_id: requestBody.role_id
          id: path.id
          workspace_id: path.workspace_id
      - text: Make person {id} a workspace admin of {workspace_id} with role {role_id}.
        slots:
          id: path.id
          workspace_id: path.workspace_id
          role_id: requestBody.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{id}/workspaces/{workspace_id}/roles/{role_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a workspace role from a user
      effect: destructive
      questions:
      - How do I take a workspace role away from a person in one workspace?
      - Can I strip workspace admin rights from a user without affecting other workspaces?
      instructions:
      - text: Remove role {role_id} from user {id} in workspace {workspace_id}.
        slots:
          role_id: path.role_id
          id: path.id
          workspace_id: path.workspace_id
      - text: Revoke workspace {workspace_id} role {role_id} from person {id}.
        slots:
          workspace_id: path.workspace_id
          role_id: path.role_id
          id: path.id
      method: generated
      generated: '2026-09-26'