catalog.yaml

openapi: 3.0.3
info:
  title: Model Catalog REST API
  version: v1alpha1
  description: REST API for Model Registry to create and manage ML model metadata
  license:
    name: Apache 2.0
    url: "https://www.apache.org/licenses/LICENSE-2.0"
servers:
  - url: "https://localhost:8080"
  - url: "http://localhost:8080"
paths:
  /api/model_catalog/v1alpha1/labels:
    summary: Path used to get the list of catalog labels.
    description: >-
      The REST endpoint/path used to list zero or more `CatalogLabel` entities.
    get:
      summary: List All CatalogLabels
      tags:
        - ModelCatalogService
      parameters:
        - $ref: "#/components/parameters/pageSize"
        - $ref: "#/components/parameters/labelOrderBy"
        - $ref: "#/components/parameters/sortOrder"
        - $ref: "#/components/parameters/nextPageToken"
      responses:
        "200":
          $ref: "#/components/responses/CatalogLabelListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: findLabels
      description: Gets a list of all `CatalogLabel` entities.
  /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: 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

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

            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:
    summary: Path used to get the list of catalog sources.
    description: >-
      The REST endpoint/path used to list zero or more `CatalogSource` entities.
    get:
      summary: List All CatalogSources
      tags:
        - ModelCatalogService
      parameters:
        - $ref: "#/components/parameters/name"
        - $ref: "#/components/parameters/pageSize"
        - $ref: "#/components/parameters/orderBy"
        - $ref: "#/components/parameters/sortOrder"
        - $ref: "#/components/parameters/nextPageToken"
      responses:
        "200":
          $ref: "#/components/responses/CatalogSourceListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
      operationId: findSources
      description: Gets a list of all `CatalogSource` entities.
  /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"
