Replicated channelReleases API

swagger: '2.0'
info:
  description: Manage enterprise portal users, install options, branding, documentation, email templates, and access control.
  title: Vendor API V3 apps channelReleases API
  contact:
    name: Replicated, Inc.
    url: http://www.replicated.com/
    email: info@replicated.com
  version: 3.0.0
host: api.replicated.com
basePath: /vendor/v3
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: channelReleases
paths:
  /app/{app_id}/channel/{channel_id}/airgap/download-url:
    get:
      security:
      - api_key: []
      description: 'Returns a download URL for the airgap bundle associated with the active release on the specified channel. Optionally, a specific channel sequence can be requested via query parameter.


        Required RBAC Policy: kots/app/[:appid]/channel/[:channelid]/releases/airgap/download-url'
      produces:
      - application/json
      schemes:
      - https
      tags:
      - channelReleases
      summary: Get airgap bundle download URL the active release on the channel.
      operationId: channelReleaseAirgapBundleURL
      parameters:
      - type: string
        x-go-name: AppID
        description: App identifier
        name: app_id
        in: path
        required: true
      - type: string
        x-go-name: ChannelID
        description: Channel identifier
        name: channel_id
        in: path
        required: true
      - type: integer
        format: int64
        x-go-name: ChannelSequence
        description: If provided, the airgap bundle download URL for the given channel sequence will be returned
        name: channelSequence
        in: query
      responses:
        '200':
          $ref: '#/responses/channelReleaseAirgapBundleURLResponse'
        '400':
          $ref: '#/responses/responseErrBadRequest'
        '401':
          $ref: '#/responses/responseErrUnauthorized'
        '403':
          $ref: '#/responses/responseErrForbidden'
        '404':
          $ref: '#/responses/responseErrNotFound'
  /app/{app_id}/channel/{channel_id}/release/{sequence}/airgap/build:
    post:
      security:
      - api_key: []
      description: 'Triggers a build of an airgap bundle for the specified release in a channel. The airgap bundle can be used for offline installations.


        Required RBAC Policy: kots/app/[:appid]/channel/[:channelid]/releases/airgap'
      produces:
      - application/json
      schemes:
      - https
      tags:
      - channelReleases
      summary: Trigger airgap build for a channel's release.
      operationId: channelReleaseAirgapBuild
      parameters:
      - type: string
        x-go-name: AppID
        description: App identifier
        name: app_id
        in: path
        required: true
      - type: string
        x-go-name: ChannelID
        description: Channel identifier
        name: channel_id
        in: path
        required: true
      - type: integer
        format: int64
        x-go-name: Sequence
        description: Release identifier
        name: sequence
        in: path
        required: true
      responses:
        '200':
          $ref: '#/responses/channelReleaseAirgapBuildResponse'
        '400':
          $ref: '#/responses/responseErrBadRequest'
        '401':
          $ref: '#/responses/responseErrUnauthorized'
        '403':
          $ref: '#/responses/responseErrForbidden'
        '404':
          $ref: '#/responses/responseErrNotFound'
  /app/{app_id}/channel/{channel_id}/release/{sequence}/airgap/cancel:
    post:
      security:
      - api_key: []
      description: 'Cancels an in-progress airgap build for the specified release in a channel.


        Required RBAC Policy: kots/app/[:appid]/channel/[:channelid]/releases/airgap'
      produces:
      - application/json
      schemes:
      - https
      tags:
      - channelReleases
      summary: Cancel airgap build for a channel's release.
      operationId: channelReleaseAirgapCancel
      parameters:
      - type: string
        x-go-name: AppID
        description: App identifier
        name: app_id
        in: path
        required: true
      - type: string
        x-go-name: ChannelID
        description: Channel identifier
        name: channel_id
        in: path
        required: true
      - type: integer
        format: int64
        x-go-name: Sequence
        description: Release identifier
        name: sequence
        in: path
        required: true
      responses:
        '200':
          $ref: '#/responses/channelReleaseAirgapCancelResponse'
        '400':
          $ref: '#/responses/responseErrBadRequest'
        '401':
          $ref: '#/responses/responseErrUnauthorized'
        '403':
          $ref: '#/responses/responseErrForbidden'
        '404':
          $ref: '#/responses/responseErrNotFound'
  /app/{app_id}/channel/{channel_id}/release/{sequence}/airgap/status:
    get:
      security:
      - api_key: []
      description: 'Returns the current airgap build status for the specified release in a channel.


        Required RBAC Policy: kots/app/[:appid]/channel/[:channelid]/releases/airgap/status/read'
      produces:
      - application/json
      schemes:
      - https
      tags:
      - channelReleases
      summary: Get airgap build status for a channel's release.
      operationId: channelReleaseAirgapStatus
      parameters:
      - type: string
        x-go-name: AppID
        description: App identifier
        name: app_id
        in: path
        required: true
      - type: string
        x-go-name: ChannelID
        description: Channel identifier
        name: channel_id
        in: path
        required: true
      - type: integer
        format: int64
        x-go-name: Sequence
        description: Release identifier
        name: sequence
        in: path
        required: true
      responses:
        '200':
          $ref: '#/responses/channelReleaseAirgapStatusResponse'
        '400':
          $ref: '#/responses/responseErrBadRequest'
        '401':
          $ref: '#/responses/responseErrUnauthorized'
        '403':
          $ref: '#/responses/responseErrForbidden'
        '404':
          $ref: '#/responses/responseErrNotFound'
  /app/{app_id}/channel/{channel_id}/release/{sequence}/install-commands:
    get:
      security:
      - api_key: []
      description: 'Return the install commands for a specific release in a channel, including commands for embedded and existing clusters.


        Required RBAC Policy: kots/app/[:appid]/channel/[:channelid]/releases/read'
      produces:
      - application/json
      schemes:
      - https
      tags:
      - channelReleases
      summary: Get install commands for a specific channel release.
      operationId: getChannelReleaseInstallCommands
      parameters:
      - type: string
        x-go-name: AppID
        description: App identifier
        name: app_id
        in: path
        required: true
      - type: string
        x-go-name: ChannelID
        description: Channel identifier
        name: channel_id
        in: path
        required: true
      - type: integer
        format: int64
        x-go-name: Sequence
        description: Release identifier
        name: sequence
        in: path
        required: true
      responses:
        '200':
          $ref: '#/responses/getChannelReleaseInstallCommandsResponse'
        '400':
          $ref: '#/responses/responseErrBadRequest'
        '401':
          $ref: '#/responses/responseErrUnauthorized'
        '403':
          $ref: '#/responses/responseErrForbidden'
        '404':
          $ref: '#/responses/responseErrNotFound'
  /app/{app_id}/channel/{channel_id}/release/{sequence}/update-properties:
    post:
      security:
      - api_key: []
      description: 'Updates the properties (such as version label, release notes, and required status) for a specific release in a channel.


        Required RBAC Policy: kots/app/[:appid]/channel/[:channelid]/releases/update'
      consumes:
      - application/json
      produces:
      - application/json
      schemes:
      - https
      tags:
      - channelReleases
      summary: Update properties for a channel release.
      operationId: updateChannelRelease
      parameters:
      - type: string
        x-go-name: AppID
        description: App identifier
        name: app_id
        in: path
        required: true
      - type: string
        x-go-name: ChannelID
        description: Channel identifier
        name: channel_id
        in: path
        required: true
      - type: integer
        format: int64
        x-go-name: Sequence
        description: Release identifier
        name: sequence
        in: path
        required: true
      - description: Update release parameters.
        name: Body
        in: body
        schema:
          type: object
          properties:
            isRequired:
              description: Prevent this release from being skipped during upgrades
              type: boolean
              x-go-name: IsRequired
            releaseNotes:
              description: The updated release notes
              type: string
              x-go-name: ReleaseNotes
            versionLabel:
              description: The new version label to use
              type: string
              x-go-name: VersionLabel
      responses:
        '200':
          $ref: '#/responses/updateChannelRelease'
        '400':
          $ref: '#/responses/responseErrBadRequest'
        '401':
          $ref: '#/responses/responseErrUnauthorized'
        '403':
          $ref: '#/responses/responseErrForbidden'
        '404':
          $ref: '#/responses/responseErrNotFound'
  /app/{app_id}/channel/{channel_id}/releases:
    get:
      security:
      - api_key: []
      description: 'Return a paginated list of releases for a specific channel within an app, including release metadata and status.


        Required RBAC Policy: kots/app/[:appid]/channel/[:channelid]/releases/read'
      produces:
      - application/json
      schemes:
      - https
      tags:
      - channelReleases
      summary: List releases for an app channel.
      operationId: listChannelReleases
      parameters:
      - type: string
        x-go-name: AppID
        description: App identifier
        name: app_id
        in: path
        required: true
      - type: string
        x-go-name: ChannelID
        description: Channel identifier
        name: channel_id
        in: path
        required: true
      - type: integer
        format: int64
        default: 20
        x-go-name: PageSize
        description: Page size
        name: pageSize
        in: query
      - type: integer
        format: int64
        x-go-name: CurrentPage
        description: Current page
        name: currentPage
        in: query
      - type: boolean
        x-go-name: ExcludeDemoted
        description: Exclude demoted releases
        name: excludeDemoted
        in: query
      - type: boolean
        x-go-name: IncludeSecuritySummary
        description: Include security summary
        name: includeSecuritySummary
        in: query
      - type: string
        x-go-name: VersionLabel
        description: Filter by version label (partial match)
        name: versionLabel
        in: query
      - enum:
        - online
        - airgap
        type: string
        x-go-name: IncludeInstallerImages
        description: Include EC installer images in the images list. Empty = app images only (default).
        name: includeInstallerImages
        in: query
      responses:
        '200':
          $ref: '#/responses/listChannelReleasesResponse'
        '400':
          $ref: '#/responses/responseErrBadRequest'
        '401':
          $ref: '#/responses/responseErrUnauthorized'
        '403':
          $ref: '#/responses/responseErrForbidden'
        '404':
          $ref: '#/responses/responseErrNotFound'
