Red Hat Satellite Hosts API

openapi: 3.2.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:
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                    example: Unable to authenticate user.
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource not found.
    UnprocessableEntity:
      description: The request was well-formed but contained validation errors.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  id:
                    type: integer
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                  full_messages:
                    type: array
                    items:
                      type: string
  parameters:
    orderQuery:
      name: order
      in: query
      description: Sort field and direction (e.g., "name ASC" or "id DESC").
      schema:
        type: string
    locationIdQuery:
      name: location_id
      in: query
      description: Set the current location context for the request.
      schema:
        type: integer
    searchQuery:
      name: search
      in: query
      description: Scoped search query string to filter results. Supports field-based search syntax (e.g., "name ~ web*").
      schema:
        type: string
    hostId:
      name: id
      in: path
      required: true
      description: Host identifier (numeric ID or FQDN).
      schema:
        type: string
    perPageQuery:
      name: per_page
      in: query
      description: Number of results per page. Use "all" to retrieve all results without pagination.
      schema:
        oneOf:
        - type: integer
          minimum: 1
        - type: string
          enum:
          - all
        default: 20
    organizationIdQuery:
      name: organization_id
      in: query
      description: Set the current organization context for the request.
      schema:
        type: integer
    pageQuery:
      name: page
      in: query
      description: Page number for paginated results (starting at 1).
      schema:
        type: integer
        minimum: 1
        default: 1
  schemas:
    Host:
      type: object
      description: A host registered with Red Hat Satellite representing a physical, virtual, or cloud system.
      properties:
        id:
          type: integer
          description: Unique identifier for the host.
          example: abc123
        name:
          type: string
          description: Fully qualified domain name (FQDN) of the host.
          example: Example Title
        ip:
          type:
          - string
          - 'null'
          description: Primary IPv4 address of the host.
          format: ipv4
          example: example_value
        ip6:
          type:
          - string
          - 'null'
          description: Primary IPv6 address of the host.
          format: ipv6
          example: example_value
        mac:
          type:
          - string
          - 'null'
          description: Primary MAC address of the host.
          example: example_value
        environment_id:
          type:
          - integer
          - 'null'
          description: Puppet environment identifier.
          example: '500123'
        hostgroup_id:
          type:
          - integer
          - 'null'
          description: Host group identifier.
          example: '500123'
        hostgroup_name:
          type:
          - string
          - 'null'
          description: Host group name.
          example: example_value
        hostgroup_title:
          type:
          - string
          - 'null'
          description: Full host group title including parent groups.
          example: example_value
        operatingsystem_id:
          type:
          - integer
          - 'null'
          description: Operating system identifier.
          example: '500123'
        operatingsystem_name:
          type:
          - string
          - 'null'
          description: Operating system name and version.
          example: example_value
        architecture_id:
          type:
          - integer
          - 'null'
          description: Architecture identifier.
          example: '500123'
        architecture_name:
          type:
          - string
          - 'null'
          description: Architecture name (e.g., x86_64).
          example: example_value
        domain_id:
          type:
          - integer
          - 'null'
          description: DNS domain identifier.
          example: '500123'
        domain_name:
          type:
          - string
          - 'null'
          description: DNS domain name.
          example: example_value
        subnet_id:
          type:
          - integer
          - 'null'
          description: IPv4 subnet identifier.
          example: '500123'
        subnet_name:
          type:
          - string
          - 'null'
          description: IPv4 subnet name.
          example: example_value
        subnet6_id:
          type:
          - integer
          - 'null'
     

# --- 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