ControlUp Host pool scaling policies API

openapi: 3.2.0
info:
  title: DaaS IQ Host pool scaling policies API
  description: 'Multi-cloud Virtual Desktop Infrastructure Management API (Default Version: v1.0)


    🔒 **Authentication**


    This API supports two authentication methods:


    **1. API Key (Bearer Token)** - Recommended for programmatic access

    - Create an API key at [API Key Management](https://support.controlup.com/docs/create-an-api-key)

    - Include in requests: `Authorization: Bearer YOUR_API_KEY`


    **2. Cookie Authentication** - For browser-based access

    - Login via DEX authentication service

    - The `user_dex_token` cookie will be automatically included'
  contact:
    name: ControlUp Support
    url: https://controlup.com/support
    email: support@controlup.com
  version: v1
  x-build-version: 1.0.107
servers:
- url: https://api.controlup.com/daas-iq/v1
tags:
- name: Host pool scaling policies
paths:
  /cloud/host-pools/{hostPoolId}/scaling-policy:
    get:
      tags:
      - Host pool scaling policies
      summary: Get scaling policy for a host pool
      description: 'Returns the pool''s weekly autoscale schedule: time blocks and which scaling profile each one assigns.

        Returns assignments only: profile bodies such as thresholds and host counts are not expanded,

        and the schedule does not indicate which block is in effect right now.'
      operationId: GetHostPoolScalingPolicy
      parameters:
      - name: hostPoolId
        in: path
        description: The unique host pool identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved the scaling policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklyScheduleDto'
              example:
                timeZoneId: America/New_York
                schedules:
                - daysOfWeek:
                  - monday
                  - tuesday
                  - wednesday
                  - thursday
                  - friday
                  startTime: 08:00:00
                  endTime: '18:00:00'
                  scalingProfileId: 67db81b6-9381-4c62-89fc-6e29ca607a17
                  priority: 100
                scaleInRestrictions:
                - daysOfWeek:
                  - monday
                  - tuesday
                  - wednesday
                  - thursday
                  - friday
                  startTime: '12:00:00'
                  endTime: '13:00:00'
        '204':
          description: No scaling policy is configured for this host pool.
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have manage scaling permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified host pool does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
    put:
      tags:
      - Host pool scaling policies
      summary: Save scaling policy for a host pool
      description: Creates or updates the scaling policy for a specific host pool with time blocks and profile assignments.
      operationId: SaveHostPoolScalingPolicy
      parameters:
      - name: hostPoolId
        in: path
        description: The unique host pool identifier.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The scaling policy data with time blocks and profile assignments.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WeeklyScheduleDto'
            example:
              timeZoneId: America/New_York
              schedules:
              - daysOfWeek:
                - monday
                - tuesday
                - wednesday
                - thursday
                - friday
                startTime: 08:00:00
                endTime: '18:00:00'
                scalingProfileId: 67db81b6-9381-4c62-89fc-6e29ca607a17
                priority: 100
              scaleInRestrictions:
              - daysOfWeek:
                - monday
                - tuesday
                - wednesday
                - thursday
                - friday
                startTime: '12:00:00'
                endTime: '13:00:00'
        required: true
      responses:
        '200':
          description: Successfully saved the scaling policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklyScheduleDto'
              example:
                timeZoneId: America/New_York
                schedules:
                - daysOfWeek:
                  - monday
                  - tuesday
                  - wednesday
                  - thursday
                  - friday
                  startTime: 08:00:00
                  endTime: '18:00:00'
                  scalingProfileId: 67db81b6-9381-4c62-89fc-6e29ca607a17
                  priority: 100
                scaleInRestrictions:
                - daysOfWeek:
                  - monday
                  - tuesday
                  - wednesday
                  - thursday
                  - friday
                  startTime: '12:00:00'
                  endTime: '13:00:00'
        '400':
          description: Bad request. Invalid scaling policy data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have manage scaling permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified host pool does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict. Ownership claim failed due to concurrent updates, host pool already owned by another organization, or an Azure-level rejection (e.g., disabled subscription).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
    delete:
      tags:
      - Host pool scaling policies
      summary: Delete scaling policy for a host pool
      description: Removes the scaling policy from a specific host pool.
      operationId: DeleteHostPoolScalingPolicy
      parameters:
      - name: hostPoolId
        in: path
        description: The unique host pool identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Successfully deleted the scaling policy.
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have manage scaling permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. No scaling policy exists for this host pool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict. Ownership release failed due to concurrent updates, ownership belongs to another organization, or an Azure-level rejection (e.g., disabled subscription).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
  /cloud/host-pools/{hostPoolId}/scaling-policy/active-profile:
    get:
      tags:
      - Host pool scaling policies
      summary: Get active scaling profile for a host pool
      description: 'Returns the one scaling profile in effect at the current UTC time, resolved from the pool''s weekly schedule.

        Covers the present moment only, not the rest of the week.'
      operationId: GetHostPoolActiveScalingProfile
      parameters:
      - name: hostPoolId
        in: path
        description: The unique host pool identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved the active scaling profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScalingProfileResponseDto'
        '204':
          description: No active profile at this time.
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have manage scaling permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. The specified host pool does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
components:
  schemas:
    WeeklyScheduleBlockDto:
      required:
      - daysOfWeek
      - endTime
      - scalingProfileId
      - startTime
      type: object
      properties:
        daysOfWeek:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/DayOfWeek'
          description: Days of the week when this schedule block is active.
        startTime:
          type: string
          description: Start time of the day (HH:mm format, e.g., "09:30").
          format: time
        endTime:
          type: string
          description: 'End time of the day (HH:mm format, e.g., "17:30").

            Must be different from StartTime to define a valid time range.'
          format: time
        scalingProfileId:
          type: string
          description: The scaling profile ID to apply during this time block.
          format: uuid
        priority:
          maximum: 2147483647
          minimum: 1
          type:
          - integer
          - 'null'
          description: 'Priority for overlapping schedule blocks (higher values take precedence).

            Optional; defaults to 100 if not provided. Must be at least 1 when specified

            (priority 0 is reserved for the default profile).'
          format: int32
      additionalProperties: false
      description: Represents a single time block within a weekly scaling schedule.
    ScalingStrategyDto:
      required:
      - provisioningMode
      - smartMinimums
      type: object
      properties:
        provisioningMode:
          $ref: '#/components/schemas/ProvisioningMode'
        staticConfig:
          $ref: '#/components/schemas/StaticConfigDto'
        elasticConfig:
          $ref: '#/components/schemas/ElasticConfigDto'
        smartMinimums:
          $ref: '#/components/schemas/SmartMinimumsDto'
      additionalProperties: false
      description: Scaling strategy including provisioning mode and mode-specific configuration.
    StaticConfigDto:
      required:
      - createAdditionalHostsIfNeeded
      - hostsToPowerOn
      type: object
      properties:
        hostsToPowerOn:
          maximum: 2147483647
          minimum: 0
          type: integer
          description: Number of hosts to keep powered on.
          format: int32
        createAdditionalHostsIfNeeded:
          type: boolean
          description: Whether to create additional hosts if not enough exist in the pool.
      additionalProperties: false
      description: Static provisioning configuration.
    ScaleTriggersDto:
      required:
      - freeSessionsThreshold
      type: object
      properties:
        cpuThresholdPercent:
          maximum: 100
          minimum: 5
          type:
          - integer
          - 'null'
          description: CPU usage threshold percentage. Null (omitted) means the metric is disabled and will not be evaluated.
          format: int32
        memoryThresholdPercent:
          maximum: 100
          minimum: 5
          type:
          - integer
          - 'null'
          description: Memory usage threshold percentage. Null (omitted) means the metric is disabled and will not be evaluated.
          format: int32
        freeSessionsThreshold:
          maximum: 2147483647
          minimum: 0
          type: integer
          description: Free sessions threshold for scaling actions. Required — cannot be disabled.
          format: int32
      additionalProperties: false
      description: Performance thresholds that trigger scaling actions.
    ElasticScalingMode:
      enum:
      - powerManagementOnly
      - dynamicHosts
      type: string
      description: Defines the elastic scaling mode for host pool capacity management.
    ProvisioningMode:
      enum:
      - static
      - elastic
      type: string
      description: Defines the provisioning and scaling mode for host pools.
    ScalingProfileResponseDto:
      required:
      - color
      - experience
      - id
      - name
      - strategy
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 3
          type: string
          description: User-friendly name for the scaling profile.
        description:
          maxLength: 500
          minLength: 0
          type:
          - string
          - 'null'
          description: Optional description for the scaling profile.
        color:
          maxLength: 50
          minLength: 1
          type: string
          description: 'Color identifier for this scaling profile. The UI defines available color IDs and their visual representation.

            Examples: "blue", "primary-1", "accent-red", etc.'
        strategy:
          $ref: '#/components/schemas/ScalingStrategyDto'
        experience:
          $ref: '#/components/schemas/UserExperienceDto'
        id:
          type: string
          description: Unique identifier for the scaling profile.
          format: uuid
      additionalProperties: false
      description: 'Full scaling profile response including all configuration details.

        Returned when fetching a specific scaling profile by ID.'
    ErrorResponse:
      required:
      - status
      - title
      - traceId
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem.
        errors:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
          description: 'Dictionary of field-specific validation errors (only present for validation failures).

            Key is the field name, value is an array of error messages for that field.'
        traceId:
          type: string
          description: Request ID (cu-request-id) for tracking and debugging purposes.
      additionalProperties: false
      description: 'Standard error body the API returns when a request fails validation or cannot be completed.

        Follows RFC 7807 Problem Details with additional `errors` and `traceId` fields.'
    NotificationSettingsDto:
      required:
      - allowSnooze
      - gracePeriodMinutes
      - maximumSnoozes
      - notificationMessage
      - notificationTitle
      type: object
      properties:
        gracePeriodMinutes:
          maximum: 2147483647
          minimum: 1
          type: integer
          description: Grace period in minutes before users are logged off after notification.
          format: int32
        notificationTitle:
          maxLength: 200
          minLength: 1
          type: string
          description: Notification title displayed to users.
        notificationMessage:
          maxLength: 2000
          minLength: 1
          type: string
          description: Notification message displayed to users.
        allowSnooze:
          type: boolean
          description: Whether users are allowed to snooze the notification.
        maximumSnoozes:
          maximum: 2147483647
          minimum: 0
          type: integer
          description: Maximum number of times users can snooze notifications.
          format: int32
      additionalProperties: false
      description: User notification settings when sessions are about to be ended.
    ElasticPerformanceDto:
      required:
      - aggressiveness
      - scaleInTriggers
      - scaleOutTriggers
      - stabilizationWindowMinutes
      type: object
      properties:
        scaleOutTriggers:
          $ref: '#/components/schemas/ScaleTriggersDto'
        scaleInTriggers:
          $ref: '#/components/schemas/ScaleTriggersDto'
        aggressiveness:
          $ref: '#/components/schemas/ScalingAggressiveness'
        stabilizationWindowMinutes:
          maximum: 60
          minimum: 1
          type: integer
          description: Stabilization window in minutes before evaluating scaling actions.
          format: int32
      additionalProperties: false
      description: Performance settings for elastic provisioning.
    SmartMinimumsDto:
      required:
      - enabled
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether smart minimums is enabled.
        utilizationThresholdPercent:
          maximum: 100
          minimum: 1
          type:
          - integer
          - 'null'
          description: Utilization threshold percentage below which the minimum hosts rule is ignored.
          format: int32
        timeWindowMinutes:
          maximum: 2147483647
          minimum: 1
          type:
          - integer
          - 'null'
          description: Time window in minutes to evaluate utilization before scaling down.
          format: int32
        scaleDownToHostCount:
          maximum: 2147483647
          minimum: 0
          type:
          - integer
          - 'null'
          description: Number of hosts to scale down to when utilization is below threshold.
          format: int32
      additionalProperties: false
      description: Smart minimums configuration to prevent scaling down during low utilization.
    ScaleInRestrictionBlockDto:
      required:
      - daysOfWeek
      - endTime
      - startTime
      type: object
      properties:
        daysOfWeek:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/DayOfWeek'
          description: Days of the week when this restriction is active.
        startTime:
          type: string
          description: Start time of the restriction window (HH:mm format, e.g., "08:30").
          format: time
        endTime:
          type: string
          description: 'End time of the restriction window (HH:mm format, e.g., "09:30").

            Midnight crossing is supported (endTime < startTime means crosses midnight).'
          format: time
      additionalProperties: false
      description: 'Represents a single scale-in restriction time block within a weekly scaling schedule.

        When any restriction block is active, scale-in actions are suppressed for the host pool.'
    ScalingAggressiveness:
      enum:
      - gentle
      - balanced
      - aggressive
      type: string
      description: Defines the aggressiveness level for scaling operations.
    WeeklyScheduleDto:
      required:
      - schedules
      - timeZoneId
      type: object
      properties:
        timeZoneId:
          minLength: 1
          type: string
          description: The IANA timezone identifier (e.g., "America/New_York", "Europe/London").
        defaultScalingProfileId:
          type:
          - string
          - 'null'
          description: 'Optional off-hours scaling profile ID. When set, stored as a priority-0 24/7 schedule

            that applies whenever no higher-priority schedule block is active.

            Must differ from every ControlUp.Foundry.Api.Dtos.Cloud.WeeklyScheduleDto.Schedules block profile.

            Omit for no scaling outside configured schedule blocks.'
          format: uuid
        schedules:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/WeeklyScheduleBlockDto'
          description: Collection of scheduled time blocks with their associated scaling profiles.
        scaleInRestrictions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ScaleInRestrictionBlockDto'
          description: 'Collection of scale-in restriction time blocks.

            When any restriction block is active, scale-in actions are suppressed for the host pool.'
      additionalProperties: false
      description: Represents a weekly scaling schedule for a host pool.
    DayOfWeek:
      enum:
      - sunday
      - monday
      - tuesday
      - wednesday
      - thursday
      - friday
      - saturday
      type: string
      description: Day of the week, Sunday through Saturday.
    UserExperienceDto:
      required:
      - notifications
      type: object
      properties:
        notifications:
          $ref: '#/components/schemas/NotificationSettingsDto'
      additionalProperties: false
      description: User experience settings for scaling operations.
    ElasticConfigDto:
      required:
      - burstBatchSize
      - elasticScalingMode
      - maxHosts
      - minHosts
      - performance
      type: object
      properties:
        minHosts:
          maximum: 2147483647
          minimum: 0
          type: integer
          description: Minimum number of hosts (floor) that should be available.
          format: int32
        maxHosts:
          maximum: 2147483647
          minimum: 0
          type: integer
          description: Maximum number of hosts (ceiling) that can be active.
          format: int32
        burstBatchSize:
          maximum: 2147483647
          minimum: 1
          type: integer
          description: Number of hosts to start/stop in a single scaling operation.
          format: int32
        elasticScalingMode:
          $ref: '#/components/schemas/ElasticScalingMode'
        performance:
          $ref: '#/components/schemas/ElasticPerformanceDto'
      additionalProperties: false
      description: Elastic provisioning configuration.
  securitySchemes:
    BearerAuth:
      type: http
      description: '**API Key Authentication** (Recommended)


        [Learn how to create an API key](https://api.controlup.io/reference/how-to-create-api-keys).'
      scheme: bearer
      bearerFormat: JWT
    CookieAuth:
      type: apiKey
      description: '**Cookie Authentication** (Browser use)


        ⚠️ The ''Authorize'' button cannot set cookies due to browser security.


        To authenticate in browser:

        1. Login via DEX authentication service (same browser session)

        2. Or use DevTools Console: `document.cookie = "user_dex_token=YOUR_TOKEN; path=/"`'
      name: user_dex_token
      in: cookie
x-readme:
  explorer-enabled: true
  proxy-enabled: false
  samples-languages:
  - shell
  - powershell
  - node
  - javascript
  - python
  - c
  - clojure
  - cplusplus
  - csharp
  - http
  - go
  - java
  - json
  - kotlin
  - objectivec
  - ocaml
  - php
  - r
  - ruby
  - swift