definitions:
  InstallationTypeKurl:
    type: object
    properties:
      installerVersion:
        type: string
        x-go-name: InstallerVersion
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  InstallerTypeEmbeddedCluster:
    type: object
    properties:
      proxyRegistryDomain:
        type: string
        x-go-name: ProxyRegistryDomain
      replicatedAppDomain:
        type: string
        x-go-name: ReplicatedAppDomain
      replicatedRegistryDomain:
        type: string
        x-go-name: ReplicatedRegistryDomain
      version:
        type: string
        x-go-name: InstallerVersion
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  AirgapBuildSummary:
    type: object
    title: AirgapBuildSummary is a lightweight snapshot of a channel-release's airgap build state.
    properties:
      airgapBuildError:
        type: string
        x-go-name: AirgapBuildError
      airgapBuildStatus:
        type: string
        x-go-name: AirgapBuildStatus
      channelId:
        type: string
        x-go-name: ChannelID
      channelName:
        type: string
        x-go-name: ChannelName
      channelSequence:
        type: integer
        format: int64
        x-go-name: ChannelSequence
      fullAirgapBuild:
        description: 'FullAirgapBuild is true when the channel-release is configured to produce

          or has completed with a full airgap bundle.

          When false, the worker may still run metadata generation for the

          channel-release and that step can fail.'
        type: boolean
        x-go-name: FullAirgapBuild
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/release
  ImageVulnCounts:
    type: object
    properties:
      counts:
        $ref: '#/definitions/VulnCounts'
      digest:
        type: string
        x-go-name: Digest
      digest_first_seen_at:
        type: string
        x-go-name: DigestFirstSeenAt
      image_size_bytes:
        type: integer
        format: int64
        x-go-name: ImageSizeBytes
      input:
        type: string
        x-go-name: Input
      installation_phase:
        description: 'InstallationPhase indicates the Embedded Cluster phase for the image ("", "online", or "airgap").

          Application images have the phase "".

          Infrastructure images used for Embedded Cluster in both online and airgap have the phase "online" or "airgap".

          Infrastructure images used for Embedded Cluster only in airgap have the phase "airgap".'
        type: string
        x-go-name: InstallationPhase
      last_scanned_at:
        type: string
        x-go-name: LastScannedAt
      not_found:
        type: boolean
        x-go-name: NotFound
      sbom_status:
        description: SBOM status tracking
        type: string
        x-go-name: SBOMStatus
      sbom_status_message:
        type: string
        x-go-name: SBOMStatusMessage
      sbom_status_updated_at:
        type: string
        x-go-name: SBOMStatusUpdatedAt
      scan_status:
        description: Scan status tracking
        type: string
        x-go-name: ScanStatus
      scan_status_message:
        type: string
        x-go-name: ScanStatusMessage
      scan_status_updated_at:
        type: string
        x-go-name: ScanStatusUpdatedAt
      scanned_images:
        description: Scan completeness tracking
        type: integer
        format: int64
        x-go-name: ScannedImages
      total_images:
        type: integer
        format: int64
        x-go-name: TotalImages
    x-go-package: github.com/replicatedhq/vandoor/pkg/securebuild/types
  InstallerTypeKotsConfig:
    type: object
    properties:
      apiVersion:
        type: string
        x-go-name: APIVersion
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  LintResult:
    type: object
    properties:
      isLintingComplete:
        type: boolean
        x-go-name: IsLintingComplete
      lintExpressions:
        type: array
        items:
          $ref: '#/definitions/LintExpression'
        x-go-name: LintExpressions
    x-go-package: github.com/replicatedhq/vandoor/pkg/lint
  InstallerTypeHelm:
    type: object
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  InstallerTypeReplicatedSDK:
    type: object
    properties:
      sdkVersion:
        type: string
        x-go-name: SDKVersion
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  InstallerTypePreflight:
    type: object
    properties:
      apiVersion:
        type: string
        x-go-name: APIVersion
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  HelmInstallabilityIssue:
    type: object
    properties:
      message:
        type: string
        x-go-name: Message
      resources:
        type: array
        items:
          $ref: '#/definitions/HelmUnavailableResource'
        x-go-name: Resources
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  KotsChannelRelease:
    type: object
    properties:
      airgapBuildError:
        type: string
        x-go-name: AirgapBuildError
      airgapBuildStatus:
        type: string
        x-go-name: AirgapBuildStatus
      airgapBundleImages:
        type: array
        items:
          type: string
        x-go-name: AirgapBundleImages
      channelIcon:
        type: string
        x-go-name: ChannelIcon
      channelId:
        type: string
        x-go-name: ChannelID
      channelName:
        type: string
        x-go-name: ChannelName
      channelSequence:
        type: integer
        format: int64
        x-go-name: ChannelSequence
      created:
        type: string
        format: date-time
        x-go-name: Created
      createdBy:
        $ref: '#/definitions/Actor'
      customResourceError:
        type: string
        x-go-name: CustomResourceError
      customResourceWarnings:
        type: array
        items:
          type: string
        x-go-name: CustomResourceWarnings
      demotedAt:
        type: string
        format: date-time
        x-go-name: DemotedAt
      embeddedClusterVersion:
        type: string
        x-go-name: EmbeddedClusterVersion
      hasECInstaller:
        type: boolean
        x-go-name: HasECInstaller
      hasKurlInstaller:
        type: boolean
        x-go-name: HasKurlInstaller
      imageSecurityInfo:
        type: array
        items:
          $ref: '#/definitions/ImageVulnCounts'
        x-go-name: ImageSecurityInfo
      imageSecuritySums:
        type: object
        additionalProperties:
          $ref: '#/definitions/ImageVulnCounts'
        x-go-name: ImageSecuritySums
      installationTypes:
        $ref: '#/definitions/InstallationTypes'
      isDemoted:
        type: boolean
        x-go-name: IsDemoted
      isRequired:
        type: boolean
        x-go-name: IsRequired
      kurlInstallerID:
        type: string
        x-go-name: KurlInstallerID
      lintResult:
        $ref: '#/definitions/LintResult'
      proxyRegistryDomain:
        type: string
        x-go-name: ProxyRegistryDomain
      registrySecret:
        type: string
        x-go-name: RegistrySecret
      releaseNotes:
        type: string
        x-go-name: ReleaseNotes
      releasedAt:
        type: string
        format: date-time
        x-go-name: ReleasedAt
      replicatedRegistryDomain:
        type: string
        x-go-name: ReplicatedRegistryDomain
      semver:
        type: string
        x-go-name: Semver
      sequence:
        type: integer
        format: int64
        x-go-name: Sequence
      updated:
        type: string
        format: date-time
        x-go-name: Updated
      updatedBy:
        $ref: '#/definitions/Actor'
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  InstallationTypes:
    type: object
    properties:
      embeddedCluster:
        $ref: '#/definitions/InstallerTypeEmbeddedCluster'
      helm:
        $ref: '#/definitions/InstallerTypeHelm'
      helmInstallabilityIssue:
        $ref: '#/definitions/HelmInstallabilityIssue'
      kots:
        $ref: '#/definitions/InstallerTypeKots'
      kotsConfig:
        $ref: '#/definitions/InstallerTypeKotsConfig'
      kurl:
        $ref: '#/definitions/InstallationTypeKurl'
      preflight:
        $ref: '#/definitions/InstallerTypePreflight'
      replicatedSDK:
        $ref: '#/definitions/InstallerTypeReplicatedSDK'
      supportBundle:
        $ref: '#/definitions/InstallerTypeSupportBundle'
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  VulnCounts:
    type: object
    properties:
      critical:
        type: integer
        format: int64
        x-go-name: Critical
      high:
        type: integer
        format: int64
        x-go-name: High
      low:
        type: integer
        format: int64
        x-go-name: Low
      medium:
        type: integer
        format: int64
        x-go-name: Medium
      total:
        type: integer
        format: int64
        x-go-name: Total
    x-go-package: github.com/replicatedhq/vandoor/pkg/securebuild/types
  Actor:
    type: object
    properties:
      description:
        type: string
        x-go-name: Description
      id:
        type: string
        x-go-name: ID
      link:
        type: string
        x-go-name: Link
      timestamp:
        type: string
        format: date-time
        x-go-name: Timestamp
      type:
        type: string
        x-go-name: Type
    x-go-package: github.com/replicatedhq/vandoor/pkg/models/types
  ChannelReleaseInstallCommands:
    type: object
    properties:
      embeddedClusterInstallCommand:
        type: string
        x-go-name: EmbeddedClusterInstallCommand
      existingClusterInstallCommand:
        type: string
        x-go-name: ExistingClusterInstallCommand
    x-go-package: github.com/replicatedhq/vandoor/handlers/vendor-api/replv3/releases
  InstallerTypeKots:
    type: object
    properties:
      minKotsVersion:
        type: string
        x-go-name: MinKotsVersion
      targetKotsVersion:
        type: string
        x-go-name: TargetKotsVersion
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  HelmUnavailableResource:
    type: object
    properties:
      filePath:
        type: string
        x-go-name: FilePath
      identifier:
        type: string
        x-go-name: Identifier
      kind:
        type: string
        x-go-name: Kind
      name:
        type: string
        x-go-name: Name
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  InstallerTypeSupportBundle:
    type: object
    properties:
      apiVersion:
        type: string
        x-go-name: APIVersion
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/channel/types
  LintExpression:
    type: object
    properties:
      message:
        type: string
        x-go-name: Message
      path:
        type: string
        x-go-name: Path
      rule:
        type: string
        x-go-name: Rule
      type:
        type: string
        x-go-name: Type
    x-go-package: github.com/replicatedhq/vandoor/pkg/kots/release
