Red Hat Hosts API

openapi: 3.1.0
info:
  title: Red Hat Ansible Automation Platform Add-Ons Hosts API
  description: The Red Hat Ansible Automation Platform API provides programmatic access to the automation controller for managing IT infrastructure automation. It supports creating and launching job templates, managing inventories, tracking job execution status, and configuring credentials for connecting to managed hosts and external services.
  version: '2.6'
  contact:
    name: Red Hat Support
    url: https://access.redhat.com/support
  termsOfService: https://www.redhat.com/en/about/terms-use
servers:
- url: https://ansible-platform.example.com
  description: Ansible Automation Platform Server
security:
- bearerAuth: []
tags:
- name: Hosts
  description: Operations for managing hosts registered with Satellite, including provisioning, facts, and power management.
paths:
  /api/v2/hosts:
    get:
      operationId: listHosts
      summary: Red Hat List Hosts
      description: Retrieves a paginated list of all hosts managed by Satellite, including their reported status, operating system, and organization membership.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/SearchParam'
      - $ref: '#/components/parameters/OrderParam'
      responses:
        '200':
          description: Successfully retrieved hosts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedHostList'
              examples:
                Listhosts200Example:
                  summary: Default listHosts 200 response
                  x-microcks-default: true
                  value:
                    total: 10
                    subtotal: 10
                    page: 10
                    per_page: 10
                    results:
                    - id: abc123
                      name: Example Title
                      ip: example_value
                      mac: example_value
                      operatingsystem_name: example_value
                      environment_name: example_value
                      hostgroup_name: example_value
                      organization_name: example_value
                      location_name: example_value
                      global_status: 10
                      content_facet_attributes: {}
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/hosts/{id}:
    get:
      operationId: getHost
      summary: Red Hat Get a Host
      description: Retrieves the details of a specific host, including its network interfaces, operating system, and content view assignment.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Successfully retrieved host details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
              examples:
                Gethost200Example:
                  summary: Default getHost 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    ip: example_value
                    mac: example_value
                    operatingsystem_name: example_value
                    environment_name: example_value
                    hostgroup_name: example_value
                    organization_name: example_value
                    location_name: example_value
                    global_status: 10
                    content_facet_attributes:
                      content_view_name: example_value
                      lifecycle_environment_name: example_value
                      errata_counts:
                        security: 10
                        bugfix: 10
                        enhancement: 10
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateHost
      summary: Red Hat Update a Host
      description: Updates the configuration of an existing host managed by Satellite.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                host:
                  $ref: '#/components/schemas/Host'
            examples:
              UpdatehostRequestExample:
                summary: Default updateHost request
                x-microcks-default: true
                value:
                  host:
                    id: abc123
                    name: Example Title
                    ip: example_value
                    mac: example_value
                    operatingsystem_name: example_value
                    environment_name: example_value
                    hostgroup_name: example_value
                    organization_name: example_value
                    location_name: example_value
                    global_status: 10
                    content_facet_attributes:
                      content_view_name: example_value
                      lifecycle_environment_name: example_value
                      errata_counts:
                        security: 10
                        bugfix: 10
                        enhancement: 10
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
      responses:
        '200':
          description: Host updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
              examples:
                Updatehost200Example:
                  summary: Default updateHost 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    ip: example_value
                    mac: example_value
                    operatingsystem_name: example_value
                    environment_name: example_value
                    hostgroup_name: example_value
                    organization_name: example_value
                    location_name: example_value
                    global_status: 10
                    content_facet_attributes:
                      content_view_name: example_value
                      lifecycle_environment_name: example_value
                      errata_counts:
                        security: 10
                        bugfix: 10
                        enhancement: 10
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteHost
      summary: Red Hat Delete a Host
      description: Deletes a host from Satellite. This removes the host record but does not affect the actual system.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Host deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    IdParam:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: integer
    PageParam:
      name: page
      in: query
      description: The page number for paginated results.
      schema:
        type: integer
        minimum: 1
        default: 1
    SearchParam:
      name: search
      in: query
      description: A scoped search filter expression.
      schema:
        type: string
    OrderParam:
      name: order
      in: query
      description: The sort order for results (e.g., name ASC).
      schema:
        type: string
    PerPageParam:
      name: per_page
      in: query
      description: The number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 20
  schemas:
    PaginatedHostList:
      type: object
      properties:
        total:
          type: integer
          example: 10
        subtotal:
          type: integer
          example: 10
        page:
          type: integer
          example: 10
        per_page:
          type: integer
          example: 10
        results:
          type: array
          items:
            $ref: '#/components/schemas/Host'
          example: []
    Host:
      type: object
      description: A host managed by Red Hat Satellite.
      properties:
        id:
          type: integer
          description: The unique identifier of the host.
          example: abc123
        name:
          type: string
          description: The fully qualified domain name of the host.
          example: Example Title
        ip:
          type: string
          description: The IP address of the host.
          example: example_value
        mac:
          type: string
          description: The MAC address of the primary interface.
          example: example_value
        operatingsystem_name:
          type: string
          description: The operating system name and version.
          example: example_value
        environment_name:
          type: string
          description: The Puppet environment name.
          example: example_value
        hostgroup_name:
          type: string
          description: The host group name.
          example: example_value
        organization_name:
          type: string
          description: The organization name.
          example: example_value
        location_name:
          type: string
          description: The location name.
          example: example_value
        global_status:
          type: integer
          description: The global host status (0=OK, 1=Warning, 2=Error).
          example: 10
        content_facet_attributes:
          type: object
          description: Content-related attributes of the host.
          properties:
            content_view_name:
              type: string
            lifecycle_environment_name:
              type: string
            errata_counts:
              type: object
              properties:
                security:
                  type: integer
                bugfix:
                  type: integer
                enhancement:
                  type: integer
          example: example_value
        created_at:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
  responses:
    NotFoundError:
      description: The requested resource was not found.
    UnauthorizedError:
      description: Authentication credentials are missing or invalid.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token for authenticating API requests to the automation controller.
externalDocs:
  description: Ansible Automation Platform API Documentation
  url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html-single/automation_execution_api_overview/index