model.yaml

paths:
  /api/model_catalog/v1alpha1/models:
    description: >-
      The REST endpoint/path used to list zero or more `CatalogModel` entities from all `CatalogSources`.
    get:
      summary: Search catalog models across sources.
      tags:
        - ModelCatalogService
      parameters:
        - name: recommendations
          in: query
          deprecated: true
          description: >-
            Deprecated: use `orderBy=RECOMMENDED` instead.
            Sort models by lowest recommended latency using Pareto filtering.
          required: false
          schema:
            type: boolean
            default: false
        - name: targetRPS
          in: query
          description: Target requests per second for latency calculations
          required: false
          schema:
            type: integer
            format: int32
        - name: latencyProperty
          in: query
          description: Property name for latency metric
          required: false
          schema:
            type: string
            default: "ttft_p90"
        - name: rpsProperty
          in: query
          description: Property name for RPS metric
          required: false
          schema:
            type: string
            default: "requests_per_second"
        - name: hardwareCountProperty
          in: query
          description: Property name for hardware count
          required: false
          schema:
            type: string
            default: "hardware_count"
        - name: hardwareTypeProperty
          in: query
          description: Property name for hardware type grouping
          required: false
          schema:
            type: string
            default: "hardware_type"
        - name: source
          description: |-
            Filter models by source. Multiple values can be separated by commas
            to filter by multiple sources (OR logic). For example:
            ?source=huggingface,local will return models from either
            huggingface OR local sources.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          in: query
          required: false
        - name: q
          description: Free-form keyword search used to filter the response.
          schema:
            type: string
          in: query
          required: false
        - name: sourceLabel
          description: |-
            Filter models by the label associated with the source. Multiple
            values can be separated by commas. If one of the values is the
            string `null`, then models from every source without a label will
            be returned.
          schema:
            type: array
            items:
              type: string
          in: query
          required: false
        - $ref: "#/components/parameters/filterQuery"
        - $ref: "#/components/parameters/pageSize"
        - name: orderBy
          style: form
          explode: true
          examples:
            orderBy:
              value: ID
          description: |-
            Specifies the order by criteria for listing entities.

            Supported values are:
            - CREATE_TIME
            - LAST_UPDATE_TIME
            - ID
            - NAME
            - ACCURACY
            - RECOMMENDED

            Defaults to `NAME`.

            The `ACCURACY` sort will sort by the `overall_average` property in any linked metrics artifact.

            The `RECOMMENDED` sort applies Pareto filtering and ranks models by recommended latency.
            The Pareto-related parameters (`targetRPS`, `latencyProperty`, `rpsProperty`,
            `hardwareCountProperty`, `hardwareTypeProperty`) are applied the same way as with the
            deprecated `recommendations` parameter. With the default `sortOrder=ASC`, the most
            recommended models (lowest latency) appear first. Use `sortOrder=DESC` to show the least
            recommended configurations first.

            In addition, models can be sorted by properties. For example:
            - `provider.string_value` sorts by provider name
            - `artifacts.ifeval.double_value` sorts by the min/max value a property called ifeval across all associated artifacts
          schema:
            $ref: "#/components/schemas/OrderByField"
          in: query
          required: false
        - $ref: "#/components/parameters/sortOrder"
        - $ref: "#/components/parameters/nextPageToken"
      responses:
        "200":
          $ref: "#/components/responses/CatalogModelListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: findModels
  /api/model_catalog/v1alpha1/models/filter_options:
    description: Lists options for `filterQuery` when listing models.
    get:
      summary: Lists fields and available options that can be used in `filterQuery` on the list models endpoint.
      tags:
        - ModelCatalogService
      responses:
        "200":
          $ref: "#/components/responses/FilterOptionsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: findModelsFilterOptions
  /api/model_catalog/v1alpha1/sources/{source_id}/models/{model_name+}:
    description: >-
      The REST endpoint/path used to get a `CatalogModel`.
    get:
      summary: Get a `CatalogModel`.
      tags:
        - ModelCatalogService
      responses:
        "200":
          $ref: "#/components/responses/CatalogModelResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: getModel
    parameters:
      - name: source_id
        description: A unique identifier for a `CatalogSource`.
        schema:
          type: string
        in: path
        required: true
      - name: model_name+
        description: A unique identifier for the model.
        schema:
          type: string
        in: path
        required: true
  /api/model_catalog/v1alpha1/sources/{source_id}/models/{model_name}/artifacts:
    description: >-
      The REST endpoint/path used to list `CatalogArtifacts`.
    get:
      summary: List CatalogArtifacts.
      tags:
        - ModelCatalogService
      responses:
        "200":
          $ref: "#/components/responses/CatalogArtifactListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: getAllModelArtifacts
    parameters:
      - name: source_id
        description: A unique identifier for a `CatalogSource`.
        schema:
          type: string
        in: path
        required: true
      - name: model_name
        description: A unique identifier for the model.
        schema:
          type: string
        in: path
        required: true
      - $ref: "#/components/parameters/artifactType"
      - $ref: "#/components/parameters/artifact_type"
      - $ref: "#/components/parameters/artifactFilterQuery"
      - $ref: "#/components/parameters/pageSize"
      - $ref: "#/components/parameters/artifactOrderBy"
      - $ref: "#/components/parameters/sortOrder"
      - $ref: "#/components/parameters/nextPageToken"
  /api/model_catalog/v1alpha1/sources/{source_id}/models/{model_name}/artifacts/performance:
    description: >-
      Lists performance metrics artifacts (that is, artifacts of type `CatalogMetricsArtifact` where `metricsType` is `performance-metrics`).
    get:
      summary: List CatalogArtifacts.
      tags:
        - ModelCatalogService
      responses:
        "200":
          $ref: "#/components/responses/CatalogArtifactListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: getAllModelPerformanceArtifacts
    parameters:
      - name: source_id
        description: A unique identifier for a `CatalogSource`.
        schema:
          type: string
        in: path
        required: true
      - name: model_name
        description: A unique identifier for the model.
        schema:
          type: string
        in: path
        required: true
      - name: targetRPS
        description: |-
          Target requests per second. If specified, values for `replicas` and
          `total_requests_per_second` will be calculated and returned as custom
          properties.
        schema:
          type: integer
        in: query
      - name: recommendations
        description: Filter records that are less optimal based on approximate cost to run and latency.
        schema:
          type: boolean
          default: false
        in: query
      - name: rpsProperty
        description: Custom property name for requests per second metric.
        schema:
          type: string
          default: "requests_per_second"
        in: query
      - name: latencyProperty
        description: Custom property name for latency metric (e.g., ttft_p90, p90_latency).
        schema:
          type: string
          default: "ttft_p90"
        in: query
      - name: hardwareCountProperty
        description: Custom property name for hardware count metric.
        schema:
          type: string
          default: "hardware_count"
        in: query
      - name: hardwareTypeProperty
        description: Custom property name for hardware type grouping.
        schema:
          type: string
          default: "hardware_type"
        in: query
      - $ref: "#/components/parameters/artifactFilterQuery"
      - $ref: "#/components/parameters/pageSize"
      - $ref: "#/components/parameters/artifactOrderBy"
      - $ref: "#/components/parameters/sortOrder"
      - $ref: "#/components/parameters/nextPageToken"
