Red Hat Hosts API

openapi: 3.2.0
info:
  title: Red Hat Satellite Hosts API
  description: The Red Hat Satellite API provides programmatic access to managing Satellite infrastructure, including content management, host provisioning, patch management, and configuration across large-scale Linux environments. It covers both the Foreman API for host and infrastructure management and the Katello API for content and subscription management.
  version: '6.16'
  contact:
    name: Red Hat Support
    url: https://access.redhat.com/support
  termsOfService: https://www.redhat.com/en/about/terms-use
servers:
- url: https://satellite.example.com
  description: Red Hat Satellite Server
security:
- basicAuth: []
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:
    SearchParam:
      name: search
      in: query
      description: A scoped search filter expression.
      schema:
        type: string
    PageParam:
      name: page
      in: query
      description: The page number for paginated results.
      schema:
        type: integer
        minimum: 1
        default: 1
    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
    IdParam:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: integer
  schemas:
    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'
    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: []
  responses:
    UnauthorizedError:
      description: Authentication credentials are missing or invalid.
    NotFoundError:
      description: The requested resource was not found.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using a valid Satellite username and password. Alternatively, a personal access token can be used.
externalDocs:
  description: Red Hat Satellite REST API Documentation
  url: https://docs.redhat.com/en/documentation/red_hat_satellite/6.16/html-single/using_the_satellite_rest_api/index