automl.yaml

openapi: 3.0.3
info:
  title: AutoML REST API
  version: 1.0.0
  description: REST API AutoML 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/user:
    summary: Path used to retrieve a user associated with the token.
    description: >-
      The REST endpoint/path used to get the configuration object.
    get:
      tags:
        - K8SOperation
      security:
        - Bearer: []
      responses:
        "200":
          $ref: "#/components/responses/ConfigResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: getUser
      summary: Get User
      description: Get User 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: Get Available Namespaces endpoint.
  /api/v1/model-registries:
    summary: List available Model Registry instances
    description: >-
      Returns all ModelRegistry instances from the rhoai-model-registries namespace.
      Registries are presented as global in the RHOAI UX; no namespace parameter is required.
      Each entry includes the registry id, name, readiness, and server URL needed
      to route subsequent model registration calls to the correct registry service.

      Required RBAC: User must have 'list' permission for
      modelregistries.modelregistry.opendatahub.io resources in the
      rhoai-model-registries namespace. Returns 403 if permission is denied.
    get:
      tags:
        - ModelRegistry
      security:
        - Bearer: []
      responses:
        "200":
          $ref: "#/components/responses/ModelRegistriesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: getModelRegistries
      summary: List Model Registries
      description: >-
        Returns all ModelRegistry instances visible to the authenticated user.
        When no registries are installed the response is 200 with an empty list.

  /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:
            - 'storage': Filters for storage secrets (e.g., S3 secrets)
            - Omit for all secrets

            Type detection uses:
            1. The 'opendatahub.io/connection-type' annotation value if present
            2. Otherwise, key-based classification (case-sensitive, keys must be uppercase):
               - S3 requires: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_ENDPOINT
               - AWS_DEFAULT_REGION is optional for classification; validate it from the 'data' field when needed

            The 'data' field in the response contains all secret keys. Use it to validate additional requirements
            for your use case (e.g., checking for AWS_S3_BUCKET or AWS_DEFAULT_REGION). Allowed keys show actual values; others show "[REDACTED]".
          schema:
            type: string
            enum:
              - storage
          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 Detection:
        1. First checks for the 'opendatahub.io/connection-type' annotation. If present, its value is used as the type.
        2. Otherwise, performs key-based classification using required classification keys:
           - 's3': S3 storage secrets (classification keys: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_ENDPOINT; AWS_DEFAULT_REGION is optional)

        Type Filtering:
        - 'storage': Returns only secrets classified as storage types (currently: s3)
        - No type: Returns all secrets with their detected type classification

        Data Security:
        The 'data' field contains all secret keys with redacted or actual values:
        - Allowed keys (currently: AWS_S3_BUCKET) return actual values
        - All other keys return "[REDACTED]"
        Metadata:
        - 'displayName': Extracted from 'openshift.io/display-name' annotation if present
        - 'description': Extracted from 'openshift.io/description' annotation if present

  /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.
      GET returns an arbitrary file with transfer-encoding: chunked for efficient streaming.
      POST uploads a CSV file using multipart/form-data (part name `file`) and credentials
      from a required Kubernetes secret; the stored object key may differ from the requested
      `key` when a name collision is resolved (numeric suffix).
    get:
      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, connection details (endpoint, credential field names, region, bucket)
            are resolved from the DSPipelineApplication spec discovered in the namespace.
          schema:
            type: string
          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
          example: my-bucket
        - name: key
          in: path
          required: true
          description: The S3 object key to retrieve
          schema:
            type: string
            pattern: '^\S(.*\S)?$'
          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.

        **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
      security:
        - Bearer: []
      parameters:
        - name: namespace
          in: query
          required: true
          description: The Kubernetes namespace containing the secret
          schema:
            type: string
            maxLength: 63
            pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
          example: default
        - name: secretName
          in: query
          required: true
          description: >-
            Name of the Kubernetes secret containing S3 credentials (required for POST).
            The secret must provide AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION,
            and AWS_S3_ENDPOINT using those exact field names. Bucket may come from this secret
            (e.g. AWS_S3_BUCKET) when the bucket query parameter is omitted.
          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. When omitted, the bucket is resolved from the secret (e.g. AWS_S3_BUCKET).
            Leading and trailing whitespace is trimmed.
          schema:
            type: string
            pattern: '^\S(.*\S)?$'
          example: my-bucket
        - name: key
          in: path
          required: true
          description: >-
            Requested S3 object key for the upload. If an object already exists at this key,
            the server may store the file under a non-colliding key (e.g. `file-1.csv`); see the
            response body `key` field for the actual object key.
          schema:
            type: string
            pattern: '^\S(.*\S)?$'
          example: data/training.csv
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    CSV file to upload. Accepted as text/csv, or application/octet-stream / empty
                    Content-Type when the filename ends with .csv.
      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":
          $ref: "#/components/responses/PayloadTooLarge"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: uploadS3CsvFile
      summary: Upload CSV file to S3
      description: >-
        Uploads a CSV file to S3 using credentials from the specified Kubernetes secret.
        The request must be multipart/form-data with a part named `file`.

        Only CSV uploads are allowed: Content-Type `text/csv`, or `application/octet-stream` (or empty)
        when the part filename ends with `.csv`. The body is size-limited (declared Content-Length
        and total multipart size caps; file part max 32 MiB). Rejects with 413 when limits are exceeded.

        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/{key}/schema:
    summary: Endpoint to get the schema (column names and types) of a CSV file from an S3-compatible connection.
    description: >-
      The REST endpoint/path used to retrieve the schema of a CSV file from S3 storage.
      Reads the header and a minimum of 100 data rows to determine column names and infer data types.
      The inferred types are for UI display and schema preview purposes only and do not modify
      the underlying CSV data.


      Type Inference Priority (highest to lowest):

      1. bool - Accepts: true/false, t/f, yes/no, y/n, 1/0 (case-insensitive).
         NOTE: Numeric values "0" and "1" are classified as boolean for schema display. Columns
         containing only 0 and 1 values will show type "bool" rather than "integer". This is a
         display classification only - the underlying numeric data remains unchanged and ML
         processing is not affected. Binary features like is_premium: [0,1,0,1] will display as
         bool but retain numeric values.

      2. timestamp - Detects ISO8601, common date formats, and Unix timestamps in plausible ranges.

      3. integer - Whole numbers without decimal points. Note: columns with only 0/1 values are
         classified as bool (see above) for display purposes.

      4. double - Numeric values with decimal points or that don't fit integer/bool.

      5. string - Fallback for all other values.


      Integer is assumed before double - columns are typed as integer until a decimal is found.
      Uses proper CSV parsing to handle quoted values and different line endings (\n, \r\n, \r).
      Returns an error if the file has fewer than 100 data rows.
    get:
      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, connection details (endpoint, credential field names, region, bucket)
            are resolved from the DSPipelineApplication spec discovered in the namespace.
          schema:
            type: string
          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
          example: my-bucket
        - name: key
          in: path
          required: true
          description: The S3 object key (CSV file) to retrieve schema from
          schema:
            type: string
            pattern: '^\S(.*\S)?$'
          example: data/training.csv
      responses:
        "200":
          description: CSV schema retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      columns:
                        type: array
                        items:
                          type: object
                          required:
                            - name
                            - type
                          properties:
                            name:
                              type: string
                              description: Column name from the CSV header
                            type:
                              type: string
                              enum: [integer, double, timestamp, bool, string]
                              description: Inferred data type of the column
                            values:
                              type: array
                              description: For boolean columns, the unique values found in the data
                              items:
                                oneOf:
                                  - type: string
                                  - type: number
                                  - type: boolean
                        description: Array of column definitions with inferred types
                        example:
                          - name: "customerID"
                            type: "string"
                          - name: "gender"
                            type: "bool"
                            values: [0, 1]
                          - name: "age"
                            type: "integer"
                          - name: "price"
                            type: "double"
                          - name: "signup_date"
                            type: "timestamp"
                      parse_warnings:
                        type: integer
                        description: Number of rows that failed CSV parsing and were skipped during schema inference
                        example: 0
        "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: getS3FileSchema
      summary: Get CSV schema with inferred types from S3
      description: >-
        Retrieves the column names and inferred data types from a CSV file in S3 storage.
        Reads the header line plus a minimum of 100 data rows to accurately determine column types.

        Two credential resolution modes are supported (same as /api/v1/s3/file):

        **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.

        **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.


        Type Inference Priority (highest to lowest):

        1. bool - Matches: true/false, t/f, yes/no, y/n, 1/0 (case-insensitive).
           NOTE: "0" and "1" are treated as boolean values for UI display purposes. A column
           containing only 0 and 1 will be classified as bool, not integer. This classification
           is for schema display only and does not modify the underlying data or affect ML processing.
           Binary numeric features (e.g., is_premium: [0,1,0,1]) will display as bool type but
           retain their numeric values.

        2. timestamp - Recognizes ISO8601, common date formats, Unix epoch timestamps.

        3. integer - Whole numbers without decimals (excluding 0/1-only columns, which display as bool).

        4. double - Numbers with decimal points or outside integer range.

        5. string - Default fallback for all other values.


        Integer is assumed before double - columns with only whole numbers are typed as integer,
        but if any decimal value is found, the column becomes double.
        For boolean columns, returns the unique values found in the data.
        Supports all common line endings (\n, \r\n, \r) and properly handles quoted CSV fields.
        Returns a 400 Bad Request error if the file has fewer than 100 data rows.

  /api/v1/s3/files:
    summary: Endpoints for dealing with multiple files within 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"


  # =============================================================================
  # MODEL REGISTRY ENDPOINTS
  # =============================================================================

  /api/v1/model-registries/{registryId}/models:
    summary: Register a model in a specific Model Registry instance
    description: >-
      Registers a model binary by creating a RegisteredModel, ModelVersion, and
      ModelArtifact in the specified Model Registry instance. The model binary
      remains in S3; the ModelArtifact.uri points to the S3 location.
      The registryId path parameter is the Kubernetes UID of the ModelRegistry CR
      (from GET /api/v1/model-registries). The BFF resolves the server_url for that
      instance and POSTs to the Model Registry REST API.
      Returns 404 if the ID is unknown, 403 if the user cannot list ModelRegistries,
      and 503 if the registry exists but is not ready.
    post:
      tags:
        - ModelRegistry
      security:
        - Bearer: []
      parameters:
        - $ref: "#/components/parameters/namespace"
        - name: registryId
          in: path
          required: true
          schema:
            type: string
          description: Kubernetes UID of the target ModelRegistry CR (from GET /api/v1/model-registries id field)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterModelRequest"
      responses:
        "201":
          $ref: "#/components/responses/RegisterModelResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      operationId: registerModel
      summary: Register model binary
      description: >-
        Creates RegisteredModel, ModelVersion, and ModelArtifact in the Model Registry,
        linking the artifact to the provided S3 URI. Requires s3_path, model_name,
        and version_name in the request body.

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

  /api/v1/pipeline-runs:
    summary: Pipeline run operations
    description: >-
      Endpoints for listing pipeline runs from the Pipeline Server
      in the specified namespace. The Pipeline Server (DSPipelineApplication)
      and AutoML managed pipeline are automatically discovered.
    get:
      tags:
        - PipelineOperation
      security:
        - Bearer: []
      parameters:
        - $ref: "#/components/parameters/namespace"
        - $ref: "#/components/parameters/pageSize"
        - $ref: "#/components/parameters/page"
      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 merged pipeline runs from all auto-discovered AutoML pipelines (time-series
        and tabular). Runs are sorted by creation time descending and paginated using
        page/pageSize. Returns 500 if no managed AutoML pipelines are found in the namespace.
    post:
      tags:
        - PipelineOperation
      security:
        - Bearer: []
      parameters:
        - $ref: "#/components/parameters/namespace"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAutoMLRunRequest"
            examples:
              tabular-binary:
                summary: Tabular binary classification pipeline request
                value:
                  display_name: "Credit Risk Binary Classification"
                  description: "Binary classification for credit default prediction"
                  train_data_secret_name: "s3-credentials"
                  train_data_bucket_name: "ml-datasets"
                  train_data_file_key: "credit/train.csv"
                  label_column: "default"
                  task_type: "binary"
                  top_n: 5
              tabular-multiclass:
                summary: Tabular multiclass classification pipeline request
                value:
                  display_name: "Customer Segmentation"
                  description: "Multiclass classification for customer categorization"
                  train_data_secret_name: "s3-credentials"
                  train_data_bucket_name: "ml-datasets"
                  train_data_file_key: "customers/train.csv"
                  label_column: "segment"
                  task_type: "multiclass"
                  top_n: 5
              tabular-regression:
                summary: Tabular regression pipeline request
                value:
                  display_name: "House Price Prediction"
                  description: "Regression model for house price estimation"
                  train_data_secret_name: "s3-credentials"
                  train_data_bucket_name: "ml-datasets"
                  train_data_file_key: "housing/train.csv"
                  label_column: "price"
                  task_type: "regression"
                  top_n: 3
              timeseries:
                summary: Timeseries forecasting pipeline request
                value:
                  display_name: "Sales Forecasting"
                  description: "7-day ahead sales forecast by store"
                  train_data_secret_name: "s3-credentials"
                  train_data_bucket_name: "ml-datasets"
                  train_data_file_key: "sales/historical.csv"
                  task_type: "timeseries"
                  target: "sales"
                  id_column: "store_id"
                  timestamp_column: "date"
                  prediction_length: 7
                  known_covariates_names: ["temperature", "is_holiday"]
                  top_n: 3
      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 AutoML pipeline run using the auto-discovered pipeline for the
        requested task type. The task_type field in the request body determines which
        pipeline to use and must be provided.


        Request body schema requirements based on task_type:

        - task_type=binary/multiclass/regression: Requires CreateTabularRunRequest schema with fields:
          label_column (required), task_type (required, enum: binary/multiclass/regression)

        - task_type=timeseries: Requires CreateTimeSeriesRunRequest schema with fields:
          target (required), id_column (required), timestamp_column (required),
          task_type (required, must be "timeseries"),
          prediction_length (optional, default: 1), known_covariates_names (optional array)

  /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 AutoML managed pipeline are automatically discovered.
    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

  /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 one of the discovered AutoML pipelines 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 AutoML 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 one of the discovered AutoML
        managed pipelines 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 one of the discovered AutoML pipelines 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 AutoML pipeline run. The BFF validates that the run
        belongs to one of the discovered AutoML managed pipelines 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

    # Secret Schemas
    SecretTypeSchema:
      description: >-
        Schema defining the classification keys for a secret type.
        Type detection first checks the 'opendatahub.io/connection-type' annotation.
        If not present, classification keys are used to identify the secret type through key-based detection.
        Common optional keys are included in the 'data' field 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 via key-based detection (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.
            These appear in the 'data' field when present.

    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"]

    ModelRegistry:
      description: A Model Registry instance discovered from the cluster
      type: object
      required:
        - id
        - name
        - display_name
        - is_ready
        - server_url
      properties:
        id:
          type: string
          description: The Kubernetes UID of the ModelRegistry CR
          example: a1b2c3d4-e5f6-7890-abcd-111111111111
        name:
          type: string
          description: The ModelRegistry CR name (also the Kubernetes service name)
          example: default-modelregistry
        display_name:
          type: string
          description: Human-readable name from openshift.io/display-name annotation; falls back to name
          example: Default Model Registry
        description:
          type: string
          description: Optional description from openshift.io/description annotation
          example: Shared model registry for the organization
        is_ready:
          type: boolean
          description: Whether the ModelRegistry has an Available=True condition
          example: true
        server_url:
          type: string
          description: >-
            Full in-cluster REST API base URL for this registry, derived from
            status.hosts (set by the operator). Callers append resource paths
            (e.g. /registered_models) to this URL.
          example: "https://default-modelregistry.rhoai-model-registries.svc.cluster.local:8443/api/model_registry/v1beta1"
        external_url:
          type: string
          description: >-
            Public Route URL for the registry, present only when serviceRoute is enabled.
            Empty when no Route is configured.
          example: "https://default-modelregistry-rest.apps.cluster.example.com/api/model_registry/v1beta1"

    ModelRegistriesData:
      description: Wrapper for the model registries list response
      type: object
      required:
        - model_registries
      properties:
        model_registries:
          type: array
          description: List of available Model Registry instances
          items:
            $ref: "#/components/schemas/ModelRegistry"

    SecretListItem:
      description: A Kubernetes secret with its UUID, name, type classification, data keys with values/redaction, and metadata
      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)

            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: >-
            Map of all keys in the secret with their values. Security redaction applies:
            - Keys in the allowed list (currently: AWS_S3_BUCKET) return their actual values
            - All other keys return the value "[REDACTED]"
          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: Display name from the 'openshift.io/display-name' annotation (if present)
          example: "My AWS S3 Connection"
        description:
          type: string
          description: Description from the 'openshift.io/description' annotation (if present)
          example: "S3 bucket for training data storage"

    S3UploadSuccess:
      description: Response body for successful S3 file upload (POST /api/v1/s3/file)
      required:
        - uploaded
        - key
      type: object
      properties:
        uploaded:
          type: boolean
          example: true
        key:
          type: string
          description: >-
            S3 object key where the file was stored. May differ from the requested `key`
            when a collision was resolved (e.g. `data/file-1.csv` if `data/file.csv` existed).
          example: data/training.csv

    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


    # Pipeline Run Schemas
    CreateAutoMLRunRequestBase:
      type: object
      description: Base schema with common fields for all AutoML pipeline run types
      required:
        - display_name
        - train_data_secret_name
        - train_data_bucket_name
        - train_data_file_key
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 250
          description: Human-readable name for the run
          example: "AutoML Optimization Run 1"
        description:
          type: string
          description: Optional run description
          example: "Test optimization run"
        train_data_secret_name:
          type: string
          minLength: 1
          description: Name of the Kubernetes secret containing S3 credentials
          example: "minio-secret"
        train_data_bucket_name:
          type: string
          minLength: 1
          description: S3 bucket name containing the training data
          example: "automl-bucket"
        train_data_file_key:
          type: string
          minLength: 1
          description: S3 object key for the training data file
          example: "data/train.csv"
        top_n:
          type: integer
          minimum: 1
          description: Number of top models to consider (optional)
          example: 5

    CreateTabularRunRequest:
      allOf:
        - $ref: '#/components/schemas/CreateAutoMLRunRequestBase'
        - type: object
          description: Request body for creating a tabular AutoML pipeline run (binary, multiclass, or regression)
          required:
            - label_column
            - task_type
          properties:
            label_column:
              type: string
              minLength: 1
              description: Name of the target column in the training data
              example: "target"
            task_type:
              type: string
              minLength: 1
              enum:
                - binary
                - multiclass
                - regression
              description: Type of task (binary classification, multiclass classification, or regression)
              example: "binary"
          not:
            anyOf:
              - required: [target]
              - required: [id_column]
              - required: [timestamp_column]
              - required: [prediction_length]
              - required: [known_covariates_names]

    CreateTimeSeriesRunRequest:
      allOf:
        - $ref: '#/components/schemas/CreateAutoMLRunRequestBase'
        - type: object
          description: Request body for creating a timeseries AutoML pipeline run (forecasting)
          required:
            - target
            - id_column
            - timestamp_column
            - task_type
          properties:
            task_type:
              type: string
              enum:
                - timeseries
              description: Type of task - must be "timeseries" for time series forecasting
              example: "timeseries"
            target:
              type: string
              minLength: 1
              description: Name of the target column to forecast
              example: "sales"
            id_column:
              type: string
              minLength: 1
              description: Name of the column identifying each time series (item_id)
              example: "item_id"
            timestamp_column:
              type: string
              minLength: 1
              description: Name of the timestamp/datetime column
              example: "timestamp"
            prediction_length:
              type: integer
              minimum: 1
              description: Forecast horizon (number of timesteps)
              default: 1
              example: 7
            known_covariates_names:
              type: array
              items:
                type: string
              description: Optional list of known covariate column names
              example: ["temperature", "holiday"]
          not:
            required: [label_column]

    RegisterModelRequest:
      type: object
      description: >-
        Request body for registering a model binary in the Model Registry.
        The target registry is identified by the registryId path parameter.
      required:
        - s3_path
        - model_name
        - version_name
      properties:
        s3_path:
          type: string
          minLength: 1
          pattern: "^s3a?://[^/]+/.+"
          description: S3 URI where the model binary is stored (s3:// or s3a:// scheme required)
          example: "s3://my-bucket/models/v1/model.bin"
        model_name:
          type: string
          minLength: 1
          pattern: "\\S"
          description: Name of the registered model (must contain at least one non-whitespace character)
          example: "my-model"
        model_description:
          type: string
          description: Optional description of the model
        version_name:
          type: string
          minLength: 1
          pattern: "\\S"
          description: Name of the model version (must contain at least one non-whitespace character)
          example: "v1"
        version_description:
          type: string
          description: Optional description of this version
        artifact_name:
          type: string
          description: Name for the ModelArtifact; defaults to version_name if empty
        artifact_description:
          type: string
          description: Optional description of the artifact
        model_format_name:
          type: string
          description: Optional format (e.g., onnx, pytorch, tensorflow)
        model_format_version:
          type: string
          description: Optional format version (e.g., 1.0)

    ModelArtifact:
      type: object
      description: Model artifact created in the Model Registry, pointing to the S3 URI
      properties:
        id:
          type: string
          description: Unique identifier of the artifact
        name:
          type: string
          description: Artifact name
        uri:
          type: string
          description: S3 URI of the model binary
        artifactType:
          type: string
          description: Type of the artifact (e.g., model-artifact)

    CreateAutoMLRunRequest:
      description: >-
        Request body for creating an AutoML pipeline run. The schema varies based on the
        task_type field in the request body:
        - task_type=binary/multiclass/regression: Uses CreateTabularRunRequest schema for tabular tasks
        - task_type=timeseries: Uses CreateTimeSeriesRunRequest schema for forecasting tasks
      oneOf:
        - $ref: '#/components/schemas/CreateTabularRunRequest'
        - $ref: '#/components/schemas/CreateTimeSeriesRunRequest'
      discriminator:
        propertyName: task_type
        mapping:
          binary: '#/components/schemas/CreateTabularRunRequest'
          multiclass: '#/components/schemas/CreateTabularRunRequest'
          regression: '#/components/schemas/CreateTabularRunRequest'
          timeseries: '#/components/schemas/CreateTimeSeriesRunRequest'

    PipelineRun:
      type: object
      description: A Kubeflow Pipeline run
      required:
        - run_id
        - display_name
        - state
        - created_at
      properties:
        run_id:
          type: string
          description: Unique run identifier
          example: "run-abc123-def456"
        display_name:
          type: string
          description: Human-readable run name
          example: "AutoML Optimization Run 1"
        description:
          type: string
          description: Optional run description
          example: "Test optimization run"
        experiment_id:
          type: string
          description: ID of the experiment this run belongs to
          example: "exp-123"
        pipeline_version_reference:
          $ref: "#/components/schemas/PipelineVersionReference"
        state:
          type: string
          enum:
            - PENDING
            - RUNNING
            - SUCCEEDED
            - FAILED
            - CANCELED
            - PAUSED
            - CANCELING
          description: Current state of the pipeline run
          example: "SUCCEEDED"
        storage_state:
          type: string
          description: Storage state of the run
          example: "AVAILABLE"
        service_account:
          type: string
          description: Service account used by the run
          example: "pipeline-runner-dspa"
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the run was created
          example: "2026-02-24T10:30:00Z"
        scheduled_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the run was scheduled
          example: "2026-02-24T10:30:00Z"
        finished_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the run finished
          example: "2026-02-24T11:15:00Z"
        state_history:
          type: array
          description: History of state transitions
          items:
            $ref: "#/components/schemas/RuntimeStatus"
        error:
          $ref: "#/components/schemas/ErrorInfo"
        run_details:
          $ref: "#/components/schemas/RunDetails"
        pipeline_type:
          type: string
          enum:
            - timeseries
            - tabular
          description: >-
            Type of the AutoML pipeline that produced this run. Identifies whether
            this is a time-series or tabular (binary/multiclass/regression) pipeline run.
          example: "timeseries"

    PipelineVersionReference:
      type: object
      description: Reference to a pipeline 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: "22e57c06-030f-4c63-900d-0a808d577899"

    RuntimeStatus:
      type: object
      description: Runtime status entry in state history
      properties:
        update_time:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the status update
          example: "2026-02-24T10:30:00Z"
        state:
          type: string
          description: State at this point in history
          example: "RUNNING"
        error:
          $ref: "#/components/schemas/ErrorInfo"

    ErrorInfo:
      type: object
      description: Error information for failed runs or tasks
      properties:
        code:
          type: integer
          description: Error code
          example: 500
        message:
          type: string
          description: Error message
          example: "Pipeline execution failed: unable to connect to data source"

    RunDetails:
      type: object
      description: Detailed information about a run's execution
      properties:
        task_details:
          type: array
          description: Details of individual tasks in the run
          items:
            $ref: "#/components/schemas/TaskDetail"

    TaskDetail:
      type: object
      description: Details of a single task within a pipeline run
      required:
        - task_id
      properties:
        run_id:
          type: string
          description: ID of the parent run
          example: "run-abc123-def456"
        task_id:
          type: string
          description: Unique task identifier
          example: "task-data-preprocessing"
        display_name:
          type: string
          description: Human-readable task name
          example: "Data Preprocessing"
        create_time:
          type: string
          format: date-time
          description: ISO 8601 timestamp of task creation
          example: "2026-02-24T10:30:00Z"
        start_time:
          type: string
          format: date-time
          description: ISO 8601 timestamp of task start
          example: "2026-02-24T10:30:05Z"
        end_time:
          type: string
          format: date-time
          description: ISO 8601 timestamp of task completion
          example: "2026-02-24T10:35:00Z"
        state:
          type: string
          description: Current state of the task
          example: "SUCCEEDED"
        error:
          $ref: "#/components/schemas/ErrorInfo"
        state_history:
          type: array
          description: History of state transitions for this task
          items:
            $ref: "#/components/schemas/RuntimeStatus"
        child_tasks:
          type: array
          description: Child tasks or pods
          items:
            $ref: "#/components/schemas/ChildTask"

    ChildTask:
      type: object
      description: Child task or pod reference
      properties:
        pod_name:
          type: string
          description: Name of the pod executing the task
          example: "data-preprocessing-pod-abc123"

    PipelineRunsData:
      type: object
      description: Container for pipeline runs list response data
      required:
        - runs
        - total_size
      properties:
        runs:
          type: array
          description: List of pipeline runs
          items:
            $ref: "#/components/schemas/PipelineRun"
        total_size:
          type: integer
          description: Total number of runs across all discovered pipelines
          example: 10

  parameters:
    namespace:
      name: namespace
      in: query
      required: true
      schema:
        type: string
      description: Kubernetes namespace
      example: "default"
    pageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
      description: Number of items to return per page
      example: 20
    page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
      description: Page number to retrieve, 1-indexed (default 1)
      example: 1

  responses:
    ModelRegistriesResponse:
      description: Successful response containing available Model Registry instances
      content:
        application/json:
          schema:
            type: object
            required:
              - data
            properties:
              data:
                $ref: "#/components/schemas/ModelRegistriesData"

    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"
      description: A response containing a list of filtered secret items

    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "403"
                  message:
                    type: string
                    example: "Forbidden"

    ConfigResponse:
      description: User configuration response
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                type: object
                description: Response metadata
              data:
                $ref: "#/components/schemas/Config"

    PipelineRunsResponse:
      description: List of pipeline runs
      content:
        application/json:
          schema:
            type: object
            required:
              - data
            properties:
              metadata:
                type: object
                description: Response metadata
              data:
                $ref: "#/components/schemas/PipelineRunsData"

    PipelineRunResponse:
      description: Single pipeline run
      content:
        application/json:
          schema:
            type: object
            required:
              - data
            properties:
              metadata:
                type: object
                description: Response metadata
              data:
                $ref: "#/components/schemas/PipelineRun"

    CreatePipelineRunResponse:
      description: Created pipeline run
      content:
        application/json:
          schema:
            type: object
            required:
              - data
            properties:
              metadata:
                type: object
                description: Response metadata
              data:
                $ref: "#/components/schemas/PipelineRun"

    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"

    RegisterModelResponse:
      description: Registered model artifact
      content:
        application/json:
          schema:
            type: object
            required:
              - data
            properties:
              metadata:
                type: object
                description: Response metadata
              data:
                $ref: "#/components/schemas/ModelArtifact"

    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "400"
                  message:
                    type: string
                    example: "Invalid request parameters"

    PayloadTooLarge:
      description: Request entity too large (e.g. declared Content-Length or file part exceeds limit)
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "413"
                  message:
                    type: string
                    example: "request body exceeds maximum upload size (32 MiB plus allowance for multipart framing)"

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "401"
                  message:
                    type: string
                    example: "Authentication required"

    NotFound:
      description: Resource Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "404"
                  message:
                    type: string
                    example: "Resource not found"

    Conflict:
      description: >-
        Conflict (e.g. S3 conditional upload failed because the object already exists at the
        resolved key, or duplicate model name in the registry; client may retry the request)
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "409"
                  message:
                    type: string
                    example: "object key \"data/file.csv\" already exists in S3 (upload conflict); retry with a different key"

    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "500"
                  message:
                    type: string
                    example: "Internal server error"

    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "503"
                  message:
                    type: string
                    example: "Service temporarily unavailable"

  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT bearer token authentication