MS-1141: Update docs for List Model Catalog search, filters, paginati…

specification/resources/gen-ai/definitions.yml

@@ -5545,12 +5545,66 @@ apiListModelAPIKeysOutput:
   type: object
 apiListModelCatalogInput:
   properties:
-    limit:
-      example: "100"
+    availability:
+      example: '["serverless", "dedicated"]'
+    badges:
+      example: '["featured"]'
+    model_type:
+      example: '["chat", "embedding"]'
     page:
       example: "1"
+    per_page:
+      example: "10"
+    provider:
+      example: '["Meta", "Google", "DeepSeek"]'
+    search:
+      example: llama
 apiListModelCatalogOutput:
   properties:
+    available_availability:
+      description: All deployment availability values the client can offer in the
+        availability filter UI.
+      example:
+      - example string
+      items:
+        example: example string
+        type: string
+      type: array
+    available_badges:
+      description: All badge values the client can offer in the badges filter UI.
+      example:
+      - example string
+      items:
+        example: example string
+        type: string
+      type: array
+    available_model_types:
+      description: All model type values the client can offer in the type filter UI.
+      example:
+      - example string
+      items:
+        example: example string
+        type: string
+      type: array
+    available_providers:
+      description: All provider values the client can offer in the provider filter
+        UI.
+      example:
+      - example string
+      items:
+        example: example string
+        type: string
+      type: array
+    available_sort_by:
+      description: All sort-by field values the client can offer in the sort UI.
+      items:
+        $ref: '#/apiModelCatalogSortBy'
+      type: array
+    available_sort_directions:
+      description: All sort-direction values the client can offer in the sort UI.
+      items:
+        $ref: '#/apiSortDirection'
+      type: array
     data:
       items:
         $ref: '#/apiModelCatalogEntry'
@@ -6255,6 +6309,51 @@ apiModelCatalogEntry:
       example: '"text-to-text"'
       type: string
   type: object
+apiModelCatalogSortBy:
+  default: MODEL_CATALOG_SORT_BY_CREATED_AT
+  description: |-
+    Field on which to sort model catalog results.
+
+     - MODEL_CATALOG_SORT_BY_CREATED_AT: Default: sort by creation date.
+     - MODEL_CATALOG_SORT_BY_NAME: Sort by the model's display name (case-insensitive).
+     - MODEL_CATALOG_SORT_BY_PRICE: Sort by input token price.
+  enum:
+  - MODEL_CATALOG_SORT_BY_CREATED_AT
+  - MODEL_CATALOG_SORT_BY_NAME
+  - MODEL_CATALOG_SORT_BY_PRICE
+  example: MODEL_CATALOG_SORT_BY_CREATED_AT
+  type: string
+apiModelCatalogUseCase:
+  default: MODEL_CATALOG_USE_CASE_UNSPECIFIED
+  description: |-
+    Pre-defined use-case filter for the model catalog. When set, only models
+    that match the selected use case are returned. The server maps each value
+    to a combination of `model_type`, `usecases`, and `output_modalities` checks
+    so the client does not need to construct those filters manually.
+
+     - MODEL_CATALOG_USE_CASE_UNSPECIFIED: No use-case filter applied; return all models.
+     - MODEL_CATALOG_USE_CASE_CODING: Coding-optimized models: model_type = coding, or usecases include coding,
+    agentic_coding, or code_generation.
+     - MODEL_CATALOG_USE_CASE_AGENTS: Agent-building models: usecases include tool_calling, agentic,
+    agent_platform, agentic_workflows, or agentic_coding.
+     - MODEL_CATALOG_USE_CASE_AUDIO: Audio models: model_type is audio, or usecases include audio,
+    text_to_speech, or voice_cloning, or output modalities include audio.
+     - MODEL_CATALOG_USE_CASE_IMAGE: Image models: model_type is image, or usecases include image_generation,
+    text_to_image, or ideogram, or output modalities include image.
+     - MODEL_CATALOG_USE_CASE_VIDEO: Video models: usecases include video_generation or text_to_video, or
+    output modalities include video.
+     - MODEL_CATALOG_USE_CASE_EMBEDDING: Embedding and reranking models: model_type is embedding or reranking, or
+    usecases include vectorization or reranking.
+  enum:
+  - MODEL_CATALOG_USE_CASE_UNSPECIFIED
+  - MODEL_CATALOG_USE_CASE_CODING
+  - MODEL_CATALOG_USE_CASE_AGENTS
+  - MODEL_CATALOG_USE_CASE_AUDIO
+  - MODEL_CATALOG_USE_CASE_IMAGE
+  - MODEL_CATALOG_USE_CASE_VIDEO
+  - MODEL_CATALOG_USE_CASE_EMBEDDING
+  example: MODEL_CATALOG_USE_CASE_UNSPECIFIED
+  type: string
 apiModelEndpoint:
   description: An available endpoint for a model and its capabilities
   properties:

specification/resources/gen-ai/examples/curl/genai_list_model_catalog.yml

@@ -2,4 +2,5 @@ lang: cURL
 source: |-
   curl -X GET \
     -H "Content-Type: application/json"  \
-    "https://api.digitalocean.com/v2/gen-ai/models/catalog"
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/gen-ai/models/catalog?page=1&per_page=20&search=llama&model_type=chat&sort_by=MODEL_CATALOG_SORT_BY_NAME&sort_direction=SORT_DIRECTION_ASC"

