ControlUp Host pool session host deployments API

openapi: 3.2.0
info:
  title: DaaS IQ Host pool session host deployments 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 session host deployments
paths:
  /cloud/host-pools/{hostPoolId}/session-host-deployments:
    post:
      tags:
      - Host pool session host deployments
      summary: Create session hosts
      description: "Adds session hosts to an existing host pool. The new hosts are built from the VM settings already saved\non that pool, so those settings must be in place before this call and are not accepted in the request body.\n            \nFor pools with a DynamicHosts scaling profile, scale-in cleanup treats all stopped\nzero-session hosts above MinHosts as elastic capacity, including manually added hosts."
      operationId: CreateSessionHostDeployment
      parameters:
      - name: hostPoolId
        in: path
        description: Foundry host pool identifier.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Session host deployment request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionHostDeploymentRequest'
            example:
              count: 3
        required: true
      responses:
        '201':
          description: Session host deployment job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreatedDto'
              example:
                id: a1b2c3d4-5678-90ab-cdef-1234567890ab
                jobType: cloudResourceImport
                action: Cloud Resource Import
                jobUrl: https://api.example.com/api/v1/jobs/a1b2c3d4-5678-90ab-cdef-1234567890ab
                statusUrl: https://api.example.com/api/v1/jobs/a1b2c3d4-5678-90ab-cdef-1234567890ab/status
                logsUrl: https://api.example.com/api/v1/jobs/a1b2c3d4-5678-90ab-cdef-1234567890ab/logs
                message: Import job created successfully. Poll statusUrl for progress updates.
        '400':
          description: Bad request. Invalid payload or precondition failed.
          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 create host pool permission.
          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. Host creation is already in progress, or planned VM names already 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:
    JobType:
      enum:
      - cloudResourceImport
      - inventorySync
      - metricCollection
      - costCollection
      - budgetCollection
      - sessionStateCollection
      - sessionHostAction
      - cloudResourceAction
      - cloudCredentialVerification
      - cloudTenantResourceImport
      - masterImageDeploy
      - masterImagePublish
      - masterImageSync
      - masterImageCleanup
      - masterImageVersionDelete
      - masterImagePublishCleanup
      - licenseUsageReport
      - hostPoolOrphanedResourcesCleanup
      - hostPoolCreate
      - hostPoolSessionHostCreate
      - hostPoolSessionHostBatchCreate
      - hostPoolDelete
      type: string
      description: 'Defines the types of background jobs supported by the system.

        Each job type is processed by a specific worker and has its own parameter structure.'
    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.'
    JobCreatedDto:
      required:
      - action
      - id
      - jobType
      - jobUrl
      - logsUrl
      - message
      - statusUrl
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the created job.
          format: uuid
        jobType:
          $ref: '#/components/schemas/JobType'
        action:
          type: string
          description: 'Job action identifier.

            For standard jobs, this matches the JobType formatted with spaces (e.g., "Cloud Resource Import").

            For action jobs, this is the specific action name formatted with spaces (e.g., "Start", "Stop").'
        jobUrl:
          type: string
          description: URL to get full job details (includes parameters).
        statusUrl:
          type: string
          description: 'URL to poll for lightweight status updates (no parameters).

            Poll this endpoint every 2-5 seconds while job is running.'
        logsUrl:
          type: string
          description: URL to get job logs in JSON format.
        message:
          type: string
          description: 'Human-readable message about job creation.

            Example: "Import job created successfully. Poll statusUrl for progress updates."'
      additionalProperties: false
      description: 'Lightweight response returned when a job is created.

        Contains only essential information needed to track the job.

        Use the statusUrl to poll for updates and jobUrl to get full details.'
    CreateSessionHostDeploymentRequest:
      required:
      - count
      type: object
      properties:
        count:
          maximum: 100
          minimum: 1
          type: integer
          description: Number of session hosts to create.
          format: int32
      additionalProperties: false
      description: Request to add session hosts to an existing Azure Virtual Desktop host pool.
  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