autorag.yaml

openapi: 3.0.3
info:
  title: AutoRAG REST API
  version: 1.0.0
  description: REST API AutoRAG BFF
  license:
    name: Apache 2.0
    url: "https://www.apache.org/licenses/LICENSE-2.0"
servers:
  - url: "https://localhost:8080"
  - url: "http://localhost:8080"
paths:
  /healthcheck:
    summary: Path targeted for healthcheck purposes.
    description: >-
      The REST endpoint/path used to allow a healthcheck update.
    get:
      tags:
        - K8SOperation
      responses:
        "200":
          description: "Ok"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: healthcheck
      summary: HealthCheck
      description: HealthCheck endpoint.
  /api/v1/namespaces:
    summary: Path used to get available namespaces.
    description: >-
      The REST endpoint/path used to list available namespaces.
    get:
      tags:
        - K8SOperation
      responses:
        "200":
          description: "Ok"
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    description: Metadata about the response
                  data:
                    type: object
                    properties:
                      name:
                        type: string
                        example: default-namespace
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: getNamespaces
      summary: Get Available Namespaces
      description: Returns available namespaces in the cluster.
  /api/v1/user:
    summary: Path used to Retrieve a user based on the header.
    description: >-
      The REST endpoint/path used pass all the config information needed for the UI.
    get:
      tags:
        - K8SOperation
      parameters:
        - $ref: "#/components/parameters/kubeflowUserId"
      responses:
        "200":
          $ref: "#/components/responses/ConfigResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: getConfig
      summary: Get configuration info
      description: Gets the configuration information needed for the UI [TBD]

  /api/v1/secrets:
    summary: Path used to retrieve and filter secrets from a namespace.
    description: >-
      The REST endpoint/path used to list and filter Kubernetes secrets based on type and namespace.
    get:
      tags:
        - K8SOperation
      parameters:
        - name: namespace
          in: query
          required: true
          description: The namespace name to query secrets from
          schema:
            type: string
          example: default
        - name: type
          in: query
          required: false
          description: >-
            Secret type filter (key matching is case-sensitive, keys must be uppercase):
            - 'storage': Filters for storage secrets (e.g., S3 secrets with classification keys: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_ENDPOINT)
            - 'lls': Filters for Llama Stack secrets (classification keys: LLAMA_STACK_CLIENT_API_KEY, LLAMA_STACK_CLIENT_BASE_URL)
            - Omit for all secrets

            Type Classification Precedence:
            When determining if a secret matches the requested type filter, the following precedence is applied:
            1. Annotation-based type (highest priority): If the secret has the 'opendatahub.io/connection-type' annotation, that annotated type takes precedence for inclusion in ?type= filter results
            2. Key-based classification (fallback): If no connection-type annotation is present, the type is determined by key-based classification rules (e.g., storage keys like AWS_ACCESS_KEY_ID for ?type=storage, LLS keys like LLAMA_STACK_CLIENT_API_KEY for ?type=lls)

            Note: Classification keys are used to identify the secret type. Additional optional keys (like AWS_S3_BUCKET, AWS_DEFAULT_REGION for S3 secrets)
            may be present but are not required for type classification. The data field in the response lists all keys
            present in each secret, allowing clients to validate additional requirements for their specific use cases.
          schema:
            type: string
            enum:
              - storage
              - lls
          example: storage
      responses:
        "200":
          $ref: "#/components/responses/SecretsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: getSecrets
      summary: Get filtered secrets
      description: >-
        Retrieves secrets from a specified namespace with optional filtering by type.
        Key matching is case-sensitive; keys must be uppercase.

        Secret Type Classification Precedence:
        The type of each secret is determined using the following precedence:
        1. Annotation-based type (highest priority): If the secret has the 'opendatahub.io/connection-type' annotation with a non-empty value, that annotated type is used
        2. Key-based classification (fallback): If no connection-type annotation is present, type is determined by the presence of specific classification keys:
           - 's3': S3 storage secrets (classification keys: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_ENDPOINT)
           - 'lls': Llama Stack secrets (classification keys: LLAMA_STACK_CLIENT_API_KEY, LLAMA_STACK_CLIENT_BASE_URL)

        Optional Keys:
        Secrets may contain additional optional keys beyond classification requirements (e.g., AWS_S3_BUCKET, AWS_DEFAULT_REGION for S3 secrets).
        The data field lists all keys present, allowing clients to validate additional use-case-specific requirements.

        Type filtering with ?type= parameter:
        When filtering by type, the annotated type (if present) takes precedence over key-based classification for determining inclusion in results.
        - 'storage': Returns only secrets classified as storage types (currently: s3 via key-based classification, or any secret with connection-type annotation matching 'storage')
        - 'lls': Returns only secrets classified as LLS type (via key-based classification or connection-type annotation)
        - No type: Returns all secrets with their detected type classification
  # =============================================================================
  # S3 Endpoints
  # =============================================================================

  /api/v1/s3/files/{key}:
    summary: Endpoints for working with a specific file from an S3-compatible connection.
    description: >-
      The REST endpoint/path used to retrieve or upload files in S3 storage.
      Uses the credentials from a specified Kubernetes secret to access the S3 bucket.
      GET returns the file with transfer-encoding: chunked for efficient streaming.
      POST accepts a multipart form file and uploads it to the given bucket and key.
    get:
      tags:
        - S3Operation
      parameters:
        - name: namespace
          in: query
          required: true
          description: The Kubernetes namespace containing the secret
          schema:
            type: string
          example: default
        - name: secretName
          in: query
          required: false
          description: >-
            Override: name of the Kubernetes secret containing S3 credentials.
            When supplied, the secret must use the conventional AWS_* field names
            (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_S3_ENDPOINT).
            When omitted, connection details (endpoint, credentials field names, region, bucket)
            are resolved from the DSPipelineApplication spec discovered in the namespace.
          schema:
            type: string
            maxLength: 253
            pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'
          example: aws-secret-1
        - name: bucket
          in: query
          required: false
          description: The S3 bucket name. Leading and trailing whitespace is trimmed.
          schema:
            type: string
            pattern: '^\S(.*\S)?$'
          example: my-bucket
        - name: key
          in: path
          required: true
          description: The S3 object key to retrieve
          schema:
            type: string
          example: documents/myfile.pdf
      responses:
        "200":
          description: File retrieved successfully
          content:
            "*/*":
              schema:
                type: string
                format: binary
                description: The binary content of the requested file
          headers:
            Transfer-Encoding:
              description: Set to 'chunked' for streaming large files
              schema:
                type: string
                example: chunked
            Content-Type:
              description: The MIME type of the file
              schema:
                type: string
                example: application/pdf
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      operationId: getS3File
      summary: Get file from S3
      description: >-
        Retrieves an arbitrary file from S3 storage. The file is streamed with
        transfer-encoding: chunked to efficiently handle large files.

        Two credential resolution modes are supported:

        **DSPA mode (default in production)** — when secretName is omitted, the endpoint,
        region, bucket, and credential field names are read from the DSPipelineApplication
        (DSPA) spec discovered in the namespace. This works for both external S3 and managed
        MinIO without requiring the caller to know which secret is in use.

        **Explicit mode (override)** — when secretName is supplied, the specified Kubernetes
        secret must contain AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION,
        and AWS_S3_ENDPOINT using those exact field names.
    post:
      tags:
        - S3Operation
      parameters:
        - name: namespace
          in: query
          required: true
          description: The Kubernetes namespace containing the secret
          schema:
            type: string
          example: default
        - name: secretName
          in: query
          required: true
          description: The name of the Kubernetes secret containing S3 credentials
          schema:
            type: string
            maxLength: 253
            pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'
          example: aws-secret-1
        - name: bucket
          in: query
          required: false
          description: The S3 bucket name. Leading and trailing whitespace is trimmed.
          schema:
            type: string
            pattern: '^\S(.*\S)?$'
          example: my-bucket
        - name: key
          in: path
          required: true
          description: The S3 object key where the file will be uploaded
          schema:
            type: string
          example: documents/myfile.pdf
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload to S3
      responses:
        "201":
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/S3UploadSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "413":
          description: >-
            Declared Content-Length too large, or file part exceeds 32 MiB (http.MaxBytesReader).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: uploadS3File
      summary: Upload file to S3
      description: >-
        Uploads a file to S3 storage using credentials from a Kubernetes secret.
        The request must include a multipart form with a file part (e.g. "file").
        The secret must contain valid S3 credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
        AWS_DEFAULT_REGION, AWS_S3_ENDPOINT).
        Chunked transfer encoding is supported. When Content-Length is set, it must not exceed
        32 MiB plus allowance for multipart framing (~64 MiB) or the request is rejected with 413.
        The file part is streamed via http.MaxBytesReader (32 MiB max); larger file parts fail with 413.

        On success, returns JSON with `uploaded: true` and the resolved `key` (which may differ
        from the requested key if a collision was avoided by probing existing keys).

        Returns 409 if the object key chosen after collision resolution still conflicts at upload time
        (e.g. concurrent writer); the client should retry the upload.

  /api/v1/s3/files:
    summary: Endpoints for working with files from an S3-compatible connection.
    get:
      operationId: getS3Files
      summary: Get files from S3
      description: >-
        Retrieves a list of files from an S3-compatible storage.
        Returns the files in a list, plus any additional metadata that ListObjectsV2 returns.


        Two credential resolution modes are supported:
        (1) **DSPA mode (default in production)** — when secretName is omitted, the endpoint,
        region, bucket, and credential field names are read from the DSPipelineApplication
        (DSPA) spec discovered in the namespace.
        (2) **Explicit mode (override)** — when secretName is supplied, the specified Kubernetes
        secret must contain AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION,
        and AWS_S3_ENDPOINT using those exact field names.
      tags:
        - S3Operation
      security:
        - Bearer: []
      parameters:
        - name: namespace
          in: query
          required: true
          description: The Kubernetes namespace containing the secret
          schema:
            type: string
          example: default
        - name: secretName
          in: query
          required: false
          description: >-
            Override: name of the Kubernetes secret containing S3 credentials.
            When supplied, the secret must use the conventional AWS_* field names
            (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_S3_ENDPOINT).
            When omitted, the endpoint falls back to DSPA mode and reads credentials from
            the DSPipelineApplication spec discovered in the namespace.
          schema:
            type: string
            maxLength: 253
            pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'
          example: aws-secret-1
        - name: bucket
          in: query
          required: false
          description: >-
            The S3 bucket name. Only honored when secretName is supplied (explicit mode).
            In DSPA mode (secretName omitted), this parameter is ignored and the bucket
            configured in the DSPipelineApplication spec is used instead; if the DSPA
            does not specify a bucket the request is rejected with 400.
          schema:
            type: string
            pattern: '^\S(.*\S)?$'
          example: my-bucket
        - name: path
          in: query
          required: false
          description: (Optional) S3-like folder path to search within (if omitted, lists bucket root). When provided, must be non-empty and not exceed 1024 characters.
          schema:
            type: string
            minLength: 1
            maxLength: 1024
          example: folder1/folder2/folder3
        - name: search
          in: query
          required: false
          description: The search term to filter results by. S3 only allows searching by leading values. Must not contain '/' characters. Maximum 1024 characters.
          schema:
            type: string
            maxLength: 1024
            pattern: "^[^/]*$"
          example: my-search-query
        - name: next
          in: query
          required: false
          description: The token value to use for the next page
          schema:
            type: string
            minLength: 1
          example: /continuationtokenexample
        - name: limit
          in: query
          required: false
          description: The limit for the number of items to return per page
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
          example: 20
      responses:
        "200":
          $ref: "#/components/responses/S3GetFilesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  # =============================================================================
  # LSD ENDPOINTS
  # =============================================================================

  /api/v1/lsd/models:
    summary: List available LSD models
    description: >-
      Lists all available models from LlamaStack Distribution (LSD).
      Returns a flat list of models with their identifiers, types, provider information, and resource paths.
      Requires namespace and secretName parameters. The secretName identifies a Kubernetes secret
      containing LLAMA_STACK_CLIENT_BASE_URL and LLAMA_STACK_CLIENT_API_KEY credentials.
    get:
      tags:
        - Models
      security:
        - Bearer: []
      parameters:
        - name: namespace
          in: query
          description: Kubernetes namespace containing the LlamaStack credentials secret
          required: true
          schema:
            type: string
            example: 'default'
        - name: secretName
          in: query
          description: Name of the Kubernetes secret containing LlamaStack credentials (LLAMA_STACK_CLIENT_BASE_URL and LLAMA_STACK_CLIENT_API_KEY)
          required: true
          schema:
            type: string
            maxLength: 253
            pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'
            example: 'my-lls-secret'
      responses:
        "200":
          $ref: "#/components/responses/LSDModelsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
      operationId: getLSDModels
      summary: Get LSD Models
      description: Returns available models from LlamaStack Distribution using credentials from a Kubernetes secret

  /api/v1/lsd/vector-stores:
    summary: List available LSD vector store providers
    description: >-
      Lists available vector store providers from LlamaStack Distribution (LSD).
      Calls the native /v1/providers endpoint and filters for vector_io API type.
      Returns provider identifiers and types (e.g., remote::milvus).
      Requires namespace and secretName parameters. The secretName identifies a Kubernetes secret
      containing LLAMA_STACK_CLIENT_BASE_URL and LLAMA_STACK_CLIENT_API_KEY credentials.
    get:
      tags:
        - VectorStores
      security:
        - Bearer: []
      parameters:
        - name: namespace
          in: query
          description: Kubernetes namespace containing the LlamaStack credentials secret
          required: true
          schema:
            type: string
            example: 'default'
        - name: secretName
          in: query
          description: Name of the Kubernetes secret containing LlamaStack credentials (LLAMA_STACK_CLIENT_BASE_URL and LLAMA_STACK_CLIENT_API_KEY)
          required: true
          schema:
            type: string
            example: 'my-lls-secret'
      responses:
        "200":
          $ref: "#/components/responses/LSDVectorStoresResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
      operationId: getLSDVectorStoreProviders
      summary: Get LSD Vector Store Providers
      description: Returns available vector store providers from LlamaStack Distribution using credentials from a Kubernetes secret

  # =============================================================================
  # PIPELINE RUNS ENDPOINTS
  # =============================================================================

  /api/v1/pipeline-runs:
    summary: Pipeline run operations
    description: >-
      Endpoints for listing and creating pipeline runs from the Pipeline Server
      in the specified namespace. The Pipeline Server (DSPipelineApplication)
      is automatically discovered.
    get:
      tags:
        - PipelineOperation
      security:
        - Bearer: []
      parameters:
        - $ref: "#/components/parameters/namespace"
        - $ref: "#/components/parameters/pageSize"
        - $ref: "#/components/parameters/nextPageToken"
      responses:
        "200":
          $ref: "#/components/responses/PipelineRunsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      operationId: getPipelineRuns
      summary: Get Pipeline Runs
      description: >-
        Returns pipeline runs filtered to the auto-discovered AutoRAG managed pipeline version.
        The AutoRAG pipeline is automatically discovered in the namespace by name prefix.
        Returns 500 if no managed AutoRAG pipeline is found in the namespace.
    post:
      tags:
        - PipelineOperation
      security:
        - Bearer: []
      parameters:
        - $ref: "#/components/parameters/namespace"
        - name: pipelineType
          in: query
          required: false
          schema:
            type: string
            enum:
              - autorag
            default: autorag
          description: >-
            Selects which discovered AutoRAG pipeline to use for this run.
            Currently only "autorag" is supported. Defaults to "autorag" when omitted.
          example: "autorag"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAutoRAGRunRequest"
      responses:
        "200":
          $ref: "#/components/responses/CreatePipelineRunResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      operationId: createPipelineRun
      summary: Create Pipeline Run
      description: >-
        Creates a new AutoRAG pipeline run. The BFF automatically discovers the managed
        AutoRAG pipeline in the namespace and injects the pipeline ID and version ID.
        The optional pipelineType parameter selects which discovered pipeline to use
        (currently only "autorag" is supported). If no matching AutoRAG pipeline is found,
        returns a 500 error. The Pipeline Server (DSPipelineApplication) is also
        auto-discovered. The BFF maps AutoRAG-specific parameters to KFP v2beta1 runtime
        config and submits the run.

  /api/v1/pipeline-runs/{runId}:
    summary: Get a single pipeline run by ID
    description: >-
      Retrieves a single pipeline run by its unique identifier from the
      Pipeline Server in the specified namespace. The Pipeline Server
      (DSPipelineApplication) and AutoRAG managed pipeline are automatically discovered.
      The run is validated to ensure it belongs to the discovered AutoRAG pipeline before
      being returned. Returns 404 if the run doesn't exist or belongs to a different pipeline.
      Returns 500 if no AutoRAG pipeline is found in the namespace.
    get:
      tags:
        - PipelineOperation
      security:
        - Bearer: []
      parameters:
        - $ref: "#/components/parameters/namespace"
        - name: runId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the pipeline run
          example: "abc123-def456-ghi789"
      responses:
        "200":
          $ref: "#/components/responses/PipelineRunResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      operationId: getPipelineRunById
      summary: Get Pipeline Run by ID
      description: >-
        Returns a single pipeline run by its unique identifier, but only if it belongs to the
        discovered AutoRAG managed pipeline in the namespace. This ensures users can only access
        runs from the AutoRAG pipeline and not runs from other pipelines in the same namespace.

  /api/v1/pipeline-runs/{runId}/terminate:
    summary: Terminate an active pipeline run
    description: >-
      Terminates an active pipeline run, cancelling all running tasks and transitioning the run
      to CANCELING and then CANCELED state. The run must be in an active state (PENDING, RUNNING,
      PAUSED, or CANCELING) and belong to the discovered AutoRAG pipeline in the namespace.
      Returns 400 if the run is not in a terminatable state, or 404 if the run doesn't exist or
      belongs to a different pipeline.
    post:
      tags:
        - PipelineOperation
      security:
        - Bearer: []
      parameters:
        - $ref: "#/components/parameters/namespace"
        - name: runId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the pipeline run to terminate
          example: "abc123-def456-ghi789"
      responses:
        "200":
          description: Run terminated successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      operationId: terminatePipelineRun
      summary: Terminate Pipeline Run
      description: >-
        Terminates an active AutoRAG pipeline run by transitioning it to CANCELING and then
        CANCELED state. The run must be in an active state (PENDING, RUNNING, PAUSED, or
        CANCELING). The BFF validates that the run belongs to the discovered AutoRAG managed
        pipeline in the namespace and that it is in a terminatable state before proceeding.
        Returns 400 if the run is not in a terminatable state.

  /api/v1/pipeline-runs/{runId}/retry:
    summary: Retry a failed or canceled pipeline run
    description: >-
      Re-initiates a failed or canceled pipeline run from the point of failure. The run must
      belong to the discovered AutoRAG pipeline in the namespace and must be in FAILED or
      CANCELED state. Returns 400 if the run is not in a retryable state, or 404 if the run
      doesn't exist or belongs to a different pipeline.
    post:
      tags:
        - PipelineOperation
      security:
        - Bearer: []
      parameters:
        - $ref: "#/components/parameters/namespace"
        - name: runId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the pipeline run to retry
          example: "abc123-def456-ghi789"
      responses:
        "200":
          description: Run retry initiated successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      operationId: retryPipelineRun
      summary: Retry Pipeline Run
      description: >-
        Re-initiates a failed or canceled AutoRAG pipeline run. The BFF validates that the run
        belongs to the discovered AutoRAG managed pipeline in the namespace and that it is in a
        retryable state (FAILED or CANCELED) before retrying it. This prevents users from
        retrying runs from other pipelines in the same namespace.

