Antfly Ml API

openapi: 3.2.0
info:
  title: Antfly Public Ml API
  version: v1alpha1
  description: Joined public contract for the Antfly server. Antfly APIs are served under `/db/v1`, auth APIs under `/auth/v1`, inference APIs under `/ai/v1`, ML prediction APIs under `/ml/v1`, and extension lifecycle APIs under `/extensions/v1`.
servers:
- url: /
security:
- BasicAuth: []
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Ml
paths:
  /ml/v1/models:
    get:
      summary: List Traditional ML predictors
      description: 'Returns the Traditional ML predictor catalog for `/ml/v1/predict`.

        Predictors are loaded from `//` and exposed separately

        from the AI model catalog.'
      operationId: listPredictors
      responses:
        '200':
          description: Predictors retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferencePredictorsResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
      tags:
      - Ml
  /ml/v1/predict:
    post:
      summary: Run a traditional ML predictor
      description: 'Run a tabular predictor (tree ensemble, linear, or SVM) on a batch of

        feature vectors. Models are loaded from `//` and

        identified by name. Use `/ml/v1/models` for the list of available

        predictors and their feature schemas.'
      operationId: predict
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InferencePredictRequest'
      responses:
        '200':
          description: Predictions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferencePredictResponse'
        '400':
          description: Invalid request (malformed body, feature-count mismatch)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '404':
          description: Predictor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '413':
          description: Batch too large (> 10000 rows)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
      tags:
      - Ml
  /ml/v1/predictors:
    get:
      operationId: listGatewayPredictors
      summary: List predictor feature schemas through the gateway
      responses:
        '200':
          description: Predictor schemas keyed by callable model ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferencePredictorsResponse'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
      tags:
      - Ml
components:
  schemas:
    InferencePredictorInfo:
      type: object
      description: Traditional ML predictor metadata.
      required:
      - task
      - num_features
      - num_outputs
      properties:
        task:
          $ref: '#/components/schemas/InferencePredictorTask'
        num_features:
          type: integer
          minimum: 1
          description: Number of feature columns expected by the predictor.
        num_outputs:
          type: integer
          minimum: 1
          description: Number of output values emitted per input row.
        feature_names:
          type: array
          description: Optional feature names in input order.
          items:
            type: string
        source_framework:
          type: string
          description: Source framework used to produce the predictor IR.
    InferencePredictResponse:
      type: object
      required:
      - model
      - task
      - predictions
      properties:
        model:
          type: string
        task:
          $ref: '#/components/schemas/InferencePredictorTask'
        predictions:
          type: array
          description: 'Per-row prediction arrays. Length equals the model''s `num_outputs`

            (1 for regression / binary, `num_classes` for multiclass).

            '
          items:
            type: array
            items:
              type: number
              format: float
    InferencePredictRequest:
      type: object
      required:
      - model
      - input
      properties:
        model:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[A-Za-z0-9_-]+$
          description: Predictor name from the model catalog.
        input:
          type: array
          maxItems: 10000
          description: Batch of feature vectors. Max 10000 rows.
          items:
            type: array
            items:
              type: number
              format: float
    InferenceError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Stable machine-readable error code
        message:
          type: string
          description: Human-readable error description
        reason:
          type: string
          description: Machine-readable capacity source when the failure is retryable
          enum:
          - inference_capacity
          - inference_admission
        retryable:
          type: boolean
          x-go-type-skip-optional-pointer: false
          description: Whether retrying the request may succeed
        retry_after_ms:
          type: integer
          minimum: 0
          description: Minimum retry delay in milliseconds
        input_index:
          type: integer
          minimum: 0
          x-go-type-skip-optional-pointer: false
          description: Input whose atomic extraction validation or decoding failed, when known
        stage:
          type: string
          description: Extraction failure stage, when known
    InferencePredictorsResponse:
      type: object
      required:
      - object
      - predictors
      properties:
        public_inference_enabled:
          x-go-type-skip-optional-pointer: false
          type: boolean
          description: Whether public inference execution is enabled on this deployment.
        object:
          type: string
          enum:
          - list
          description: Response object type.
        predictors:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/InferencePredictorInfo'
          description: Traditional ML predictors keyed by predictor name.
    InferencePredictorTask:
      type: string
      description: Task type for tabular predictors.
      enum:
      - regression
      - binary_classification
      - multiclass
      - ranking
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: Antfly
  tags:
  - cluster_management
  - table_management
  - data_operations
  - query_operations
  - index_management
- name: Auth
  tags:
  - User
  - Permission
  - ApiKey
  - RowFilter
- name: Inference
  tags: []
- name: Extensions
  tags:
  - Packages
  - Installed