Unity Catalog Model Versions API

openapi: 3.2.0
info:
  title: Unity Catalog Model Versions API
  version: '0.1'
  description: 'Model versions contain all artifact files associated with an individual machine learning model. They are associated with a single parent model and have an integer identifier, indicating the version number of the model.

    Model versions are referenced via model URI''s using the Unity Catalog three-level namespace of the registered model and the version identifier.'
servers:
- url: http://localhost:8080/api/2.1/unity-catalog
  description: Localhost reference server
tags:
- name: Model Versions
  description: 'Model versions contain all artifact files associated with an individual machine learning model. They are associated with a single parent model and have an integer identifier, indicating the version number of the model.

    Model versions are referenced via model URI''s using the Unity Catalog three-level namespace of the registered model and the version identifier.'
paths:
  /models/versions:
    post:
      operationId: createModelVersion
      summary: Create a model version
      tags:
      - Model Versions
      description: Creates a new model version instance.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelVersion'
      responses:
        '200':
          description: The new model version was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelVersionInfo'
  /models/{full_name}/versions:
    parameters:
    - name: full_name
      in: path
      description: Full name of the registered model.
      required: true
      schema:
        type: string
    - name: max_results
      in: query
      description: 'Maximum number of model versions to return.

        - when set to a value greater than 0, the page length is the minimum of this value and a server configured value;

        - when set to 0, the page length is set to a server configured value;

        - when set to a value less than 0, an invalid parameter error is returned;

        '
      required: false
      schema:
        type: integer
        format: int32
        maximum: 50
    - name: page_token
      in: query
      description: Opaque token to send for the next page of results (pagination).
      required: false
      schema:
        type: string
    get:
      tags:
      - Model Versions
      operationId: listModelVersions
      summary: List model versions of the specified registered model
      description: 'Gets the paginated list of all available model versions under the specified registered model.

        There is no guarantee of a specific ordering of the elements in the array.'
      responses:
        '200':
          description: The model versions list was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelVersionsResponse'
  /models/{full_name}/versions/{version}:
    parameters:
    - name: full_name
      in: path
      description: Full name of the model.
      required: true
      schema:
        type: string
    - name: version
      in: path
      description: Version number of the model version.
      required: true
      schema:
        type: integer
        format: int64
    get:
      tags:
      - Model Versions
      operationId: getModelVersion
      summary: Get a model version
      description: Gets a specific model version for a specific model.
      responses:
        '200':
          description: The model version was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelVersionInfo'
    patch:
      tags:
      - Model Versions
      operationId: updateModelVersion
      summary: Update a model version
      description: Updates the specified model version.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateModelVersion'
      responses:
        '200':
          description: The model version was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelVersionInfo'
    delete:
      tags:
      - Model Versions
      operationId: deleteModelVersion
      summary: Delete a model version
      description: Deletes the specified model version.
      responses:
        '200':
          description: The model version was successfully deleted.
          content:
            application/json:
              schema: {}
  /models/{full_name}/versions/{version}/finalize:
    parameters:
    - name: full_name
      in: path
      description: Full name of the model.
      required: true
      schema:
        type: string
    - name: version
      in: path
      description: Version number of the model version.
      required: true
      schema:
        type: integer
        format: int64
    patch:
      tags:
      - Model Versions
      operationId: finalizeModelVersion
      summary: Finalize a model version
      description: Finalizes the status of the specified model version.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinalizeModelVersion'
      responses:
        '200':
          description: The model version was successfully finalized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelVersionInfo'
components:
  schemas:
    FinalizeModelVersion:
      type: object
      properties:
        full_name:
          description: The full name of the registered model to finalize.
          type: string
        version:
          description: Version number of the version to finalize.
          type: integer
          format: int64
      required:
      - full_name
      - version
    ListModelVersionsResponse:
      type: object
      properties:
        model_versions:
          description: An array of model version information objects.
          type: array
          items:
            $ref: '#/components/schemas/ModelVersionInfo'
        next_page_token:
          type: string
          description: 'Opaque token to retrieve the next page of results. Absent if there are no more pages.

            __page_token__ should be set to this value for the next request (for the next page of results).

            '
    ModelVersionInfo:
      type: object
      properties:
        model_name:
          description: The name of the parent registered model of the model version, relative to parent schema
          type: string
        catalog_name:
          description: The name of the catalog containing the model version
          type: string
        schema_name:
          description: The name of the schema containing the model version, relative to parent catalog
          type: string
        version:
          description: Integer model version number, used to reference the model version in API requests.
          type: integer
          format: int64
        source:
          description: URI indicating the location of the source artifacts (files) for the model version
          type: string
        run_id:
          description: The run id used by the ML package that generated the model.
          type: string
        status:
          $ref: '#/components/schemas/ModelVersionStatus'
        storage_location:
          description: The storage location on the cloud under which model version data files are stored
          type: string
        comment:
          description: The comment attached to the model version
          type: string
        created_at:
          description: Time at which this model version was created, in epoch milliseconds.
          type: integer
          format: int64
        created_by:
          description: The identifier of the user who created the model version
          type: string
        updated_at:
          description: Time at which this model version was last modified, in epoch milliseconds.
          type: integer
          format: int64
        updated_by:
          description: The identifier of the user who updated the model version last time
          type: string
        id:
          description: Unique identifier for the model version.
          type: string
    CreateModelVersion:
      type: object
      properties:
        model_name:
          description: Name of registered model, relative to parent schema.
          type: string
        catalog_name:
          description: Name of parent catalog.
          type: string
        schema_name:
          description: Name of parent schema relative to its parent catalog.
          type: string
        source:
          description: URI indicating the location of the source model artifacts.
          type: string
        run_id:
          description: The run id used by the ML package that generated the model.
          type: string
        comment:
          description: User-provided free-form text description.
          type: string
      required:
      - model_name
      - catalog_name
      - schema_name
      - source
    ModelVersionStatus:
      description: All possible model version statuses.
      type: string
      enum:
      - MODEL_VERSION_STATUS_UNKNOWN
      - PENDING_REGISTRATION
      - FAILED_REGISTRATION
      - READY
      x-enum-descriptions:
      - 'MODEL_VERSION_STATUS_UNKNOWN: Unknown'
      - 'PENDING_REGISTRATION: Indicates that the client has not completely written all model artifacts to external storage.'
      - 'FAILED_REGISTRATION: Indicates that the client has failed to write all model artifacts to external storage.'
      - 'READY: Indicates that the client has successfully written all model artifacts to external storage.'
    UpdateModelVersion:
      type: object
      properties:
        comment:
          description: User-provided free-form text description.
          type: string