model-registry/api/openapi/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/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. This parameter can be specified multiple times
            to filter by multiple sources (OR logic). For example:
            ?source=huggingface&source=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
        - $ref: "#/components/parameters/pageSize"
        - $ref: "#/components/parameters/orderBy"
        - $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/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/pageSize"
      - $ref: "#/components/parameters/orderBy"
      - $ref: "#/components/parameters/sortOrder"
      - $ref: "#/components/parameters/nextPageToken"
components:
  schemas:
    ArtifactTypeQueryParam:
      description: Supported artifact types for querying.
      enum:
        - model-artifact
        - doc-artifact
        - dataset-artifact
        - metric
        - parameter
      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"
    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
    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
    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.
    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
    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:
    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
    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
    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
    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
    artifactType:
      style: form
      explode: true
      examples:
        artifactType:
          value: model-artifact
      name: artifactType
      description: "Specifies the artifact type for listing artifacts."
      schema:
        $ref: "#/components/schemas/ArtifactTypeQueryParam"
      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: []