components:
  schemas:
    ArtifactTypeQueryParam:
      description: Supported artifact types for querying.
      enum:
        - model-artifact
        - metrics-artifact
      type: string
    BaseModel:
      type: object
      properties:
        description:
          type: string
          description: Human-readable description of the model.
        readme:
          type: string
          description: Model documentation in Markdown.
        maturity:
          type: string
          description: Maturity level of the model.
          example: Generally Available
        language:
          type: array
          description: List of supported languages (https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).
          items:
            type: string
          example:
            - en
            - es
            - cz
        tasks:
          type: array
          description: List of tasks the model is designed for.
          items:
            type: string
          example:
            - text-generation
        provider:
          type: string
          description: Name of the organization or entity that provides the model.
          example: IBM
        logo:
          type: string
          format: uri
          description: |-
            URL to the model's logo. A [data
            URL](https://developer.mozilla.org/en-US/docs/Web/URI/Schemes/data)
            is recommended.
        license:
          type: string
          description: Short name of the model's license.
          example: apache-2.0
        licenseLink:
          type: string
          format: uri
          description: URL to the license text.
        libraryName:
          type: string
          example: transformers
        customProperties:
          description: User provided custom properties which are not defined by its type.
          type: object
          additionalProperties:
            $ref: "#/components/schemas/MetadataValue"
    BaseResource:
      allOf:
        - type: object
          properties:
            customProperties:
              description: User provided custom properties which are not defined by its type.
              type: object
              additionalProperties:
                $ref: "#/components/schemas/MetadataValue"
            description:
              description: |-
                An optional description about the resource.
              type: string
            externalId:
              description: |-
                The external id that come from the clients’ system. This field is optional.
                If set, it must be unique among all resources within a database instance.
              type: string
            name:
              description: |-
                The client provided name of the artifact. This field is optional. If set,
                it must be unique among all the artifacts of the same artifact type within
                a database instance and cannot be changed once set.
              type: string
            id:
              format: int64
              description: The unique server generated id of the resource.
              type: string
        - $ref: "#/components/schemas/BaseResourceDates"
    BaseResourceDates:
      description: Common timestamp fields for resources
      type: object
      properties:
        createTimeSinceEpoch:
          format: int64
          description: Output only. Create time of the resource in millisecond since epoch.
          type: string
          readOnly: true
        lastUpdateTimeSinceEpoch:
          format: int64
          description: Output only. Last update time of the resource since epoch in millisecond since epoch.
          type: string
          readOnly: true
    BaseResourceList:
      required:
        - nextPageToken
        - pageSize
        - size
      type: object
      properties:
        nextPageToken:
          description: Token to use to retrieve next page of results.
          type: string
        pageSize:
          format: int32
          description: Maximum number of resources to return in the result.
          type: integer
        size:
          format: int32
          description: Number of items in result list.
          type: integer
    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"
    CatalogLabel:
      description: A catalog label. Labels are used to categorize catalog sources. Represented as a flexible map of string key-value pairs with a required 'name' field.
      type: object
      required:
        - name
      properties:
        name:
          type: string
          nullable: true
          description: The unique name identifier for the label.
        displayName:
          type: string
          description: An optional human-readable name to show in place of `name`.
      additionalProperties:
        type: string
      example:
        name: huggingface
        displayName: HuggingFace Hub
        description: HuggingFace models with full support and legal indemnification.
    CatalogLabelList:
      description: List of CatalogLabel entities.
      allOf:
        - type: object
          properties:
            items:
              description: Array of `CatalogLabel` entities.
              type: array
              items:
                $ref: "#/components/schemas/CatalogLabel"
          required:
            - items
        - $ref: "#/components/schemas/BaseResourceList"
    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
            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.
        - $ref: "#/components/schemas/BaseModel"
        - $ref: "#/components/schemas/BaseResource"
    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"
    CatalogSource:
      description: A catalog source. A catalog source has CatalogModel children.
      required:
        - id
        - name
        - labels
      type: object
      properties:
        id:
          description: A unique identifier for a `CatalogSource`.
          type: string
        name:
          description: The name of the catalog source.
          type: string
        enabled:
          description: Whether the catalog source is enabled.
          type: boolean
          default: true
        labels:
          description: Labels for the catalog source.
          type: array
          items:
            type: string
        includedModels:
          description: |-
            Optional allow-list of models that are eligible for this source. Entries can be
            exact model names or patterns that use `*` as a wildcard. When provided, only
            models matching at least one pattern are considered.

            Pattern matching is case-insensitive, so `Granite/*` will match `granite/model`,
            `Granite/model`, and `GRANITE/model`.
          type: array
          items:
            type: string
        excludedModels:
          description: |-
            Optional block-list of models that should be removed from the catalog even if
            they match `includedModels`. Patterns support the `*` wildcard.

            Pattern matching is case-insensitive, so `*-beta` will match `Model-Beta`,
            `model-beta`, and `MODEL-BETA`.
          type: array
          items:
            type: string
    CatalogSourceList:
      description: List of CatalogSource entities.
      allOf:
        - type: object
          properties:
            items:
              description: Array of `CatalogSource` entities.
              type: array
              items:
                $ref: "#/components/schemas/CatalogSource"
        - $ref: "#/components/schemas/BaseResourceList"
    Error:
      description: Error code and message.
      required:
        - code
        - message
      type: object
      properties:
        code:
          description: Error code
          type: string
        message:
          description: Error message
          type: string
    FilterOption:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: The data type of the filter option
          enum:
            - string
            - number
        values:
          type: array
          description: Known values of the property for string types with a small number of possible options.
          items: {}
        range:
          $ref: "#/components/schemas/FilterOptionRange"
    FilterOptionRange:
      type: object
      description: Min and max values for number types.
      properties:
        min:
          type: number
          format: double
        max:
          type: number
          format: double
    FilterOptionsList:
      description: List of FilterOptions
      type: object
      properties:
        filters:
          type: object
          description: A single filter option.
          additionalProperties:
            $ref: "#/components/schemas/FilterOption"
    MetadataBoolValue:
      description: A bool property value.
      type: object
      required:
        - metadataType
        - bool_value
      properties:
        bool_value:
          type: boolean
        metadataType:
          type: string
          example: MetadataBoolValue
          default: MetadataBoolValue
    MetadataDoubleValue:
      description: A double property value.
      type: object
      required:
        - metadataType
        - double_value
      properties:
        double_value:
          format: double
          type: number
        metadataType:
          type: string
          example: MetadataDoubleValue
          default: MetadataDoubleValue
    MetadataIntValue:
      description: An integer (int64) property value.
      type: object
      required:
        - metadataType
        - int_value
      properties:
        int_value:
          format: int64
          type: string
        metadataType:
          type: string
          example: MetadataIntValue
          default: MetadataIntValue
    MetadataProtoValue:
      description: A proto property value.
      type: object
      required:
        - metadataType
        - type
        - proto_value
      properties:
        type:
          description: url describing proto value
          type: string
        proto_value:
          description: Base64 encoded bytes for proto value
          type: string
        metadataType:
          type: string
          example: MetadataProtoValue
          default: MetadataProtoValue
    MetadataStringValue:
      description: A string property value.
      type: object
      required:
        - metadataType
        - string_value
      properties:
        string_value:
          type: string
        metadataType:
          type: string
          example: MetadataStringValue
          default: MetadataStringValue
    MetadataStructValue:
      description: A struct property value.
      type: object
      required:
        - metadataType
        - struct_value
      properties:
        struct_value:
          description: Base64 encoded bytes for struct value
          type: string
        metadataType:
          type: string
          example: MetadataStructValue
          default: MetadataStructValue
    MetadataValue:
      oneOf:
        - $ref: "#/components/schemas/MetadataIntValue"
        - $ref: "#/components/schemas/MetadataDoubleValue"
        - $ref: "#/components/schemas/MetadataStringValue"
        - $ref: "#/components/schemas/MetadataStructValue"
        - $ref: "#/components/schemas/MetadataProtoValue"
        - $ref: "#/components/schemas/MetadataBoolValue"
      discriminator:
        propertyName: metadataType
        mapping:
          MetadataBoolValue: "#/components/schemas/MetadataBoolValue"
          MetadataDoubleValue: "#/components/schemas/MetadataDoubleValue"
          MetadataIntValue: "#/components/schemas/MetadataIntValue"
          MetadataProtoValue: "#/components/schemas/MetadataProtoValue"
          MetadataStringValue: "#/components/schemas/MetadataStringValue"
          MetadataStructValue: "#/components/schemas/MetadataStructValue"
      description: A value in properties.
      example:
        string_value: my_value
        metadataType: MetadataStringValue
    OrderByField:
      description: |-
        Supported fields for ordering result entities.
      enum:
        - CREATE_TIME
        - LAST_UPDATE_TIME
        - ID
        - NAME
      type: string
    SortOrder:
      description: Supported sort direction for ordering result entities.
      enum:
        - ASC
        - DESC
      type: string
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
      description: Bad Request parameters
    CatalogArtifactListResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CatalogArtifactList"
      description: A response containing a list of CatalogArtifact entities.
    CatalogLabelListResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CatalogLabelList"
      description: A response containing a list of CatalogLabel 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.
    CatalogSourceListResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CatalogSourceList"
      description: A response containing a list of CatalogSource entities.
    CatalogSourceResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CatalogSource"
      description: A response containing a `CatalogSource` entity.
    Conflict:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
      description: Conflict with current state of target resource
    FilterOptionsResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/FilterOptionsList"
      description: A response containing options for a `filterQuery` parameter.
    InternalServerError:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
      description: Unexpected internal server error
    NotFound:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
      description: The specified resource was not found
    ServiceUnavailable:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
      description: Service is unavailable
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
      description: Unauthorized
    UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
      description: Unprocessable Entity error
  parameters:
    filterQuery:
      examples:
        filterQuery:
          value: "name='my-model' AND state='LIVE'"
      name: filterQuery
      description: |
        A SQL-like query string to filter the list of entities. 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:**
        - Standard properties: `name`, `id`, `state`, `createTimeSinceEpoch`
        - Custom properties: Any user-defined property name
        - 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-model"`
        - Comparison: `accuracy > 0.95`
        - Pattern: `name LIKE "%tensorflow%"`
        - Complex: `(name = "model-a" OR name = "model-b") AND state = "LIVE"`
        - Custom property: `framework.string_value = "pytorch"`
        - Escaped property: `` `mlflow.source.type` = "notebook" ``
      schema:
        type: string
      in: query
      required: false
    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
      in: query
      required: false
    orderBy:
      style: form
      explode: true
      examples:
        orderBy:
          value: ID
      name: orderBy
      description: Specifies the order by criteria for listing entities.
      schema:
        $ref: "#/components/schemas/OrderByField"
      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
    labelOrderBy:
      style: form
      explode: true
      examples:
        labelOrderBy:
          value: name
      name: orderBy
      description: |
        Specifies the key to order catalog labels by. You can provide any string key
        that may exist in the label maps. Labels that contain the specified key will
        be sorted by that key's value. Labels that don't contain the key will maintain
        their original order and appear after labels that do contain the key.
      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
    id:
      name: id
      description: The ID of resource.
      schema:
        type: string
      in: path
      required: true
    name:
      examples:
        name:
          value: entity-name
      name: name
      description: Name of entity to search.
      schema:
        type: string
      in: query
      required: false
    externalId:
      examples:
        externalId:
          value: "10"
      name: externalId
      description: External ID of entity to search.
      schema:
        type: string
      in: query
      required: false
    parentResourceId:
      examples:
        parentResourceId:
          value: "10"
      name: parentResourceId
      description: ID of the parent resource to use for search.
      schema:
        type: string
      in: query
      required: false
    pageSize:
      examples:
        pageSize:
          value: "100"
      name: pageSize
      description: Number of entities in each page.
      schema:
        type: string
      in: query
      required: false
    nextPageToken:
      name: nextPageToken
      description: Token to use to retrieve next page of results.
      schema:
        type: string
      in: query
      required: false
    sortOrder:
      style: form
      explode: true
      examples:
        sortOrder:
          value: DESC
      name: sortOrder
      description: "Specifies the sort order for listing entities, defaults to ASC."
      schema:
        $ref: "#/components/schemas/SortOrder"
      in: query
      required: false
    stepIds:
      style: form
      explode: true
      examples:
        stepIds:
          value: "1,2,3"
      name: stepIds
      description: "Comma-separated list of step IDs to filter metrics by."
      schema:
        type: string
      in: query
      required: false
  securitySchemes:
    Bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Bearer JWT scheme
security:
  - Bearer: []
tags: []