openapi: 3.1.0
info:
  title: Porter Bundle Bundles CredentialSets 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: CredentialSets
  description: Operations for managing credential sets that supply secret values to bundle executions.
paths:
  /v1/credentialsets:
    get:
      operationId: listCredentialSets
      summary: Porter List credential sets
      description: Returns all credential sets managed by Porter. A credential set maps bundle credential names to their sources, such as environment variables, files, or secret store references.
      tags:
      - CredentialSets
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of credential sets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialSetListResponse'
        '401':
          description: Unauthorized
    post:
      operationId: createCredentialSet
      summary: Porter Create a credential set
      description: Creates a new credential set defining how bundle credential names are resolved at execution time from sources such as environment variables, files, or secret store integrations.
      tags:
      - CredentialSets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialSet'
      responses:
        '201':
          description: Credential set created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialSet'
        '400':
          description: Invalid credential set specification
        '401':
          description: Unauthorized
        '409':
          description: Credential set already exists
  /v1/credentialsets/{namespace}/{name}:
    get:
      operationId: getCredentialSet
      summary: Porter Get a credential set
      description: Returns the specified credential set including its credential mappings. Secret values are never included in responses.
      tags:
      - CredentialSets
      parameters:
      - $ref: '#/components/parameters/namespace_path'
      - $ref: '#/components/parameters/name_path'
      responses:
        '200':
          description: Credential set details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialSet'
        '401':
          description: Unauthorized
        '404':
          description: Credential set not found
    put:
      operationId: updateCredentialSet
      summary: Porter Update a credential set
      description: Replaces the credential mappings in a credential set with the provided definition.
      tags:
      - CredentialSets
      parameters:
      - $ref: '#/components/parameters/namespace_path'
      - $ref: '#/components/parameters/name_path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialSet'
      responses:
        '200':
          description: Credential set updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialSet'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '404':
          description: Credential set not found
    delete:
      operationId: deleteCredentialSet
      summary: Porter Delete a credential set
      description: Deletes the specified credential set. Installations referencing this credential set will fail if they are re-run.
      tags:
      - CredentialSets
      parameters:
      - $ref: '#/components/parameters/namespace_path'
      - $ref: '#/components/parameters/name_path'
      responses:
        '204':
          description: Credential set deleted
        '401':
          description: Unauthorized
        '404':
          description: Credential set not found
components:
  schemas:
    CredentialSet:
      type: object
      description: A named collection of credential mappings that resolve bundle credential names to their runtime sources such as environment variables, files, or secret store entries.
      required:
      - name
      - credentials
      properties:
        name:
          type: string
          description: Name of the credential set.
        namespace:
          type: string
          description: Porter namespace this credential set belongs to.
        credentials:
          type: array
          description: List of credential mappings.
          items:
            $ref: '#/components/schemas/CredentialMapping'
        labels:
          type: object
          additionalProperties:
            type: string
          description: Labels for categorizing the credential set.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the credential set was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the credential set was last updated.
    CredentialSetListResponse:
      type: object
      description: Paginated list of credential sets.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CredentialSet'
        total:
          type: integer
    CredentialMapping:
      type: object
      description: Maps a bundle credential name to its runtime source.
      required:
      - name
      - source
      properties:
        name:
          type: string
          description: Name of the bundle credential this mapping applies to.
        source:
          $ref: '#/components/schemas/ValueSource'
    ValueSource:
      type: object
      description: Defines where a credential or parameter value is sourced from at execution time. Exactly one of the source fields should be set.
      properties:
        env:
          type: string
          description: Name of an environment variable providing the value.
        path:
          type: string
          description: Absolute path to a file providing the value.
        value:
          type: string
          description: A literal string value.
        secret:
          type: string
          description: Reference to a secret in the configured secret store plugin, such as a secret name in HashiCorp Vault or Azure Key Vault.
        command:
          type: string
          description: Shell command whose stdout provides the value.
  parameters:
    name_path:
      name: name
      in: path
      required: true
      description: Name of the resource.
      schema:
        type: string
    name:
      name: name
      in: query
      required: false
      description: Filter results by resource name.
      schema:
        type: string
    namespace_path:
      name: namespace
      in: path
      required: true
      description: Porter namespace of the resource.
      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
    namespace:
      name: namespace
      in: query
      required: false
      description: Porter namespace to scope the query to. Defaults to the current namespace configured in Porter's context.
      schema:
        type: string
  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/