specification/resources/gen-ai/genai_list_model_catalog.yml

@@ -1,16 +1,126 @@
 description: Returns all available models.
 operationId: genai_list_model_catalog
 parameters:
-- example: 1
+- description: Page number for pagination.
+  example: 1
   in: query
   name: page
   schema:
     type: integer
-- example: 1
+- description: Deprecated. Use `per_page` instead.
+  example: 1
   in: query
   name: limit
   schema:
     type: integer
+- description: Partial, case-insensitive match on the model's display name.
+  example: llama
+  in: query
+  name: search
+  schema:
+    type: string
+- description: |-
+    Filter by model type. Multiple values use OR semantics.
+    Accepted values: `chat`, `embedding`, `image`, `reasoning`, `coding`, `audio`, `reranking`.
+  in: query
+  name: model_type
+  schema:
+    items:
+      type: string
+    type: array
+- description: |-
+    Filter by model creator/developer. Multiple values use OR semantics.
+    Values are data-driven; use `available_providers` from the response to discover valid options.
+  in: query
+  name: provider
+  schema:
+    items:
+      type: string
+    type: array
+- description: |-
+    Filter by deployment availability. Multiple values use OR semantics.
+    Accepted values: `serverless`, `dedicated`.
+  in: query
+  name: availability
+  schema:
+    items:
+      type: string
+    type: array
+- description: |-
+    Filter by badge. Multiple values use OR semantics.
+    Accepted values: `featured`, `new`, `preview`.
+  in: query
+  name: badges
+  schema:
+    items:
+      type: string
+    type: array
+- description: |-
+    Field to sort results by. Default is `MODEL_CATALOG_SORT_BY_CREATED_AT`.
+
+     - MODEL_CATALOG_SORT_BY_CREATED_AT: Default: sort by creation date.
+     - MODEL_CATALOG_SORT_BY_NAME: Sort by the model's display name (case-insensitive).
+     - MODEL_CATALOG_SORT_BY_PRICE: Sort by input token price.
+  example: MODEL_CATALOG_SORT_BY_NAME
+  in: query
+  name: sort_by
+  schema:
+    default: MODEL_CATALOG_SORT_BY_CREATED_AT
+    enum:
+    - MODEL_CATALOG_SORT_BY_CREATED_AT
+    - MODEL_CATALOG_SORT_BY_NAME
+    - MODEL_CATALOG_SORT_BY_PRICE
+    type: string
+- description: Number of items per page. Replaces the deprecated `limit` field.
+  example: 1
+  in: query
+  name: per_page
+  schema:
+    type: integer
+- description: Sort direction. Defaults to descending when unspecified.
+  example: SORT_DIRECTION_ASC
+  in: query
+  name: sort_direction
+  schema:
+    default: SORT_DIRECTION_UNSPECIFIED
+    enum:
+    - SORT_DIRECTION_UNSPECIFIED
+    - SORT_DIRECTION_ASC
+    - SORT_DIRECTION_DESC
+    type: string
+- description: |-
+    Filter by pre-defined use case. When unspecified, no use-case filter is applied.
+    Accepted values: `MODEL_CATALOG_USE_CASE_CODING`, `MODEL_CATALOG_USE_CASE_AGENTS`,
+    `MODEL_CATALOG_USE_CASE_AUDIO`, `MODEL_CATALOG_USE_CASE_IMAGE`,
+    `MODEL_CATALOG_USE_CASE_EMBEDDING`, `MODEL_CATALOG_USE_CASE_VIDEO`.
+
+     - MODEL_CATALOG_USE_CASE_UNSPECIFIED: No use-case filter applied; return all models.
+     - MODEL_CATALOG_USE_CASE_CODING: Coding-optimized models: model_type = coding, or usecases include coding,
+    agentic_coding, or code_generation.
+     - MODEL_CATALOG_USE_CASE_AGENTS: Agent-building models: usecases include tool_calling, agentic,
+    agent_platform, agentic_workflows, or agentic_coding.
+     - MODEL_CATALOG_USE_CASE_AUDIO: Audio models: model_type is audio, or usecases include audio,
+    text_to_speech, or voice_cloning, or output modalities include audio.
+     - MODEL_CATALOG_USE_CASE_IMAGE: Image models: model_type is image, or usecases include image_generation,
+    text_to_image, or ideogram, or output modalities include image.
+     - MODEL_CATALOG_USE_CASE_VIDEO: Video models: usecases include video_generation or text_to_video, or
+    output modalities include video.
+     - MODEL_CATALOG_USE_CASE_EMBEDDING: Embedding and reranking models: model_type is embedding or reranking, or
+    usecases include vectorization or reranking.
+  example: MODEL_CATALOG_USE_CASE_CODING
+  in: query
+  name: use_case
+  schema:
+    default: MODEL_CATALOG_USE_CASE_UNSPECIFIED
+    enum:
+    - MODEL_CATALOG_USE_CASE_UNSPECIFIED
+    - MODEL_CATALOG_USE_CASE_CODING
+    - MODEL_CATALOG_USE_CASE_AGENTS
+    - MODEL_CATALOG_USE_CASE_AUDIO
+    - MODEL_CATALOG_USE_CASE_IMAGE
+    - MODEL_CATALOG_USE_CASE_VIDEO
+    - MODEL_CATALOG_USE_CASE_EMBEDDING
+    type: string
 responses:
   "200":
     content: