openapi: 3.0.3
info:
  title: Waylay Byoml
  version: 1.5.1
  description: "This service deploys and executes Machine Learning models.\n\nPreferably\
    \ use the [Python SDK](http://docs.waylay.io/#/api/sdk/python?id=byoml-api) \n\
    to create and upload models. \nThis SDK provides additional tools to correctly\
    \ serialize\nand upload models, and handles timeouts, errors and retries."
externalDocs:
  url: /#/features/byoml/
  description: Waylay Documentation
tags:
- name: Model
  description: Provisioning of BYOML models.
  externalDocs:
    url: /#/api/byoml/?id=model-provisioning
    description: Waylay API Docs
- name: Model Invocation
  description: Send data to a model to execute it.
  externalDocs:
    url: /#/api/byoml/?id=model-execution
    description: Waylay API Docs
- name: Model runtimes
  description: Overview of the supported model runtimes.
  externalDocs:
    url: /#/api/byoml/?id=supported-model-runtimes
    description: Waylay API Docs
paths:
  /ml/v1/models:
    get:
      summary: List Models
      description: Get a list of the available models.
      parameters:
      - $ref: '#/components/parameters/modelFilter'
      tags:
      - Model
      responses:
        '200':
          $ref: '#/components/responses/ListModelResponse'
      x-permissions:
      - byoml:all:read
      operationId: get_ml_v1_models
      security: &id001
      - waylayApiKeySecret: []
    post:
      summary: Create Model
      description: Upload a model archive.
      tags:
      - Model
      externalDocs:
        url: /#/api/byoml/?id=upload-a-model
        description: Waylay Docs
      requestBody:
        $ref: '#/components/requestBodies/UploadModelSpecification'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/CreateModelResponse'
      x-permissions:
      - byoml:all:create
      operationId: post_ml_v1_models
      security: *id001
  /ml/v1/models/{modelName}:
    get:
      summary: Get Model
      description: 'Get information about the model.

        Note that this call will try to fetch the deployment status of the model.

        If this fails or times out (2 seconds), a `ready: false` will be included.'
      tags:
      - Model
      parameters:
      - $ref: '#/components/parameters/modelName'
      responses:
        '200':
          $ref: '#/components/responses/GetModelResponse'
      operationId: get_ml_v1_models_modelName
      security: *id001
    put:
      summary: Replace Model
      description: Create a new model version by uploading a model archive.
      tags:
      - Model
      parameters:
      - $ref: '#/components/parameters/modelName'
      requestBody:
        $ref: '#/components/requestBodies/UploadModelSpecification'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/CreateModelResponse'
      operationId: put_ml_v1_models_modelName
      security: *id001
    patch:
      summary: Update Model
      description: Update the model metadata without modifying the model.
      tags:
      - Model
      parameters:
      - $ref: '#/components/parameters/modelName'
      requestBody:
        $ref: '#/components/requestBodies/PatchModelRequest'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/CreateModelResponse'
      operationId: patch_ml_v1_models_modelName
      security: *id001
    delete:
      summary: Delete Model
      description: Delete a model.
      tags:
      - Model
      parameters:
      - $ref: '#/components/parameters/modelName'
      responses:
        '200':
          $ref: '#/components/responses/DeleteModelResponse'
      operationId: delete_ml_v1_models_modelName
      security: *id001
  /ml/v1/models/{modelName}/predict:
    post:
      summary: Predict
      description: Send data and get predictions from the model.
      tags:
      - Model Invocation
      parameters:
      - $ref: '#/components/parameters/modelName'
      requestBody:
        $ref: '#/components/requestBodies/InstanceData'
      responses:
        '200':
          $ref: '#/components/responses/PredictResponse'
      operationId: post_ml_v1_models_modelName_predict
      security: *id001
  /ml/v1/models/{modelName}/classify:
    post:
      summary: Classify (Tensorflow)
      description: Send data to get classifications from the model (only for TensorFlow
        models).
      tags:
      - Model Invocation
      parameters:
      - $ref: '#/components/parameters/modelName'
      requestBody:
        $ref: '#/components/requestBodies/InstanceData'
      responses:
        '200':
          $ref: '#/components/responses/ClassifyResponse'
      operationId: post_ml_v1_models_modelName_classify
      security: *id001
  /ml/v1/models/{modelName}/regress:
    post:
      summary: Regress (Tensorflow)
      description: Get regressions from the model (only for TensorFlow models).
      tags:
      - Model Invocation
      parameters:
      - $ref: '#/components/parameters/modelName'
      requestBody:
        $ref: '#/components/requestBodies/InstanceData'
      responses:
        '200':
          $ref: '#/components/responses/RegressResponse'
      operationId: post_ml_v1_models_modelName_regress
      security: *id001
  /ml/v1/runtimes:
    get:
      summary: List Runtimes
      description: List supported runtimes.
      tags:
      - Model runtimes
      responses:
        '200':
          $ref: '#/components/responses/DefaultSuccessResponse'
      operationId: get_ml_v1_runtimes
      security: *id001
  /ml/v1/runtimes/{runtime}:
    get:
      summary: Get Runtime
      description: Get named runtime description.
      tags:
      - Model runtimes
      parameters:
      - name: runtime
        in: path
        description: runtime name
        schema:
          type: string
        required: true
      responses:
        '200':
          $ref: '#/components/responses/DefaultSuccessResponse'
      operationId: get_ml_v1_runtimes_runtime
      security: *id001
  /ml/v1/frameworks:
    get:
      summary: List Frameworks
      description: List supported frameworks and framework versions.
      tags:
      - Model runtimes
      responses:
        '200':
          $ref: '#/components/responses/DefaultSuccessResponse'
      operationId: get_ml_v1_frameworks
      security: *id001
  /ml/v1/frameworks/{framework}:
    get:
      summary: Get Framework
      description: Get supported versions and default runtime for the named framework.
      tags:
      - Model runtimes
      parameters:
      - $ref: '#/components/parameters/modelFramework'
      responses:
        '200':
          $ref: '#/components/responses/DefaultSuccessResponse'
      operationId: get_ml_v1_frameworks_framework
      security: *id001
  /ml/v1/frameworks/{framework}/versions:
    get:
      summary: List Framwork Runtimes
      description: Get the supported runtimes for the named framework.
      tags:
      - Model runtimes
      parameters:
      - $ref: '#/components/parameters/modelFramework'
      responses:
        '200':
          $ref: '#/components/responses/DefaultSuccessResponse'
      operationId: get_ml_v1_frameworks_framework_versions
      security: *id001
  /ml/v1/frameworks/{framework}/versions/{frameworkVersion}/content:
    get:
      summary: Get Framework Runtime
      description: Get the runtime for a framework version.
      tags:
      - Model runtimes
      parameters:
      - $ref: '#/components/parameters/modelFramework'
      - $ref: '#/components/parameters/frameworkVersion'
      responses:
        '200':
          $ref: '#/components/responses/DefaultSuccessResponse'
      operationId: get_ml_v1_frameworks_framework_versions_frameworkVersion_content
      security: *id001
  /ml/v1/:
    get:
      summary: Get Service Status
      tags:
      - About
      description: Get the status and version of the service.
      responses:
        '200':
          $ref: '#/components/responses/VersionResponse'
      operationId: get_ml_v1
      security: *id001
components:
  schemas:
    VersionResponse:
      type: object
      properties:
        version:
          type: string
          example: 1.5.1
    ModelListing:
      type: array
      items:
        $ref: '#/components/schemas/ModelSummary'
    ModelSummary:
      type: object
      properties:
        name:
          type: string
        framework:
          type: string
        framework_version:
          type: string
        metadata:
          $ref: '#/components/schemas/ModelMetaData'
        version:
          type: string
        updatedBy:
          type: string
        updatedOn:
          type: string
          format: date-time
        createdBy:
          type: string
        createdOn:
          type: string
          format: date-time
      example:
        name: tst-807-654-custom-sarima
        framework: custom
        framework_version: '1.0'
        metadata:
          description: integration test_story_byoml
        version: '1'
        createdBy: users/0476f99d-ac60-4f86-bc45-7215962754cd
        createdOn: '2022-09-02T11:26:01.512000+00:00'
        updatedBy: users/0476f99d-ac60-4f86-bc45-7215962754cd
        updatedOn: '2022-09-02T11:26:22.590000+00:00'
    ModelWithReadiness:
      type: object
      allOf:
      - $ref: '#/components/schemas/ModelSummary'
      - $ref: '#/components/schemas/ModelReadiness'
    ModelReadiness:
      type: object
      properties:
        ready:
          description: "If `False` the model is not yet active. Either deployment\
            \ has failed, \ndeployment is still busy, or the model is restarting after\
            \ a period \nof inactivity."
          type: boolean
    ModelMetaData:
      type: object
      description: User provided metadata for the model.
      properties:
        description:
          type: string
        title:
          type: string
        author:
          type: string
    DeletionResponse:
      type: object
      properties:
        message:
          type: string
        name:
          type: string
        versions:
          type: array
          items:
            type: string
      example:
        message: 'Model xgboost-example: all versions deleted'
        name: xgboost-example
        versions:
        - 0.0.1
    ModelFilterParams:
      description: Query filter parameters for the model.
      type: object
      properties:
        name:
          description: 'Filter on a model name.

            Supports `*` and `?` wild cards and is case-insensitive.'
          type: string
        version:
          description: Filter on a specific model revision.
          type: integer
      example:
        name: '*demo*'
        version: 2
    InstanceData:
      title: Instance Data
      description: 'Array of observations that are used to infer the model.

        In most cases this is two-dimensional (array-of-arrays).

        The first dimension loops over instances (e.g. over time),

        the second dimension shows the numeric features of each observation.


        Some models might support alternate representation of tensor data.'
      type: object
      properties:
        instances:
          type: array
          items:
            type: array
            items:
              type: number
      required:
      - instances
    PredictResponse:
      title: Predict Response
      type: object
    ClassifyResponse:
      title: Classify Response
      type: object
    RegressResponse:
      title: Regress Response
      type: object
  requestBodies:
    PatchModelRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                $ref: '#/components/schemas/ModelMetaData'
    InstanceData:
      description: 'Array of observations that are used in the model inference.

        In most cases this is a two-dimensional json array (array-of-arrays).

        The first dimension loops over instances or time,

        the second dimension shows the (numeric) features of each observation.


        Some models might support alternate representations of input data.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceData'
    UploadModelSpecification:
      description: "To upload a model using the REST API, prepare a `tar` archive,\
        \ with the following content:\n- `<model.json>` A json file that describes\
        \ your model.\n- `models/<model_file>` The serialized model file. See [serialization](http://docs.waylay.io/#/api/byoml/?id=model-serialization)\
        \ for the supported serialization methods.\n- `requirements.txt` a pip requirements\
        \ file containing addtional custom dependencies for your (python) model.\n\
        \  Leave the file empty when no additional dependencies are needed.\n- `lib`\
        \ a folder, optionally containing python packages to be installed with the\
        \ model.\n  Leave empty when no dependencies are required.\"<br>\n  The `model.json`\
        \ file should contain the name, runtime, and optionally a description:\n```\n\
        \  {\n    \"name\": \"my-byoml-model\",\n    \"runtime\": \"byoml-tensorflow-2.4\"\
        ,\n    \"metadata\" : {\n      \"description\": \"An example tensorflow model\"\
        \n    }\n```\n"
      content:
        application/x-tar:
          schema:
            type: string
            format: binary
        multipart/form-data:
          x-visibility:
            status: deprecated
            description: This upload method is deprecated since byoml v.1.4.
          schema:
            type: object
            properties:
              file:
                title: Model zip archive
                description: a zip archive containing the model file
                type: string
                format: binary
              name:
                title: model name
                type: string
                description: the unique name of the model (only lowercase, numbers
                  and hyphens)
              framework:
                title: model framework
                type: string
                description: the framework for the model runtime
                example: tensorflow
              description:
                title: model description
                type: string
                description: an optional description of which inputs the model expects
                  and which outputs it gives
              framework_version:
                title: framework version
                type: string
                description: the framework version for the model runtime
              runtime:
                title: runtime name
                type: string
                description: the exact runtime name for your model
                example: byoml-tensorflow-2.4
            required:
            - file
            - name
            - framework
          encoding:
            file:
              contentType: application/zip
  parameters:
    modelName:
      name: modelName
      in: path
      description: unique model name
      required: true
      schema:
        type: string
    modelFramework:
      name: framework
      in: path
      required: true
      description: framework name
      schema:
        type: string
    frameworkVersion:
      name: frameworkVersion
      in: path
      required: true
      description: framework version
      schema:
        type: string
    modelFilter:
      name: modelFilter
      in: query
      required: false
      description: Search filter for listing models.
      style: form
      explode: true
      schema:
        $ref: '#/components/schemas/ModelFilterParams'
  responses:
    DefaultSuccessResponse:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
    ListModelResponse:
      description: Model Listing
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ModelListing'
    CreateModelResponse:
      description: Model Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ModelSummary'
    GetModelResponse:
      description: Model Retrieved
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ModelWithReadiness'
    DeleteModelResponse:
      description: Model Deleted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeletionResponse'
    PredictResponse:
      description: Predicted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PredictResponse'
    ClassifyResponse:
      description: Classified
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClassifyResponse'
    RegressResponse:
      description: Regressed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RegressResponse'
    VersionResponse:
      description: Successful Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VersionResponse'
  securitySchemes:
    waylayApiKeySecret:
      type: http
      description: Waylay apiKey/apiSecret basic authentication. All endpoints support
        also Waylay JWT Bearer authentication.
      scheme: basic
servers:
- url: https://api.waylay.io
  description: Waylay enterprise gateway