components:
  schemas:
    CatalogArtifact:
      description: A single artifact in the catalog API.
      oneOf:
        - $ref: "#/components/schemas/CatalogModelArtifact"
        - $ref: "#/components/schemas/CatalogMetricsArtifact"
      discriminator:
        propertyName: artifactType
        mapping:
          model-artifact: "#/components/schemas/CatalogModelArtifact"
          metrics-artifact: "#/components/schemas/CatalogMetricsArtifact"
    CatalogArtifactList:
      description: List of CatalogModel entities.
      allOf:
        - type: object
          properties:
            items:
              description: Array of `CatalogArtifact` entities.
              type: array
              items:
                $ref: "#/components/schemas/CatalogArtifact"
          required:
            - items
        - $ref: "#/components/schemas/BaseResourceList"
    ArtifactTypeQueryParam:
      description: Supported artifact types for querying.
      enum:
        - model-artifact
        - metrics-artifact
      type: string
    CatalogMetricsArtifact:
      description: A metadata Artifact Entity.
      allOf:
        - type: object
          required:
            - artifactType
            - metricsType
          properties:
            artifactType:
              type: string
              default: metrics-artifact
            metricsType:
              type: string
              enum:
                - performance-metrics
                - accuracy-metrics
                - security-metrics
            customProperties:
              description: User provided custom properties which are not defined by its type.
              type: object
              additionalProperties:
                $ref: "#/components/schemas/MetadataValue"
        - $ref: "#/components/schemas/BaseResource"
    CatalogModel:
      description: A model in the model catalog.
      allOf:
        - type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Name of the model. Must be unique within a source.
              example: ibm-granite/granite-3.1-8b-base
            source_id:
              type: string
              description: ID of the source this model belongs to.
            validatedTasks:
              type: array
              items:
                type: string
              description: List of tasks for this model which have been validated by the catalog provider.
            servingConfig:
              $ref: "#/components/schemas/ServingConfig"
        - $ref: "#/components/schemas/BaseModel"
        - $ref: "#/components/schemas/BaseResource"
    ServingConfig:
      description: >-
        Serving and deployment configuration for the model. Each property represents a distinct configuration concern with its own typed schema. All properties are optional.
      type: object
      properties:
        toolCalling:
          $ref: "#/components/schemas/ToolCallingConfig"
    ToolCallingConfig:
      description: >-
        Tool-calling arguments for this model.
      type: object
      properties:
        toolCallParser:
          type: string
          description: >-
            The tool-call parser identifier for the serving runtime.
          example: granite
        chatTemplate:
          type: string
          description: >-
            Path to the chat template file packaged with the model.
          example: opt/app-root/template/tool_chat_template_granite.jinja
        enableAutoToolChoice:
          type: boolean
          description: >-
            Whether to enable automatic tool choice in the serving runtime.
          default: true
        requiredArgs:
          type: array
          items:
            type: string
          description: >-
            Additional CLI arguments required for tool calling beyond the parser, template, and auto-tool-choice flags. Each entry is a complete argument (e.g., "--config_format mistral").
          example:
            - "--config_format granite"
    CatalogModelArtifact:
      description: A Catalog Model Artifact Entity.
      allOf:
        - type: object
          required:
            - artifactType
            - uri
          properties:
            artifactType:
              type: string
              default: model-artifact
            uri:
              type: string
              format: uri
              description: URI where the model can be retrieved.
            customProperties:
              description: User provided custom properties which are not defined by its type.
              type: object
              additionalProperties:
                $ref: "#/components/schemas/MetadataValue"
        - $ref: "#/components/schemas/BaseResource"
    CatalogModelList:
      description: List of CatalogModel entities.
      allOf:
        - type: object
          properties:
            items:
              description: Array of `CatalogModel` entities.
              type: array
              items:
                $ref: "#/components/schemas/CatalogModel"
          required:
            - items
        - $ref: "#/components/schemas/BaseResourceList"
  responses:
    CatalogArtifactListResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CatalogArtifactList"
      description: A response containing a list of CatalogArtifact entities.
    CatalogModelListResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CatalogModelList"
      description: A response containing a list of CatalogModel entities.
    CatalogModelResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CatalogModel"
      description: A response containing a `CatalogModel` entity.
  parameters:
    artifactFilterQuery:
      examples:
        artifactFilterQuery:
          value: "name='my-artifact' AND uri LIKE '%s3%'"
      name: filterQuery
      description: |
        A SQL-like query string to filter catalog artifacts. The query supports rich filtering capabilities with automatic type inference.

        **Supported Operators:**
        - Comparison: `=`, `!=`, `<>`, `>`, `<`, `>=`, `<=`
        - Pattern matching: `LIKE`, `ILIKE` (case-insensitive)
        - Set membership: `IN`
        - Logical: `AND`, `OR`
        - Grouping: `()` for complex expressions

        **Data Types:**
        - Strings: `"value"` or `'value'`
        - Numbers: `42`, `3.14`, `1e-5`
        - Booleans: `true`, `false` (case-insensitive)

        **Property Access (Artifacts):**
        - Standard properties: `name`, `id`, `uri`, `artifactType`, `createTimeSinceEpoch`
        - Custom properties: Any user-defined property name in `customProperties`
        - Escaped properties: Use backticks for special characters: `` `custom-property` ``
        - Type-specific access: `property.string_value`, `property.double_value`, `property.int_value`, `property.bool_value`

        **Examples:**
        - Basic: `name = "my-artifact"`
        - Comparison: `ttft_mean > 90`
        - Pattern: `uri LIKE "%s3.amazonaws.com%"`
        - Complex: `(artifactType = "model-artifact" OR artifactType = "metrics-artifact") AND name LIKE "%pytorch%"`
        - Custom property: `format.string_value = "pytorch"`
        - Escaped property: `` `custom-key` = "value" ``
      schema:
        type: string
        pattern: "^[\\x20-\\x7E]*$"
      in: query
      required: false
    artifactOrderBy:
      style: form
      explode: true
      examples:
        standardField:
          value: ID
          summary: Order by standard field
        customPropertyDouble:
          value: mmlu.double_value
          summary: Order by custom double property
        customPropertyString:
          value: framework_type.string_value
          summary: Order by custom string property
        customPropertyInt:
          value: hardware_count.int_value
          summary: Order by custom integer property
      name: orderBy
      description: |
        Specifies the order by criteria for listing artifacts.

        **Standard Fields:**
        - `ID` - Order by artifact ID
        - `NAME` - Order by artifact name
        - `CREATE_TIME` - Order by creation timestamp
        - `LAST_UPDATE_TIME` - Order by last update timestamp

        **Custom Property Ordering:**

        Artifacts can be ordered by custom properties using the format: `<property_name>.<value_type>`

        Supported value types:
        - `double_value` - For numeric (floating-point) properties
        - `int_value` - For integer properties
        - `string_value` - For string properties

        Examples:
        - `mmlu.double_value` - Order by the 'mmlu' benchmark score
        - `accuracy.double_value` - Order by accuracy metric
        - `framework_type.string_value` - Order by framework type
        - `hardware_count.int_value` - Order by hardware count
        - `ttft_mean.double_value` - Order by time-to-first-token mean

        **Behavior:**
        - If an invalid value type is specified (e.g., `accuracy.invalid_type`), an error is returned
        - If an invalid format is used (e.g., `accuracy` without `.value_type`), it falls back to ID ordering
        - If a property doesn't exist, it falls back to ID ordering
        - Artifacts with the specified property are ordered first (by the property value), followed by artifacts without the property (ordered by ID)
        - Empty property names (e.g., `.double_value`) return an error
      schema:
        type: string
      in: query
      required: false
    artifactType:
      style: form
      explode: true
      examples:
        artifactType:
          value: model-artifact
      name: artifactType
      description: "Specifies the artifact type for listing artifacts."
      schema:
        type: array
        items:
          $ref: "#/components/schemas/ArtifactTypeQueryParam"
      in: query
      required: false
    artifact_type:
      deprecated: true
      style: form
      explode: true
      examples:
        artifact_type:
          value: model-artifact
      name: artifact_type
      description: "Specifies the artifact type for listing artifacts."
      schema:
        type: array
        items:
          $ref: "#/components/schemas/ArtifactTypeQueryParam"
      in: query
      required: false