components:
  schemas:
    Config:
      required:
        - userId
        - clusterAdmin
      type: object
      properties:
        userId:
          type: string
          example: user@example.com
        clusterAdmin:
          type: boolean
          example: true

    # LSD Model Schemas
    LSDModel:
      type: object
      description: Model from LlamaStack Distribution
      required:
        - id
        - type
        - provider
      properties:
        id:
          type: string
          description: Unique model identifier
          example: "llama3.2:3b"
        type:
          type: string
          enum: ["llm", "embedding"]
          description: Model type (llm or embedding)
          example: "llm"
        provider:
          type: string
          description: Provider identifier
          example: "ollama"
        resource_path:
          type: string
          description: Full provider resource path
          example: "ollama://models/llama3.2:3b"
    LSDModelsData:
      type: object
      description: List of all available models from LlamaStack Distribution
      required:
        - models
      properties:
        models:
          type: array
          description: Complete list of all available models
          items:
            $ref: '#/components/schemas/LSDModel'

    LSDVectorStoreProvider:
      type: object
      description: Vector store provider from LlamaStack Distribution
      required:
        - provider_id
        - provider_type
      properties:
        provider_id:
          type: string
          description: Provider identifier
          example: "milvus"
        provider_type:
          type: string
          description: Provider implementation type
          example: "remote::milvus"
    LSDVectorStoreProvidersData:
      type: object
      description: List of vector store providers from LlamaStack Distribution
      required:
        - vector_store_providers
      properties:
        vector_store_providers:
          type: array
          description: List of vector_io providers
          items:
            $ref: '#/components/schemas/LSDVectorStoreProvider'

    SecretTypeSchema:
      description: >-
        Schema defining the classification and optional keys for a secret type.
        Classification keys are used to identify the secret type.
        Optional keys are commonly used but not required for type classification.
      type: object
      properties:
        classificationKeys:
          type: array
          items:
            type: string
          description: Keys required for BFF to classify a secret as this type (case-sensitive, uppercase)
        commonOptionalKeys:
          type: array
          items:
            type: string
          description: Common optional keys that may be required for specific use cases but not for type classification

    SecretTypeSchemas:
      description: Reference documentation for secret type schemas
      type: object
      properties:
        s3:
          allOf:
            - $ref: '#/components/schemas/SecretTypeSchema'
            - type: object
              properties:
                classificationKeys:
                  example: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_S3_ENDPOINT"]
                commonOptionalKeys:
                  example: ["AWS_S3_BUCKET", "AWS_DEFAULT_REGION"]
        lls:
          allOf:
            - $ref: '#/components/schemas/SecretTypeSchema'
            - type: object
              properties:
                classificationKeys:
                  example: ["LLAMA_STACK_CLIENT_API_KEY", "LLAMA_STACK_CLIENT_BASE_URL"]
                commonOptionalKeys:
                  example: []

    SecretListItem:
      description: A Kubernetes secret with its UUID, name, type classification, and available keys
      required:
        - uuid
        - name
        - data
      type: object
      properties:
        uuid:
          type: string
          description: The Kubernetes UID of the secret
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: The name of the secret
          example: aws-secret-1
        type:
          type: string
          description: >-
            Optional type of the secret determined by the following precedence:
            1. First priority: The 'opendatahub.io/connection-type' annotation if present and non-empty
            2. Fallback: Key-based type detection (see SecretTypeSchemas):
               - 's3': S3 storage secret (has all required S3 classification keys)
               - 'lls': Llama Stack secret (has all required LLS classification keys)

            When filtering with the ?type= parameter, the annotated type (if present) takes precedence over key-based classification
            for determining inclusion in results. This means a secret with connection-type='storage' will be included in ?type=storage
            results even if it lacks the typical storage classification keys.

            This field is omitted from the response if the secret doesn't match any recognized type and has no connection-type annotation.
          example: s3
        data:
          type: object
          additionalProperties:
            type: string
          description: >-
            Object mapping all keys available in the secret to their values.
            Keys are case-preserved. Most values are sanitized as "[REDACTED]" for security.
            Only specific allowed keys (currently: AWS_S3_BUCKET) return their actual values.
            Use this field to validate that additional optional keys required for your use case are present (via Object.keys()).
          example: {"AWS_ACCESS_KEY_ID": "[REDACTED]", "AWS_DEFAULT_REGION": "[REDACTED]", "AWS_S3_ENDPOINT": "[REDACTED]", "AWS_SECRET_ACCESS_KEY": "[REDACTED]", "AWS_S3_BUCKET": "my-bucket-name"}
        displayName:
          type: string
          description: >-
            Optional human-readable display name from the 'openshift.io/display-name' annotation.
            This field is only included in the response if the annotation exists on the secret.
          example: Production S3 Bucket
        description:
          type: string
          description: >-
            Optional human-readable description from the 'openshift.io/description' annotation.
            This field is only included in the response if the annotation exists on the secret.
          example: Main S3 bucket for production data storage and backups

    # Pipeline Run Schemas
    PipelineRun:
      type: object
      description: Kubeflow Pipeline Run information
      required:
        - run_id
        - display_name
        - state
        - created_at
      properties:
        run_id:
          type: string
          description: Unique pipeline run identifier
          example: "abc123-def456-ghi789"
        display_name:
          type: string
          description: Human-readable run name
          example: "AutoRAG Optimization Run 1"
        description:
          type: string
          description: Run description
          example: "Optimizing RAG parameters for dataset X"
        experiment_id:
          type: string
          description: ID of the experiment this run belongs to
          example: "1858af57-f990-4aee-a03e-c93bdfd02eb3"
        pipeline_version_reference:
          type: object
          description: Reference to pipeline and version
          properties:
            pipeline_id:
              type: string
              description: ID of the pipeline
              example: "9e3940d5-b275-4b64-be10-b914cd06c58e"
            pipeline_version_id:
              type: string
              description: ID of the pipeline version
              example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        runtime_config:
          type: object
          description: Runtime configuration used for this run, including pipeline parameters
          nullable: true
          properties:
            parameters:
              type: object
              description: Key-value map of pipeline parameters
              additionalProperties: true
              example:
                optimization_metric: "faithfulness"
                test_data_secret_name: "minio-secret"
                test_data_bucket_name: "autorag"
            pipeline_root:
              type: string
              description: Root output directory for pipeline artifacts
        state:
          type: string
          enum: [UNKNOWN, PENDING, RUNNING, SUCCEEDED, SKIPPED, FAILED, ERROR, CANCELED, CANCELING, PAUSED]
          description: Current run state
          example: "SUCCEEDED"
        storage_state:
          type: string
          description: Storage state of the run
          example: "AVAILABLE"
        service_account:
          type: string
          description: Service account used to run the pipeline
          example: "pipeline-runner-dspa"
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
          example: "2026-02-24T10:30:00Z"
        scheduled_at:
          type: string
          format: date-time
          description: Scheduled timestamp (ISO 8601)
          example: "2026-02-24T10:30:00Z"
        finished_at:
          type: string
          format: date-time
          description: Completion timestamp (ISO 8601)
          example: "2026-02-24T11:15:00Z"
        error:
          type: object
          description: Error information if the run failed
          nullable: true
          properties:
            code:
              type: integer
              format: int32
              description: Error code
            message:
              type: string
              description: Error message
        state_history:
          type: array
          description: History of state changes
          items:
            type: object
            properties:
              update_time:
                type: string
                format: date-time
                description: When the state changed
                example: "2026-02-24T10:30:00Z"
              state:
                type: string
                description: The state at this time
                example: "RUNNING"
              error:
                type: object
                description: Optional error information if the state change was due to an error
                nullable: true
                properties:
                  code:
                    type: integer
                    format: int32
                    description: Error code
                  message:
                    type: string
                    description: Error message
        run_details:
          type: object
          description: Detailed information about the pipeline run including task execution details
          nullable: true
          properties:
            task_details:
              type: array
              description: List of tasks executed as part of this pipeline run
              items:
                type: object
                properties:
                  run_id:
                    type: string
                    description: ID of the pipeline run this task belongs to
                    example: "abc123-def456"
                  task_id:
                    type: string
                    description: Unique identifier for this task
                    example: "task-data-preprocessing"
                  display_name:
                    type: string
                    description: Human-readable task name
                    example: "Data Preprocessing"
                  create_time:
                    type: string
                    format: date-time
                    description: When the task was created
                    example: "2026-02-24T10:30:00Z"
                  start_time:
                    type: string
                    format: date-time
                    description: When the task started executing
                    example: "2026-02-24T10:30:05Z"
                  end_time:
                    type: string
                    format: date-time
                    description: When the task completed
                    example: "2026-02-24T10:35:00Z"
                  state:
                    type: string
                    enum: [UNKNOWN, PENDING, RUNNING, SUCCEEDED, SKIPPED, FAILED, ERROR, CANCELED, CANCELING, PAUSED]
                    description: Current task state
                    example: "SUCCEEDED"
                  state_history:
                    type: array
                    description: History of state changes for this task
                    items:
                      type: object
                      properties:
                        update_time:
                          type: string
                          format: date-time
                          description: When the state changed
                          example: "2026-02-24T10:30:00Z"
                        state:
                          type: string
                          description: The state at this time
                          example: "RUNNING"
                  child_tasks:
                    type: array
                    description: Child tasks or pods created by this task
                    items:
                      type: object
                      properties:
                        pod_name:
                          type: string
                          description: Name of the Kubernetes pod running this task
                          example: "data-preprocessing-pod-abc123"
        pipeline_type:
          type: string
          enum:
            - autorag
          description: >-
            Type of the pipeline that produced this run. Always "autorag" for
            AutoRAG pipeline runs.
          example: "autorag"

    CreateAutoRAGRunRequest:
      type: object
      description: Request body for creating an AutoRAG pipeline run
      required:
        - display_name
        - test_data_secret_name
        - test_data_bucket_name
        - test_data_key
        - input_data_secret_name
        - input_data_bucket_name
        - input_data_key
        - llama_stack_secret_name
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 250
          description: Human-readable name for the run
          example: "my-optimization-run"
        description:
          type: string
          description: Optional description of the run
        test_data_secret_name:
          type: string
          description: Name of the K8s secret containing test data credentials
        test_data_bucket_name:
          type: string
          description: S3 bucket name for test data
        test_data_key:
          type: string
          description: Object key within the test data bucket
        input_data_secret_name:
          type: string
          description: Name of the K8s secret containing input data credentials
        input_data_bucket_name:
          type: string
          description: S3 bucket name for input data
        input_data_key:
          type: string
          description: Object key within the input data bucket
        llama_stack_secret_name:
          type: string
          description: Name of the K8s secret for LlamaStack access
        embeddings_models:
          type: array
          items:
            type: string
          description: Optional list of embedding model identifiers
        generation_models:
          type: array
          items:
            type: string
          description: Optional list of generation model identifiers
        optimization_metric:
          type: string
          enum:
            - faithfulness
            - answer_correctness
            - context_correctness
          description: Metric to optimize (defaults to faithfulness)
        llama_stack_vector_io_provider_id:
          type: string
          description: Pipeline vector store provider ID from the selected LlamaStack provider (e.g. milvus)
          example: milvus
        optimization_max_rag_patterns:
          type: integer
          minimum: 4
          maximum: 20
          description: Maximum number of RAG patterns to generate. Passed to ai4rag (max_number_of_rag_patterns). Defaults to 8.
          default: 8
      additionalProperties: false

    PipelineRunsData:
      type: object
      description: List of pipeline runs with pagination support
      required:
        - runs
      properties:
        runs:
          type: array
          description: Array of pipeline runs
          maxItems: 100
          items:
            $ref: '#/components/schemas/PipelineRun'
        total_size:
          type: integer
          format: int32
          description: Total number of runs matching the filter
          example: 42
        next_page_token:
          type: string
          description: Token for retrieving the next page
          example: "eyJwYWdlIjoyfQ=="

    S3UploadSuccess:
      description: Response body for successful S3 file upload
      required:
        - uploaded
        - key
      type: object
      properties:
        uploaded:
          type: boolean
          example: true
        key:
          type: string
          description: >-
            The actual S3 key used for the uploaded file. When the requested key already exists,
            the server appends or increments a numeric suffix (for example: file.pdf -> file-1.pdf).
          example: documents/myfile-1.pdf

    S3ListObjectsResult:
      type: object
      description: A listing of S3 objects and virtual folders within a bucket prefix.
      properties:
        common_prefixes:
          type: array
          items:
            type: object
            properties:
              prefix:
                type: string
        contents:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              last_modified:
                type: string
                format: date-time
              etag:
                type: string
              size:
                type: integer
                format: int64
              storage_class:
                type: string
        continuation_token:
          type: string
        delimiter:
          type: string
        is_truncated:
          type: boolean
        key_count:
          type: integer
          format: int32
        max_keys:
          type: integer
          format: int32
        name:
          type: string
        next_continuation_token:
          type: string
        prefix:
          type: string

    BaseResource:
      allOf:
        - $ref: "#/components/schemas/BaseResourceCreate"
        - type: object
          properties:
            id:
              format: int64
              description: Output only. The unique server generated id of the resource.
              type: string
              readOnly: true
            createTimeSinceEpoch:
              format: int64
              description: Output only. Create time of the resource in millisecond since epoch.
              type: string
              readOnly: true
            lastUpdateTimeSinceEpoch:
              format: int64
              description: |-
                Output only. Last update time of the resource since epoch in millisecond
                since epoch.
              type: string
              readOnly: true
    BaseResourceCreate:
      allOf:
        - $ref: "#/components/schemas/BaseResourceUpdate"
        - type: object
          properties:
            name:
              description: |-
                The client provided name of the artifact. This field is optional. If set,
                it must be unique among all the artifacts of the same artifact type within
                a database instance and cannot be changed once set.
              type: string
    BaseResourceUpdate:
      type: object
      properties:
        customProperties:
          description: User provided custom properties which are not defined by its type.
          type: object
          additionalProperties:
            $ref: "#/components/schemas/MetadataValue"
        description:
          description: |-
            An optional description about the resource.
          type: string
        externalId:
          description: |-
            The external id that come from the clients' system. This field is optional.
            If set, it must be unique among all resources within a database instance.
          type: string
    MetadataValue:
      oneOf:
        - $ref: "#/components/schemas/MetadataIntValue"
        - $ref: "#/components/schemas/MetadataDoubleValue"
        - $ref: "#/components/schemas/MetadataStringValue"
        - $ref: "#/components/schemas/MetadataStructValue"
        - $ref: "#/components/schemas/MetadataProtoValue"
        - $ref: "#/components/schemas/MetadataBoolValue"
      discriminator:
        propertyName: metadataType
        mapping:
          MetadataBoolValue: "#/components/schemas/MetadataBoolValue"
          MetadataDoubleValue: "#/components/schemas/MetadataDoubleValue"
          MetadataIntValue: "#/components/schemas/MetadataIntValue"
          MetadataProtoValue: "#/components/schemas/MetadataProtoValue"
          MetadataStringValue: "#/components/schemas/MetadataStringValue"
          MetadataStructValue: "#/components/schemas/MetadataStructValue"
      description: A value in properties.
    MetadataIntValue:
      description: An integer (int64) property value.
      type: object
      required:
        - metadataType
        - int_value
      properties:
        int_value:
          format: int64
          type: string
        metadataType:
          type: string
          example: MetadataIntValue
          default: MetadataIntValue
    MetadataDoubleValue:
      description: A double property value.
      type: object
      required:
        - metadataType
        - double_value
      properties:
        double_value:
          format: double
          type: number
        metadataType:
          type: string
          example: MetadataDoubleValue
          default: MetadataDoubleValue
    MetadataStringValue:
      description: A string property value.
      type: object
      required:
        - metadataType
        - string_value
      properties:
        string_value:
          type: string
        metadataType:
          type: string
          example: MetadataStringValue
          default: MetadataStringValue
    MetadataStructValue:
      description: A struct property value.
      type: object
      required:
        - metadataType
        - struct_value
      properties:
        struct_value:
          description: Base64 encoded bytes for struct value
          type: string
        metadataType:
          type: string
          example: MetadataStructValue
          default: MetadataStructValue
    MetadataProtoValue:
      description: A proto property value.
      type: object
      required:
        - metadataType
        - type
        - proto_value
      properties:
        type:
          description: url describing proto value
          type: string
        proto_value:
          description: Base64 encoded bytes for proto value
          type: string
        metadataType:
          type: string
          example: MetadataProtoValue
          default: MetadataProtoValue
    MetadataBoolValue:
      description: A bool property value.
      type: object
      required:
        - metadataType
        - bool_value
      properties:
        bool_value:
          type: boolean
        metadataType:
          type: string
          example: MetadataBoolValue
          default: MetadataBoolValue

    Error:
      description: Error code and message.
      required:
        - code
        - message
      type: object
      properties:
        code:
          description: Error code
          type: string
        message:
          description: Error message
          type: string
    ErrorEnvelope:
      description: Envelope wrapping an Error response.
      required:
        - error
      type: object
      properties:
        error:
          $ref: "#/components/schemas/Error"
    SortOrder:
      description: Supported sort direction for ordering result entities.
      enum:
        - ASC
        - DESC
      type: string
    OrderByField:
      description: Supported fields for ordering result entities.
      enum:
        - CREATE_TIME
        - LAST_UPDATE_TIME
        - Id
      type: string

  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
      description: The specified resource was not found
    BadRequest:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
      description: Bad Request parameters
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
      description: Unauthorized
    Forbidden:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
      description: Forbidden - insufficient permissions
    Conflict:
      description: >-
        Conflict (e.g. S3 conditional upload failed because the object already exists at the
        resolved key; client may retry the request)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    InternalServerError:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
      description: Unexpected internal server error
    ServiceUnavailable:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
      description: Service temporarily unavailable
    BadGateway:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
      description: Bad Gateway - upstream service is unreachable
    ConfigResponse:
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                type: object
                description: Metadata about the response
              data:
                $ref: "#/components/schemas/Config"
      description: A response containing a list of Config entities.

    # LSD Responses
    LSDModelsResponse:
      description: List of available LSD models
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                type: object
                description: Metadata about the response
              data:
                $ref: '#/components/schemas/LSDModelsData'
          example:
            metadata: {}
            data:
              models:
                - id: "llama3.2:3b"
                  type: "llm"
                  provider: "ollama"
                  resource_path: "ollama://models/llama3.2:3b"
                - id: "mistral-7b-instruct"
                  type: "llm"
                  provider: "ollama"
                  resource_path: "ollama://models/mistral-7b-instruct"
                - id: "all-minilm:l6-v2"
                  type: "embedding"
                  provider: "ollama"
                  resource_path: "ollama://models/all-minilm:l6-v2"
                - id: "nomic-embed-text"
                  type: "embedding"
                  provider: "ollama"
                  resource_path: "ollama://models/nomic-embed-text"

    LSDVectorStoresResponse:
      description: List of available LSD vector store providers
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                type: object
                description: Metadata about the response
              data:
                $ref: '#/components/schemas/LSDVectorStoreProvidersData'
          example:
            metadata: {}
            data:
              vector_store_providers:
                - provider_id: "milvus"
                  provider_type: "remote::milvus"
                - provider_id: "faiss"
                  provider_type: "inline::faiss"

    SecretsResponse:
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                type: object
                description: Metadata about the response
              data:
                type: array
                description: List of filtered secrets
                items:
                  $ref: "#/components/schemas/SecretListItem"
          examples:
            storageSecrets:
              summary: Example response with storage (S3) secrets
              value:
                data:
                  - uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    name: aws-secret-1
                    type: s3
                    data: {"AWS_ACCESS_KEY_ID": "[REDACTED]", "AWS_DEFAULT_REGION": "[REDACTED]", "AWS_S3_ENDPOINT": "[REDACTED]", "AWS_SECRET_ACCESS_KEY": "[REDACTED]", "AWS_S3_BUCKET": "my-production-bucket"}
                    displayName: Production S3 Bucket
                  - uuid: b2c3d4e5-f6a7-8901-bcde-f01234567891
                    name: aws-secret-2
                    type: s3
                    data: {"AWS_ACCESS_KEY_ID": "[REDACTED]", "AWS_DEFAULT_REGION": "[REDACTED]", "AWS_S3_ENDPOINT": "[REDACTED]", "AWS_SECRET_ACCESS_KEY": "[REDACTED]"}
            llsSecrets:
              summary: Example response with LLS (Llama Stack) secrets
              value:
                data:
                  - uuid: c1d2e3f4-a5b6-7890-cdef-ab1234567890
                    name: llama-stack-secret-1
                    type: lls
                    data: {"LLAMA_STACK_CLIENT_API_KEY": "[REDACTED]", "LLAMA_STACK_CLIENT_BASE_URL": "[REDACTED]"}
                    displayName: Development LLS
                    description: Llama Stack connection for development and testing
                  - uuid: d2e3f4a5-b6c7-8901-defa-bc2345678901
                    name: llama-stack-secret-2
                    type: lls
                    data: {"LLAMA_STACK_CLIENT_API_KEY": "[REDACTED]", "LLAMA_STACK_CLIENT_BASE_URL": "[REDACTED]"}
            allSecrets:
              summary: Example response with all secrets (no type filter)
              value:
                data:
                  - uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    name: s3-secret
                    type: s3
                    data: {"AWS_ACCESS_KEY_ID": "[REDACTED]", "AWS_DEFAULT_REGION": "[REDACTED]", "AWS_S3_ENDPOINT": "[REDACTED]", "AWS_SECRET_ACCESS_KEY": "[REDACTED]", "AWS_S3_BUCKET": "my-bucket"}
                    displayName: Production S3 Bucket
                    description: Main S3 bucket for production data storage and backups
                  - uuid: c1d2e3f4-a5b6-7890-cdef-ab1234567890
                    name: lls-secret
                    type: lls
                    data: {"LLAMA_STACK_CLIENT_API_KEY": "[REDACTED]", "LLAMA_STACK_CLIENT_BASE_URL": "[REDACTED]"}
                    displayName: Development LLS
                  - uuid: b2c3d4e5-f6a7-8901-bcde-f01234567891
                    name: other-secret
                    data: {"password": "[REDACTED]", "username": "[REDACTED]"}
            emptyList:
              summary: Example response with no matching secrets
              value:
                data: []
      description: A response containing a list of filtered secret items

    PipelineRunsResponse:
      description: Successful response containing pipeline runs
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                type: object
                description: Response metadata
              data:
                $ref: '#/components/schemas/PipelineRunsData'
          example:
            metadata: {}
            data:
              runs:
                - run_id: "abc123-def456"
                  display_name: "AutoRAG Optimization Run 1"
                  description: "Optimizing RAG parameters for dataset X"
                  experiment_id: "1858af57-f990-4aee-a03e-c93bdfd02eb3"
                  pipeline_version_reference:
                    pipeline_id: "9e3940d5-b275-4b64-be10-b914cd06c58e"
                    pipeline_version_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                  state: "SUCCEEDED"
                  storage_state: "AVAILABLE"
                  service_account: "pipeline-runner-dspa"
                  created_at: "2026-02-24T10:30:00Z"
                  scheduled_at: "2026-02-24T10:30:00Z"
                  finished_at: "2026-02-24T11:15:00Z"
                  state_history:
                    - update_time: "2026-02-24T10:30:00Z"
                      state: "RUNNING"
                    - update_time: "2026-02-24T11:15:00Z"
                      state: "SUCCEEDED"
              total_size: 1
              next_page_token: ""

    CreatePipelineRunResponse:
      description: Successful response containing the created pipeline run
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                type: object
                description: Response metadata
              data:
                $ref: '#/components/schemas/PipelineRun'
          example:
            metadata: {}
            data:
              run_id: "abc123-def456"
              display_name: "my-optimization-run"
              state: "PENDING"
              created_at: "2026-02-25T10:30:00Z"
              pipeline_version_reference:
                pipeline_id: "9e3940d5-b275-4b64-be10-b914cd06c58e"
                pipeline_version_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              runtime_config:
                parameters:
                  optimization_metric: "faithfulness"
                  test_data_secret_name: "minio-secret"
                  test_data_bucket_name: "autorag"
                  test_data_key: "test_data.json"
                  input_data_secret_name: "minio-secret"
                  input_data_bucket_name: "autorag"
                  input_data_key: "documents/"
                  llama_stack_secret_name: "llama-secret"

    PipelineRunResponse:
      description: Successful response containing a single pipeline run
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                type: object
                description: Response metadata
              data:
                $ref: '#/components/schemas/PipelineRun'
          example:
            metadata: {}
            data:
              run_id: "abc123-def456"
              display_name: "AutoRAG Optimization Run 1"
              description: "Optimizing RAG parameters for dataset X"
              experiment_id: "1858af57-f990-4aee-a03e-c93bdfd02eb3"
              pipeline_version_reference:
                pipeline_id: "9e3940d5-b275-4b64-be10-b914cd06c58e"
                pipeline_version_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              state: "SUCCEEDED"
              storage_state: "AVAILABLE"
              service_account: "pipeline-runner-dspa"
              created_at: "2026-02-24T10:30:00Z"
              scheduled_at: "2026-02-24T10:30:00Z"
              finished_at: "2026-02-24T11:15:00Z"
              state_history:
                - update_time: "2026-02-24T10:30:00Z"
                  state: "RUNNING"
                - update_time: "2026-02-24T11:15:00Z"
                  state: "SUCCEEDED"
              run_details:
                task_details:
                  - run_id: "abc123-def456"
                    task_id: "task-data-preprocessing"
                    display_name: "Data Preprocessing"
                    create_time: "2026-02-24T10:30:00Z"
                    start_time: "2026-02-24T10:30:05Z"
                    end_time: "2026-02-24T10:35:00Z"
                    state: "SUCCEEDED"
                    state_history:
                      - update_time: "2026-02-24T10:30:05Z"
                        state: "RUNNING"
                      - update_time: "2026-02-24T10:35:00Z"
                        state: "SUCCEEDED"
                    child_tasks:
                      - pod_name: "data-preprocessing-pod-abc123"
                  - run_id: "abc123-def456"
                    task_id: "task-model-training"
                    display_name: "Model Training"
                    create_time: "2026-02-24T10:30:00Z"
                    start_time: "2026-02-24T10:35:10Z"
                    end_time: "2026-02-24T11:10:00Z"
                    state: "SUCCEEDED"
                    state_history:
                      - update_time: "2026-02-24T10:35:10Z"
                        state: "RUNNING"
                      - update_time: "2026-02-24T11:10:00Z"
                        state: "SUCCEEDED"
                    child_tasks:
                      - pod_name: "model-training-pod-def456"

    ConflictResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
      description: Conflict - Role Binding with the same name already exists

    S3GetFilesResponse:
      description: S3 response when retrieving files successfully
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                type: object
                description: Response metadata
              data:
                $ref: "#/components/schemas/S3ListObjectsResult"

  parameters:
    kubeflowUserId:
      in: header
      name: kubeflow-userid
      schema:
        type: string
      required: true
    id:
      name: id
      description: The ID of resource.
      schema:
        type: string
      in: path
      required: true
    name:
      examples:
        name:
          value: entity-name
      name: name
      description: Name of entity to search.
      schema:
        type: string
      in: query
      required: false
    externalId:
      examples:
        externalId:
          value: "10"
      name: externalId
      description: External ID of entity to search.
      schema:
        type: string
      in: query
      required: false
    parentResourceId:
      examples:
        parentResourceId:
          value: "10"
      name: parentResourceId
      description: ID of the parent resource to use for search.
      schema:
        type: string
      in: query
      required: false
    pageSize:
      examples:
        pageSize:
          value: 100
      name: pageSize
      description: Number of entities in each page.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 20
      in: query
      required: false
    nextPageToken:
      name: nextPageToken
      description: Token to use to retrieve next page of results.
      schema:
        type: string
      in: query
      required: false
    orderBy:
      style: form
      explode: true
      examples:
        orderBy:
          value: Id
      name: orderBy
      description: Specifies the order by criteria for listing entities.
      schema:
        $ref: "#/components/schemas/OrderByField"
      in: query
      required: false
    sortOrder:
      style: form
      explode: true
      examples:
        sortOrder:
          value: DESC
      name: sortOrder
      description: "Specifies the sort order for listing entities, defaults to ASC."
      schema:
        $ref: "#/components/schemas/SortOrder"
      in: query
      required: false
    namespace:
      name: namespace
      description: The namespace to filter resources by.
      schema:
        type: string
      in: query
      required: true

  securitySchemes:
    Bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Bearer JWT scheme
security:
  - Bearer: []
tags:
  - name: K8SOperation
    description: Operation performed in Kubernetes
  - name: S3Operation
    description: Operation performed on S3 storage
  - name: Models
    description: AI model discovery and management from LlamaStack Distribution
  - name: PipelineOperation
    description: Operations for querying Kubeflow Pipeline runs
  - name: VectorStores
    description: Vector store provider discovery from LlamaStack Distribution