Red Hat Satellite API

openapi: 3.1.0
info:
  title: Red Hat Satellite 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
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
servers:
- url: https://satellite.example.com
  description: Red Hat Satellite Server
tags:
- name: Content Views
  description: >-
    Operations for managing content views that define curated snapshots
    of software repositories for controlled content delivery.
- name: Environments
  description: >-
    Operations for managing lifecycle environments that define the
    promotion path for content from development to production.
- name: Errata
  description: >-
    Operations for listing and managing errata (security advisories, bug
    fixes, and enhancements) applicable to registered hosts.
- name: Host Groups
  description: >-
    Operations for managing host groups that provide shared configuration
    templates for provisioning and management.
- name: Hosts
  description: >-
    Operations for managing hosts registered with Satellite, including
    provisioning, facts, and power management.
- name: Organizations
  description: >-
    Operations for managing organizations that provide multi-tenancy
    isolation for content and infrastructure resources.
- name: Repositories
  description: >-
    Operations for managing software repositories synced from Red Hat CDN
    or custom sources.
security:
- basicAuth: []
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
  /api/v2/hosts/{id}/errata:
    get:
      operationId: listHostErrata
      summary: Red Hat List Errata for a Host
      description: >-
        Retrieves the list of applicable errata for a specific host, including
        security advisories, bug fixes, and enhancements.
      tags:
      - Errata
      parameters:
      - $ref: '#/components/parameters/IdParam'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successfully retrieved host errata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedErrataList'
              examples:
                Listhosterrata200Example:
                  summary: Default listHostErrata 200 response
                  x-microcks-default: true
                  value:
                    total: 10
                    subtotal: 10
                    page: 10
                    per_page: 10
                    results:
                    - id: abc123
                      errata_id: '500123'
                      title: Example Title
                      type: security
                      severity: Critical
                      issued: '2026-01-15'
                      updated: '2026-01-15'
                      hosts_available_count: 10
                      hosts_applicable_count: 10
                      cves:
                      - {}
                      packages:
                      - {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /katello/api/v2/content_views:
    get:
      operationId: listContentViews
      summary: Red Hat List Content Views
      description: >-
        Retrieves the list of content views that define curated snapshots of
        software repositories used for controlled content delivery to hosts.
      tags:
      - Content Views
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - name: organization_id
        in: query
        description: Filter by organization identifier.
        schema:
          type: integer
        example: '500123'
      - name: name
        in: query
        description: Filter by content view name.
        schema:
          type: string
        example: Example Title
      responses:
        '200':
          description: Successfully retrieved content views
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedContentViewList'
              examples:
                Listcontentviews200Example:
                  summary: Default listContentViews 200 response
                  x-microcks-default: true
                  value:
                    total: 10
                    subtotal: 10
                    page: 10
                    per_page: 10
                    results:
                    - id: abc123
                      name: Example Title
                      label: Example Title
                      description: A sample description.
                      composite: true
                      organization_id: '500123'
                      repository_ids:
                      - {}
                      last_published: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createContentView
      summary: Red Hat Create a Content View
      description: >-
        Creates a new content view that can include selected repositories
        and filters for curating content delivery.
      tags:
      - Content Views
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - organization_id
              properties:
                name:
                  type: string
                  description: The name of the content view.
                description:
                  type: string
                  description: A description of the content view.
                organization_id:
                  type: integer
                  description: The organization to create the content view in.
                repository_ids:
                  type: array
                  description: IDs of repositories to include.
                  items:
                    type: integer
            examples:
              CreatecontentviewRequestExample:
                summary: Default createContentView request
                x-microcks-default: true
                value:
                  name: Example Title
                  description: A sample description.
                  organization_id: '500123'
                  repository_ids:
                  - 10
      responses:
        '201':
          description: Content view created successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /katello/api/v2/organizations/{organization_id}/environments:
    get:
      operationId: listEnvironments
      summary: Red Hat List Lifecycle Environments
      description: >-
        Retrieves the list of lifecycle environments for an organization,
        defining the promotion path for content views from development
        through to production.
      tags:
      - Environments
      parameters:
      - name: organization_id
        in: path
        required: true
        description: The organization identifier.
        schema:
          type: integer
        example: '500123'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successfully retrieved lifecycle environments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvironmentList'
              examples:
                Listenvironments200Example:
                  summary: Default listEnvironments 200 response
                  x-microcks-default: true
                  value:
                    total: 10
                    subtotal: 10
                    page: 10
                    per_page: 10
                    results:
                    - id: abc123
                      name: Example Title
                      label: Example Title
                      description: A sample description.
                      prior:
                        id: abc123
                        name: Example Title
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /katello/api/v2/repositories:
    get:
      operationId: listRepositories
      summary: Red Hat List Repositories
      description: >-
        Retrieves the list of repositories managed by Satellite, including
        those synced from Red Hat CDN and custom repositories.
      tags:
      - Repositories
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - name: organization_id
        in: query
        description: Filter by organization.
        schema:
          type: integer
        example: '500123'
      - name: content_type
        in: query
        description: Filter by content type.
        schema:
          type: string
          enum:
          - yum
          - deb
          - docker
          - file
          - ostree
        example: yum
      responses:
        '200':
          description: Successfully retrieved repositories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRepositoryList'
              examples:
                Listrepositories200Example:
                  summary: Default listRepositories 200 response
                  x-microcks-default: true
                  value:
                    total: 10
                    subtotal: 10
                    page: 10
                    per_page: 10
                    results:
                    - id: abc123
                      name: Example Title
                      label: Example Title
                      content_type: example_value
                      url: https://www.example.com
                      last_sync:
                        id: abc123
                        state: example_value
                        started_at: '2026-01-15T10:30:00Z'
                        ended_at: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/organizations:
    get:
      operationId: listOrganizations
      summary: Red Hat List Organizations
      description: >-
        Retrieves the list of organizations in Satellite that provide
        multi-tenancy isolation.
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/SearchParam'
      responses:
        '200':
          description: Successfully retrieved organizations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedOrganizationList'
              examples:
                Listorganizations200Example:
                  summary: Default listOrganizations 200 response
                  x-microcks-default: true
                  value:
                    total: 10
                    subtotal: 10
                    page: 10
                    per_page: 10
                    results:
                    - id: abc123
                      name: Example Title
                      label: Example Title
                      description: A sample description.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/hostgroups:
    get:
      operationId: listHostGroups
      summary: Red Hat List Host Groups
      description: >-
        Retrieves the list of host groups that provide shared configuration
        templates for host provisioning and management.
      tags:
      - Host Groups
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/SearchParam'
      responses:
        '200':
          description: Successfully retrieved host groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedHostGroupList'
              examples:
                Listhostgroups200Example:
                  summary: Default listHostGroups 200 response
                  x-microcks-default: true
                  value:
                    total: 10
                    subtotal: 10
                    page: 10
                    per_page: 10
                    results:
                    - id: abc123
                      name: Example Title
                      title: Example Title
                      description: A sample description.
                      environment_name: example_value
                      operatingsystem_name: example_value
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /katello/api/v2/errata:
    get:
      operationId: listErrata
      summary: Red Hat List Errata
      description: >-
        Retrieves a paginated list of available errata including security
        advisories, bug fixes, and enhancement updates.
      tags:
      - Errata
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - name: type
        in: query
        description: Filter errata by type.
        schema:
          type: string
          enum:
          - security
          - bugfix
          - enhancement
        example: security
      - name: severity
        in: query
        description: Filter security errata by severity.
        schema:
          type: string
          enum:
          - Critical
          - Important
          - Moderate
          - Low
        example: Critical
      responses:
        '200':
          description: Successfully retrieved errata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedErrataList'
              examples:
                Listerrata200Example:
                  summary: Default listErrata 200 response
                  x-microcks-default: true
                  value:
                    total: 10
                    subtotal: 10
                    page: 10
                    per_page: 10
                    results:
                    - id: abc123
                      errata_id: '500123'
                      title: Example Title
                      type: security
                      severity: Critical
                      issued: '2026-01-15'
                      updated: '2026-01-15'
                      hosts_available_count: 10
                      hosts_applicable_count: 10
                      cves:
                      - {}
                      packages:
                      - {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  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.
  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
    PerPageParam:
      name: per_page
      in: query
      description: The number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 20
    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
  responses:
    UnauthorizedError:
      description: Authentication credentials are missing or invalid.
    NotFoundError:
      description: The requested resource was not found.
  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: []
    PaginatedContentViewList:
      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:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              label:
                type: string
              description:
                type: string
              composite:
                type: boolean
              organization_id:
                type: integer
              repository_ids:
                type: array
                items:
                  type: integer
              last_published:
                type: string
                format: date-time
          example: []
    PaginatedEnvironmentList:
      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:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              label:
                type: string
              description:
                type: string
              prior:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
          example: []
    PaginatedRepositoryList:
      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:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              label:
                type: string
              content_type:
                type: string
              url:
                type: string
                format: uri
              last_sync:
                type: object
                properties:
                  id:
                    type: integer
                  state:
                    type: string
                  started_at:
                    type: string
                    format: date-time
                  ended_at:
                    type: string
                    format: date-time
          example: []
    PaginatedOrganizationList:
      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:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              label:
                type: string
              description:
                type: string
          example: []
    PaginatedHostGroupList:
      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:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              title:
                type: string
              description:
                type: string
              environment_name:
                type: string
              operatingsystem_name:
                type: string
          example: []
    PaginatedErrataList:
      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:
            type: object
            properties:
              id:
                type: integer
              errata_id:
                type: string
                description: The advisory identifier (e.g., RHSA-2024:1234).
              title:
                type: string
              type:
                type: string
                enum:
                - security
                - bugfix
                - enhancement
              severity:
                type: string
                enum:
                - Critical
                - Important
                - Moderate
                - Low
                - N/A
              issued:
                type: string
                format: date
              updated:


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