Scalable Inference Serving Metadata API

openapi: 3.2.0
info:
  title: KServe Open Inference Protocol Metadata 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: Metadata
  description: Server and model metadata endpoints
paths:
  /v2:
    get:
      operationId: GetServerMetadata
      summary: Get Server Metadata
      description: Returns metadata about the inference server, including its name, version, and the extensions it supports.
      tags:
      - Metadata
      responses:
        '200':
          description: Server metadata returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerMetadataResponse'
              example:
                name: triton
                version: 2.30.0
                extensions:
                - binary_tensor_data
                - classification
                - sequence
                - model_configuration
  /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:
      - Metadata
      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:
      - Metadata
      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:
    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.
    ServerMetadataResponse:
      type: object
      description: Server metadata including name, version, and supported extensions.
      required:
      - name
      - version
      - extensions
      properties:
        name:
          type: string
          description: Server implementation name (e.g., triton, kserve, bentoml).
          example: triton
        version:
          type: string
          description: Server version string.
          example: 2.30.0
        extensions:
          type: array
          description: List of protocol extensions supported by the server.
          items:
            type: string
          example:
          - binary_tensor_data
          - classification
    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