openapi: 3.1.0
info:
  title: Red Hat Satellite REST Content Views Lifecycle Environments 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: Lifecycle Environments
  description: Manage lifecycle environments that define promotion paths for content views from development through production.
  externalDocs:
    url: https://apidocs.theforeman.org/katello/latest/apidoc/v2/lifecycle_environments.html
paths:
  /katello/api/v2/organizations/{organization_id}/environments:
    get:
      operationId: listLifecycleEnvironments
      summary: List Lifecycle Environments
      description: Retrieve a list of lifecycle environments for an organization. Lifecycle environments define the content promotion path from Library through development, testing, and production stages.
      tags:
      - Lifecycle Environments
      parameters:
      - name: organization_id
        in: path
        required: true
        description: Organization identifier.
        schema:
          type: integer
        example: '500123'
      - name: library
        in: query
        description: Include the Library lifecycle environment.
        schema:
          type: boolean
        example: true
      - name: name
        in: query
        description: Filter by lifecycle environment name.
        schema:
          type: string
        example: Example Title
      - name: label
        in: query
        description: Filter by lifecycle environment label.
        schema:
          type: string
        example: Example Title
      - $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 lifecycle environments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  subtotal:
                    type: integer
                  page:
                    type: integer
                  per_page:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/LifecycleEnvironment'
              examples:
                Listlifecycleenvironments200Example:
                  summary: Default listLifecycleEnvironments 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.
                      organization_id: '500123'
                      organization:
                        name: Example Title
                        label: Example Title
                        id: abc123
                      library: true
                      prior:
                        id: abc123
                        name: Example Title
                      successor: example_value
                      counts:
                        content_hosts: 10
                        content_views: 10
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createLifecycleEnvironment
      summary: Create a Lifecycle Environment
      description: Create a new lifecycle environment within an organization's content promotion path.
      tags:
      - Lifecycle Environments
      parameters:
      - name: organization_id
        in: path
        required: true
        description: Organization identifier.
        schema:
          type: integer
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - prior_id
              properties:
                name:
                  type: string
                  description: Name of the lifecycle environment.
                label:
                  type: string
                  description: Label for the lifecycle environment (auto-generated from name if omitted).
                description:
                  type: string
                  description: Description of the lifecycle environment.
                prior_id:
                  type: integer
                  description: Identifier of the prior lifecycle environment in the promotion path.
            examples:
              CreatelifecycleenvironmentRequestExample:
                summary: Default createLifecycleEnvironment request
                x-microcks-default: true
                value:
                  name: Example Title
                  label: Example Title
                  description: A sample description.
                  prior_id: '500123'
      responses:
        '201':
          description: Lifecycle environment created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LifecycleEnvironment'
              examples:
                Createlifecycleenvironment201Example:
                  summary: Default createLifecycleEnvironment 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    label: Example Title
                    description: A sample description.
                    organization_id: '500123'
                    organization:
                      name: Example Title
                      label: Example Title
                      id: abc123
                    library: true
                    prior:
                      id: abc123
                      name: Example Title
                    successor: example_value
                    counts:
                      content_hosts: 10
                      content_views: 10
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /katello/api/v2/organizations/{organization_id}/environments/paths:
    get:
      operationId: listLifecycleEnvironmentPaths
      summary: List Lifecycle Environment Paths
      description: Retrieve the lifecycle environment promotion paths for an organization, showing the sequence of environments content views are promoted through.
      tags:
      - Lifecycle Environments
      parameters:
      - name: organization_id
        in: path
        required: true
        description: Organization identifier.
        schema:
          type: integer
        example: '500123'
      responses:
        '200':
          description: Successful response containing lifecycle environment paths.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    environments:
                      type: array
                      items:
                        $ref: '#/components/schemas/LifecycleEnvironment'
              examples:
                Listlifecycleenvironmentpaths200Example:
                  summary: Default listLifecycleEnvironmentPaths 200 response
                  x-microcks-default: true
                  value:
                  - environments:
                    - id: abc123
                      name: Example Title
                      label: Example Title
                      description: A sample description.
                      organization_id: '500123'
                      organization: {}
                      library: true
                      prior: {}
                      successor: example_value
                      counts: {}
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    pageQuery:
      name: page
      in: query
      description: Page number for paginated results (starting at 1).
      schema:
        type: integer
        minimum: 1
        default: 1
    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
    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
    orderQuery:
      name: order
      in: query
      description: Sort field and direction (e.g., "name ASC" or "id DESC").
      schema:
        type: string
  schemas:
    LifecycleEnvironment:
      type: object
      description: A lifecycle environment defining a stage in the content promotion path.
      properties:
        id:
          type: integer
          description: Unique identifier for the lifecycle environment.
          example: abc123
        name:
          type: string
          description: Name of the lifecycle environment.
          example: Example Title
        label:
          type: string
          description: Unique label for the lifecycle environment.
          example: Example Title
        description:
          type:
          - string
          - 'null'
          description: Description of the lifecycle environment.
          example: A sample description.
        organization_id:
          type: integer
          description: Organization this environment belongs to.
          example: '500123'
        organization:
          type: object
          properties:
            name:
              type: string
            label:
              type: string
            id:
              type: integer
          example: example_value
        library:
          type: boolean
          description: Whether this is the Library environment.
          example: true
        prior:
          type: object
          description: Prior environment in the promotion path.
          properties:
            id:
              type: integer
            name:
              type: string
          example: example_value
        successor:
          type:
          - object
          - 'null'
          description: Successor environment in the promotion path.
          properties:
            id:
              type: integer
            name:
              type: string
          example: example_value
        counts:
          type: object
          description: Content counts for this environment.
          properties:
            content_hosts:
              type: integer
            content_views:
              type: integer
          example: example_value
        created_at:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
  responses:
    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.
    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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using Satellite username and password.
    oAuth2:
      type: oauth2
      description: OAuth 2.0 Personal Access Token authentication for Satellite users.
      flows:
        implicit:
          authorizationUrl: https://satellite.example.com/users/extlogin
          scopes: {}
externalDocs:
  description: Red Hat Satellite API Documentation
  url: https://docs.redhat.com/en/documentation/red_hat_satellite/6.18/html/using_the_satellite_rest_api/index