Scalable Inference Serving Models API

openapi: 3.2.0
info:
  title: KServe Open Inference Protocol Models API
  description: The Open Inference Protocol (OIP), also known as the KServe V2 Inference Protocol, provides a standardized REST interface for model inference across ML serving frameworks.
  version: v2
  contact:
    name: KServe Community
    url: https://github.com/kserve/kserve
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  externalDocs:
    description: KServe Open Inference Protocol Documentation
    url: https://kserve.github.io/website/docs/concepts/architecture/data-plane/v2-protocol
servers:
- url: https://inference.kserve.example.com
  description: KServe InferenceService endpoint
tags:
- name: Models
  description: Model management and metadata operations
paths:
  /v2/models/{model_name}/ready:
    get:
      operationId: CheckModelReadiness
      summary: Check Model Readiness
      description: The model readiness API indicates if a specific model is ready for inferencing. Check this before submitting inference requests to a newly deployed model.
      tags:
      - Models
      parameters:
      - name: model_name
        in: path
        required: true
        description: Name of the model to check readiness for.
        schema:
          type: string
        example: bert-sentiment-classifier
      responses:
        '200':
          description: Model is ready for inference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelReadyResponse'
              example:
                name: bert-sentiment-classifier
                ready: true
        '404':
          description: Model not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Model not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/models/{model_name}/versions/{model_version}/ready:
    get:
      operationId: CheckModelVersionReadiness
      summary: Check Model Version Readiness
      description: Check if a specific version of a model is ready for inference.
      tags:
      - Models
      parameters:
      - name: model_name
        in: path
        required: true
        schema:
          type: string
        example: bert-sentiment-classifier
      - name: model_version
        in: path
        required: true
        schema:
          type: string
        example: '2'
      responses:
        '200':
          description: Model version is ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelReadyResponse'
        '404':
          description: Model version not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/models/{model_name}:
    get:
      operationId: GetModelMetadata
      summary: Get Model Metadata
      description: Returns metadata about a model, including its name, versions, platform, inputs, and outputs. Use this to discover the input/output tensor shapes and data types before submitting inference requests.
      tags:
      - Models
      parameters:
      - name: model_name
        in: path
        required: true
        description: Name of the model.
        schema:
          type: string
        example: resnet50-image-classifier
      responses:
        '200':
          description: Model metadata returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelMetadataResponse'
              example:
                name: resnet50-image-classifier
                versions:
                - '1'
                - '2'
                platform: tensorflow_savedmodel
                inputs:
                - name: input_image
                  datatype: FP32
                  shape:
                  - -1
                  - 224
                  - 224
                  - 3
                outputs:
                - name: class_probabilities
                  datatype: FP32
                  shape:
                  - -1
                  - 1000
        '404':
          description: Model not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/models/{model_name}/versions/{model_version}:
    get:
      operationId: GetModelVersionMetadata
      summary: Get Model Version Metadata
      description: Returns metadata for a specific version of a model.
      tags:
      - Models
      parameters:
      - name: model_name
        in: path
        required: true
        schema:
          type: string
        example: resnet50-image-classifier
      - name: model_version
        in: path
        required: true
        schema:
          type: string
        example: '2'
      responses:
        '200':
          description: Model version metadata returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelMetadataResponse'
        '404':
          description: Model version not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ModelReadyResponse:
      type: object
      description: Response from the model readiness endpoint.
      required:
      - name
      - ready
      properties:
        name:
          type: string
          description: Name of the model.
        ready:
          type: boolean
          description: Indicates if the model is ready for inference.
    ModelMetadataResponse:
      type: object
      description: Metadata about a model, including its versions, platform, and input/output tensor specifications.
      required:
      - name
      - platform
      - inputs
      - outputs
      properties:
        name:
          type: string
          description: Model name.
        versions:
          type: array
          items:
            type: string
          description: Available model versions.
        platform:
          type: string
          description: Backend platform (e.g., tensorflow_savedmodel, pytorch_libtorch, sklearn_sklearn, xgboost_xgboost, onnxruntime_onnx).
          examples:
          - tensorflow_savedmodel
          - pytorch_libtorch
          - sklearn_sklearn
          - onnxruntime_onnx
          - ensemble
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/TensorMetadata'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/TensorMetadata'
    ErrorResponse:
      type: object
      description: Error response returned when an inference or metadata request fails.
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message describing why the request failed.
          example: 'model not found: bert-sentiment-classifier'
    TensorMetadata:
      type: object
      description: Metadata describing a single input or output tensor.
      required:
      - name
      - datatype
      - shape
      properties:
        name:
          type: string
          description: Name of the tensor as defined by the model.
        datatype:
          $ref: '#/components/schemas/TensorDatatype'
        shape:
          type: array
          description: Shape of the tensor. Use -1 for dynamic dimensions.
          items:
            type: integer
          example:
          - -1
          - 224
          - 224
          - 3
        parameters:
          type: object
          additionalProperties: true
          description: Optional tensor-specific parameters.
    TensorDatatype:
      type: string
      description: Data type of a tensor. Follows the Open Inference Protocol datatype naming convention.
      enum:
      - BOOL
      - UINT8
      - UINT16
      - UINT32
      - UINT64
      - INT8
      - INT16
      - INT32
      - INT64
      - FP16
      - FP32
      - FP64
      - BYTES
      - STRING