Red Hat Satellite Hosts API

openapi: 3.1.0
info:
  title: Red Hat Satellite REST Content Views Hosts API
  description: The Red Hat Satellite REST API provides programmatic access to Red Hat Satellite server functionality including host management, content view management, subscription management, lifecycle environments, and provisioning. The API is built on the Foreman and Katello upstream projects and follows RESTful conventions with JSON request and response bodies.
  version: 6.18.0
  contact:
    name: Red Hat Support
    url: https://access.redhat.com/support
  license:
    name: GPL-3.0
    url: https://www.gnu.org/licenses/gpl-3.0.html
  x-logo:
    url: https://www.redhat.com/profiles/rh/themes/redhatdotcom/img/logo.png
servers:
- url: https://satellite.example.com
  description: Red Hat Satellite Server
security:
- basicAuth: []
- oAuth2: []
tags:
- name: Hosts
  description: Manage hosts registered with Red Hat Satellite including physical, virtual, and cloud instances.
  externalDocs:
    url: https://apidocs.theforeman.org/foreman/latest/apidoc/v2/hosts.html
paths:
  /api/v2/hosts:
    get:
      operationId: listHosts
      summary: List All Hosts
      description: Retrieve a paginated list of all hosts registered with the Satellite server. Supports filtering by organization, location, host group, and search queries.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/organizationIdQuery'
      - $ref: '#/components/parameters/locationIdQuery'
      - name: hostgroup_id
        in: query
        description: Filter hosts by host group identifier.
        schema:
          type: integer
        example: '500123'
      - name: thin
        in: query
        description: Only return the ID and name of each host.
        schema:
          type: boolean
          default: false
        example: true
      - name: include
        in: query
        description: Additional information to include (e.g., parameters, all_parameters).
        schema:
          type: string
          enum:
          - parameters
          - all_parameters
        example: parameters
      - $ref: '#/components/parameters/searchQuery'
      - $ref: '#/components/parameters/orderQuery'
      - $ref: '#/components/parameters/pageQuery'
      - $ref: '#/components/parameters/perPageQuery'
      responses:
        '200':
          description: Successful response containing a list of hosts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of hosts matching the query.
                  subtotal:
                    type: integer
                    description: Number of hosts after filtering.
                  page:
                    type: integer
                    description: Current page number.
                  per_page:
                    type: integer
                    description: Number of results per page.
                  search:
                    type:
                    - string
                    - 'null'
                    description: Applied search filter.
                  sort:
                    type: object
                    properties:
                      by:
                        type:
                        - string
                        - 'null'
                      order:
                        type:
                        - string
                        - 'null'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Host'
              examples:
                Listhosts200Example:
                  summary: Default listHosts 200 response
                  x-microcks-default: true
                  value:
                    total: 10
                    subtotal: 10
                    page: 10
                    per_page: 10
                    search: example_value
                    sort:
                      by: example_value
                      order: example_value
                    results:
                    - id: abc123
                      name: Example Title
                      ip: example_value
                      ip6: example_value
                      mac: example_value
                      environment_id: '500123'
                      hostgroup_id: '500123'
                      hostgroup_name: example_value
                      hostgroup_title: example_value
                      operatingsystem_id: '500123'
                      operatingsystem_name: example_value
                      architecture_id: '500123'
                      architecture_name: example_value
                      domain_id: '500123'
                      domain_name: example_value
                      subnet_id: '500123'
                      subnet_name: example_value
                      subnet6_id: '500123'
                      compute_resource_id: '500123'
                      compute_resource_name: example_value
                      compute_profile_id: '500123'
                      medium_id: '500123'
                      ptable_id: '500123'
                      model_id: '500123'
                      model_name: example_value
                      location_id: '500123'
                      location_name: example_value
                      organization_id: '500123'
                      organization_name: example_value
                      owner_id: '500123'
                      owner_type: User
                      managed: true
                      build: true
                      enabled: true
                      comment: example_value
                      uuid: '500123'
                      global_status: 10
                      global_status_label: OK
                      content_facet_attributes:
                        id: abc123
                        content_view_id: '500123'
                        content_view_name: example_value
                        lifecycle_environment_id: '500123'
                        lifecycle_environment_name: example_value
                        content_source_id: '500123'
                        errata_counts: {}
                        applicable_errata_count: 10
                        upgradable_package_count: 10
                      subscription_facet_attributes:
                        id: abc123
                        uuid: '500123'
                        registered_at: '2026-01-15T10:30:00Z'
                        last_checkin: '2026-01-15T10:30:00Z'
                        service_level: example_value
                        release_version: example_value
                        autoheal: true
                        registered_through: example_value
                      interfaces:
                      - {}
                      puppetclasses:
                      - {}
                      all_puppetclasses:
                      - {}
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
                      installed_at: '2026-01-15T10:30:00Z'
                      last_report: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createHost
      summary: Create a Host
      description: Register a new host with the Satellite server. The host can be managed (provisioned and configured by Satellite) or unmanaged (inventory only).
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/organizationIdQuery'
      - $ref: '#/components/parameters/locationIdQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - host
              properties:
                host:
                  $ref: '#/components/schemas/HostCreate'
            examples:
              CreatehostRequestExample:
                summary: Default createHost request
                x-microcks-default: true
                value:
                  host:
                    name: Example Title
                    location_id: '500123'
                    organization_id: '500123'
                    ip: example_value
                    mac: example_value
                    architecture_id: '500123'
                    domain_id: '500123'
                    subnet_id: '500123'
                    operatingsystem_id: '500123'
                    medium_id: '500123'
                    ptable_id: '500123'
                    compute_resource_id: '500123'
                    compute_profile_id: '500123'
                    hostgroup_id: '500123'
                    root_pass: example_value
                    owner_id: '500123'
                    owner_type: User
                    build: true
                    managed: true
                    comment: example_value
                    content_facet_attributes:
                      content_view_id: '500123'
                      lifecycle_environment_id: '500123'
                      content_source_id: '500123'
                    interfaces_attributes:
                    - {}
      responses:
        '201':
          description: Host created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
              examples:
                Createhost201Example:
                  summary: Default createHost 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    ip: example_value
                    ip6: example_value
                    mac: example_value
                    environment_id: '500123'
                    hostgroup_id: '500123'
                    hostgroup_name: example_value
                    hostgroup_title: example_value
                    operatingsystem_id: '500123'
                    operatingsystem_name: example_value
                    architecture_id: '500123'
                    architecture_name: example_value
                    domain_id: '500123'
                    domain_name: example_value
                    subnet_id: '500123'
                    subnet_name: example_value
                    subnet6_id: '500123'
                    compute_resource_id: '500123'
                    compute_resource_name: example_value
                    compute_profile_id: '500123'
                    medium_id: '500123'
                    ptable_id: '500123'
                    model_id: '500123'
                    model_name: example_value
                    location_id: '500123'
                    location_name: example_value
                    organization_id: '500123'
                    organization_name: example_value
                    owner_id: '500123'
                    owner_type: User
                    managed: true
                    build: true
                    enabled: true
                    comment: example_value
                    uuid: '500123'
                    global_status: 10
                    global_status_label: OK
                    content_facet_attributes:
                      id: abc123
                      content_view_id: '500123'
                      content_view_name: example_value
                      lifecycle_environment_id: '500123'
                      lifecycle_environment_name: example_value
                      content_source_id: '500123'
                      errata_counts:
                        security: 10
                        bugfix: 10
                        enhancement: 10
                        total: 10
                      applicable_errata_count: 10
                      upgradable_package_count: 10
                    subscription_facet_attributes:
                      id: abc123
                      uuid: '500123'
                      registered_at: '2026-01-15T10:30:00Z'
                      last_checkin: '2026-01-15T10:30:00Z'
                      service_level: example_value
                      release_version: example_value
                      autoheal: true
                      registered_through: example_value
                    interfaces:
                    - id: abc123
                      mac: example_value
                      ip: example_value
                      ip6: example_value
                      type: interface
                      name: Example Title
                      subnet_id: '500123'
                      subnet6_id: '500123'
                      domain_id: '500123'
                      identifier: example_value
                      managed: true
                      primary: true
                      provision: true
                      virtual: true
                      tag: example_value
                      mtu: example_value
                      attached_to: example_value
                    puppetclasses:
                    - {}
                    all_puppetclasses:
                    - {}
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
                    installed_at: '2026-01-15T10:30:00Z'
                    last_report: '2026-01-15T10:30:00Z'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/hosts/{id}:
    get:
      operationId: showHost
      summary: Show a Host
      description: Retrieve details for a specific host by its identifier.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/hostId'
      responses:
        '200':
          description: Successful response containing host details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
              examples:
                Showhost200Example:
                  summary: Default showHost 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    ip: example_value
                    ip6: example_value
                    mac: example_value
                    environment_id: '500123'
                    hostgroup_id: '500123'
                    hostgroup_name: example_value
                    hostgroup_title: example_value
                    operatingsystem_id: '500123'
                    operatingsystem_name: example_value
                    architecture_id: '500123'
                    architecture_name: example_value
                    domain_id: '500123'
                    domain_name: example_value
                    subnet_id: '500123'
                    subnet_name: example_value
                    subnet6_id: '500123'
                    compute_resource_id: '500123'
                    compute_resource_name: example_value
                    compute_profile_id: '500123'
                    medium_id: '500123'
                    ptable_id: '500123'
                    model_id: '500123'
                    model_name: example_value
                    location_id: '500123'
                    location_name: example_value
                    organization_id: '500123'
                    organization_name: example_value
                    owner_id: '500123'
                    owner_type: User
                    managed: true
                    build: true
                    enabled: true
                    comment: example_value
                    uuid: '500123'
                    global_status: 10
                    global_status_label: OK
                    content_facet_attributes:
                      id: abc123
                      content_view_id: '500123'
                      content_view_name: example_value
                      lifecycle_environment_id: '500123'
                      lifecycle_environment_name: example_value
                      content_source_id: '500123'
                      errata_counts:
                        security: 10
                        bugfix: 10
                        enhancement: 10
                        total: 10
                      applicable_errata_count: 10
                      upgradable_package_count: 10
                    subscription_facet_attributes:
                      id: abc123
                      uuid: '500123'
                      registered_at: '2026-01-15T10:30:00Z'
                      last_checkin: '2026-01-15T10:30:00Z'
                      service_level: example_value
                      release_version: example_value
                      autoheal: true
                      registered_through: example_value
                    interfaces:
                    - id: abc123
                      mac: example_value
                      ip: example_value
                      ip6: example_value
                      type: interface
                      name: Example Title
                      subnet_id: '500123'
                      subnet6_id: '500123'
                      domain_id: '500123'
                      identifier: example_value
                      managed: true
                      primary: true
                      provision: true
                      virtual: true
                      tag: example_value
                      mtu: example_value
                      attached_to: example_value
                    puppetclasses:
                    - {}
                    all_puppetclasses:
                    - {}
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
                    installed_at: '2026-01-15T10:30:00Z'
                    last_report: '2026-01-15T10:30:00Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateHost
      summary: Update a Host
      description: Update the attributes of an existing host.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/hostId'
      - $ref: '#/components/parameters/organizationIdQuery'
      - $ref: '#/components/parameters/locationIdQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - host
              properties:
                host:
                  $ref: '#/components/schemas/HostUpdate'
            examples:
              UpdatehostRequestExample:
                summary: Default updateHost request
                x-microcks-default: true
                value:
                  host:
                    name: Example Title
                    ip: example_value
                    mac: example_value
                    architecture_id: '500123'
                    domain_id: '500123'
                    subnet_id: '500123'
                    operatingsystem_id: '500123'
                    hostgroup_id: '500123'
                    location_id: '500123'
                    organization_id: '500123'
                    owner_id: '500123'
                    owner_type: User
                    build: true
                    managed: true
                    comment: example_value
                    content_facet_attributes:
                      content_view_id: '500123'
                      lifecycle_environment_id: '500123'
                      content_source_id: '500123'
                    interfaces_attributes:
                    - {}
      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
                    ip6: example_value
                    mac: example_value
                    environment_id: '500123'
                    hostgroup_id: '500123'
                    hostgroup_name: example_value
                    hostgroup_title: example_value
                    operatingsystem_id: '500123'
                    operatingsystem_name: example_value
                    architecture_id: '500123'
                    architecture_name: example_value
                    domain_id: '500123'
                    domain_name: example_value
                    subnet_id: '500123'
                    subnet_name: example_value
                    subnet6_id: '500123'
                    compute_resource_id: '500123'
                    compute_resource_name: example_value
                    compute_profile_id: '500123'
                    medium_id: '500123'
                    ptable_id: '500123'
                    model_id: '500123'
                    model_name: example_value
                    location_id: '500123'
                    location_name: example_value
                    organization_id: '500123'
                    organization_name: example_value
                    owner_id: '500123'
                    owner_type: User
                    managed: true
                    build: true
                    enabled: true
                    comment: example_value
                    uuid: '500123'
                    global_status: 10
                    global_status_label: OK
                    content_facet_attributes:
                      id: abc123
                      content_view_id: '500123'
                      content_view_name: example_value
                      lifecycle_environment_id: '500123'
                      lifecycle_environment_name: example_value
                      content_source_id: '500123'
                      errata_counts:
                        security: 10
                        bugfix: 10
                        enhancement: 10
                        total: 10
                      applicable_errata_count: 10
                      upgradable_package_count: 10
                    subscription_facet_attributes:
                      id: abc123
                      uuid: '500123'
                      registered_at: '2026-01-15T10:30:00Z'
                      last_checkin: '2026-01-15T10:30:00Z'
                      service_level: example_value
                      release_version: example_value
                      autoheal: true
                      registered_through: example_value
                    interfaces:
                    - id: abc123
                      mac: example_value
                      ip: example_value
                      ip6: example_value
                      type: interface
                      name: Example Title
                      subnet_id: '500123'
                      subnet6_id: '500123'
                      domain_id: '500123'
                      identifier: example_value
                      managed: true
                      primary: true
                      provision: true
                      virtual: true
                      tag: example_value
                      mtu: example_value
                      attached_to: example_value
                    puppetclasses:
                    - {}
                    all_puppetclasses:
                    - {}
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
                    installed_at: '2026-01-15T10:30:00Z'
                    last_report: '2026-01-15T10:30:00Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteHost
      summary: Delete a Host
      description: Remove a host from the Satellite server.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/hostId'
      responses:
        '200':
          description: Host deleted successfully.
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/hosts/{id}/power:
    put:
      operationId: hostPowerAction
      summary: Execute a Power Operation on a Host
      description: Perform a power management action on a host such as powering on, powering off, or rebooting. Requires a BMC or compute resource association.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/hostId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - power_action
              properties:
                power_action:
                  type: string
                  description: Power action to perform.
                  enum:
                  - start
                  - stop
                  - reboot
                  - status
            examples:
              HostpoweractionRequestExample:
                summary: Default hostPowerAction request
                x-microcks-default: true
                value:
                  power_action: start
      responses:
        '200':
          description: Power action executed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  power:
                    type: string
                  id:
                    type: integer
              examples:
                Hostpoweraction200Example:
                  summary: Default hostPowerAction 200 response
                  x-microcks-default: true
                  value:
                    power: example_value
                    id: abc123
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    HostCreate:
      type: object
      description: Parameters for creating a new host.
      required:
      - name
      - organization_id
      - location_id
      properties:
        name:
          type: string
          description: Hostname or FQDN.
          example: Example Title
        location_id:
          type: integer
          description: Location identifier.
          example: '500123'
        organization_id:
          type: integer
          description: Organization identifier.
          example: '500123'
        ip:
          type: string
          description: IPv4 address (not required when using DHCP proxy).
          format: ipv4
          example: example_value
        mac:
          type: string
          description: MAC address (required for managed bare metal hosts).
          example: example_value
        architecture_id:
          type: integer
          description: Architecture identifier (required if managed).
          example: '500123'
        domain_id:
          type: integer
          description: Domain identifier (required if managed).
          example: '500123'
        subnet_id:
          type: integer
          description: Subnet identifier (required if managed).
          example: '500123'
        operatingsystem_id:
          type: integer
          description: Operating system identifier (required if managed).
          example: '500123'
        medium_id:
          type: integer
          description: Installation medium identifier (required for non-image provisioning if managed).
          example: '500123'
        ptable_id:
          type: integer
          description: Partition table identifier (required if managed and no custom partition layout).
          example: '500123'
        compute_resource_id:
          type: integer
          description: Compute resource identifier. Null indicates bare metal.
          example: '500123'
        compute_profile_id:
          type: integer
          description: Compute profile identifier.
          example: '500123'
        hostgroup_id:
          type: integer
          description: Host group identifier.
          example: '500123'
        root_pass:
          type: string
          description: Root password (required if managed unless inherited).
          format: password
          example: example_value
        owner_id:
          type: integer
          description: Owner identifier.
          example: '500123'
        owner_type:
          type: string
          description: Owner type.
          enum:
          - User
          - Usergroup
          example: User
        build:
          type: boolean
          description: Enable build mode for provisioning.
          example: true
        managed:
          type: boolean
          description: Whether the host should be managed by Satellite.
          example: true
        comment:
          type: string
          description: Additional information about the host.
          example: example_value
        content_facet_attributes:
          type: object
          properties:
            content_view_id:
              type: integer
              description: Content view identifier.
            lifecycle_environment_id:
              type: integer
              description: Lifecycle environment identifier.
            content_source_id:
              type: integer
              description: Content source (Capsule) identifier.
          example: example_value
        interfaces_attributes:
          type: array
          description: Network interface configurations.
          items:
            $ref: '#/components/schemas/HostInterfaceCreate'
          example: []
    HostInterface:
      type: object
      description: A network interface associated with a host.
      properties:
        id:
          type: integer
          example: abc123
        mac:
          type:
          - string
          - 'null'
          example: example_value
        ip:
          type:
          - string
          - 'null'
          format: ipv4
          example: example_value
        ip6:
          type:
          - string
          - 'null'
          format: ipv6
          example: example_value
        type:
          type: string
          enum:
          - interface
          - bmc
          - bond
          - bridge
          example: interface
        name:
          type:
          - string
          - 'null'
          example: Example Title
        subnet_id:
          type:
          - integer
          - 'null'
          example: '500123'
        subnet6_id:
          type:
          - integer
          - 'null'
          example: '500123'
        domain_id:
          type:
          - integer
          - 'null'
          example: '500123'
        identifier:
          type:
          - string
          - 'null'
          description: Device identifier (e.g., eth0, ens192).
          example: example_value
        managed:
          type: boolean
          example: true
        primary:
          type: boolean
          example: true
        provision:
          type: boolean
          example: true
        virtual:
          type: boolean
          example: true
        tag:
          type:
          - string
          - 'null'
          description: VLAN tag.
          example: example_value
        mtu:
          type:
          - integer
          - 'null'
          description: Maximum transmission unit.
          example: example_value
        attached_to:
          type:
          - string
          - 'null'
          description: Parent interface identifier.
          example: example_value
    Host:
      type: object
      description: A host registered with Red Hat 

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/red-hat-satellite/refs/heads/main/openapi/red-hat-satellite-hosts-api-openapi.yml