openapi: 3.1.0
info:
  title: Porter Bundle Bundles Runs API
  description: The Porter Bundle API provides programmatic access to managing Cloud Native Application Bundles (CNAB) using Porter. It supports listing and inspecting bundles, managing installations, handling credential sets and parameter sets, and querying installation runs and outputs. Porter implements the CNAB spec for packaging applications with their dependencies into distributable installers.
  version: 1.0.0
  contact:
    name: Porter Community
    url: https://porter.sh/community/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:3000
  description: Porter local server (porter server)
security:
- bearerAuth: []
tags:
- name: Runs
  description: Operations for querying the history of bundle action executions and their outputs.
paths:
  /v1/installations/{namespace}/{name}/runs:
    get:
      operationId: listInstallationRuns
      summary: Porter List runs for an installation
      description: Returns the history of all bundle action executions for a specific installation, ordered from most recent to oldest. Each run captures the action performed, the result, and timing information.
      tags:
      - Runs
      parameters:
      - $ref: '#/components/parameters/namespace_path'
      - $ref: '#/components/parameters/name_path'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunListResponse'
        '401':
          description: Unauthorized
        '404':
          description: Installation not found
  /v1/installations/{namespace}/{name}/runs/{run_id}:
    get:
      operationId: getInstallationRun
      summary: Porter Get a specific run
      description: Returns details of a single bundle action execution including the bundle action performed, parameters and credentials used, result status, and any outputs produced.
      tags:
      - Runs
      parameters:
      - $ref: '#/components/parameters/namespace_path'
      - $ref: '#/components/parameters/name_path'
      - $ref: '#/components/parameters/run_id'
      responses:
        '200':
          description: Run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '401':
          description: Unauthorized
        '404':
          description: Run not found
  /v1/installations/{namespace}/{name}/runs/{run_id}/outputs:
    get:
      operationId: listRunOutputs
      summary: Porter List outputs for a run
      description: Returns all outputs produced during a specific bundle action execution. Outputs are values defined in the bundle that are written during an action and can be referenced by dependent bundles or inspected by users.
      tags:
      - Runs
      parameters:
      - $ref: '#/components/parameters/namespace_path'
      - $ref: '#/components/parameters/name_path'
      - $ref: '#/components/parameters/run_id'
      responses:
        '200':
          description: List of outputs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutputListResponse'
        '401':
          description: Unauthorized
        '404':
          description: Run not found
components:
  schemas:
    Run:
      type: object
      description: A record of a single bundle action execution for an installation, capturing the action taken, parameters and credentials used, result, and timing.
      properties:
        id:
          type: string
          description: Unique identifier for this run.
        installation:
          type: string
          description: Name of the installation this run belongs to.
        namespace:
          type: string
          description: Porter namespace of the installation.
        bundle:
          type: string
          description: OCI reference to the bundle used in this run.
        action:
          type: string
          description: Bundle action executed in this run.
          enum:
          - install
          - upgrade
          - invoke
          - uninstall
        parameters:
          type: object
          description: Parameter values used during this run.
          additionalProperties: {}
        credentialSets:
          type: array
          description: Credential sets used during this run.
          items:
            type: string
        parameterSets:
          type: array
          description: Parameter sets used during this run.
          items:
            type: string
        result:
          type: string
          description: Outcome of the run.
          enum:
          - succeeded
          - failed
          - running
          - pending
          - cancelled
        startedAt:
          type: string
          format: date-time
          description: When the run started.
        completedAt:
          type: string
          format: date-time
          description: When the run completed.
    Output:
      type: object
      description: A named output value produced by a bundle action execution.
      properties:
        name:
          type: string
          description: Name of the output as defined in the bundle.
        type:
          type: string
          description: JSON Schema type of the output value.
        sensitive:
          type: boolean
          description: Whether the output contains sensitive data.
        value:
          description: The output value. Absent for sensitive outputs.
        runID:
          type: string
          description: ID of the run that produced this output.
    RunListResponse:
      type: object
      description: Paginated list of runs.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Run'
        total:
          type: integer
    OutputListResponse:
      type: object
      description: List of outputs from a bundle run.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Output'
  parameters:
    name_path:
      name: name
      in: path
      required: true
      description: Name of the resource.
      schema:
        type: string
    namespace_path:
      name: namespace
      in: path
      required: true
      description: Porter namespace of the resource.
      schema:
        type: string
    run_id:
      name: run_id
      in: path
      required: true
      description: Unique identifier of the run.
      schema:
        type: string
    skip:
      name: skip
      in: query
      required: false
      description: Number of records to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token for authenticating to the Porter server API.
externalDocs:
  description: Porter Documentation
  url: https://porter.sh/docs/