responses:
  channelReleaseAirgapBuildResponse:
    description: ChannelReleaseAirgapBuildResponse contains empty JSON object
    schema:
      type: object
  listChannelReleasesResponse:
    description: ListChannelReleasesResponse contains the JSON channel releases list
    schema:
      type: object
      properties:
        matchedCount:
          type: integer
          format: int64
          x-go-name: MatchedCount
        releases:
          type: array
          items:
            $ref: '#/definitions/KotsChannelRelease'
          x-go-name: Releases
  channelReleaseAirgapCancelResponse:
    description: ChannelReleaseAirgapCancelResponse contains empty JSON object
    schema:
      type: object
  updateChannelRelease:
    description: UpdateChannelReleaseResponse contains the release properties
    schema:
      type: object
      properties:
        release:
          $ref: '#/definitions/KotsChannelRelease'
  responseErrUnauthorized:
    description: Return if the caller is not authorized
    schema:
      type: object
      properties:
        message:
          type: string
          x-go-name: Message
  responseErrBadRequest:
    description: Returned on bad input
    schema:
      type: object
      properties:
        error_code:
          description: Error code if available
          type: string
          x-go-name: ErrorCode
        message:
          description: Error message text if available
          type: string
          x-go-name: Message
  responseErrForbidden:
    description: Returned if the caller does not have the needed permission
    schema:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              x-go-name: Message
            messageCode:
              type: string
              x-go-name: MessageCode
          x-go-name: Error
  channelReleaseAirgapBundleURLResponse:
    description: ChannelReleaseAirgapBundleURLResponse contains the airgap bundle download URL
    schema:
      type: object
      properties:
        url:
          type: string
          x-go-name: URL
  getChannelReleaseInstallCommandsResponse:
    description: GetChannelReleaseInstallCommandsResponse contains the JSON channel release install commands
    schema:
      type: object
      properties:
        commands:
          $ref: '#/definitions/ChannelReleaseInstallCommands'
  channelReleaseAirgapStatusResponse:
    description: ChannelReleaseAirgapStatusResponse contains the airgap build status
    schema:
      $ref: '#/definitions/AirgapBuildSummary'
  responseErrNotFound:
    description: Returned on resource not found
    schema:
      type: object
      properties:
        message:
          type: string
          x-go-name: Message
securityDefinitions:
  api_key:
    type: apiKey
    name: Authorization
    in: header