Skip to content

Commit 90fdf0d

Browse files
satyaabhishekippilisatyaabhishekippili
authored
MS-1141: Update docs for List Model Catalog search, filters, paginati… (#1214)
* MS-1141: Update docs for List Model Catalog search, filters, pagination, and badges * fix catalog enum schemas and param defaults/examples * fix: add examples
1 parent 7c1300c commit 90fdf0d

3 files changed

Lines changed: 223 additions & 5 deletions

File tree

‎specification/resources/gen-ai/definitions.yml‎

Lines changed: 101 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5545,12 +5545,66 @@ apiListModelAPIKeysOutput:
55455545
type: object
55465546
apiListModelCatalogInput:
55475547
properties:
5548-
limit:
5549-
example: "100"
5548+
availability:
5549+
example: '["serverless", "dedicated"]'
5550+
badges:
5551+
example: '["featured"]'
5552+
model_type:
5553+
example: '["chat", "embedding"]'
55505554
page:
55515555
example: "1"
5556+
per_page:
5557+
example: "10"
5558+
provider:
5559+
example: '["Meta", "Google", "DeepSeek"]'
5560+
search:
5561+
example: llama
55525562
apiListModelCatalogOutput:
55535563
properties:
5564+
available_availability:
5565+
description: All deployment availability values the client can offer in the
5566+
availability filter UI.
5567+
example:
5568+
- example string
5569+
items:
5570+
example: example string
5571+
type: string
5572+
type: array
5573+
available_badges:
5574+
description: All badge values the client can offer in the badges filter UI.
5575+
example:
5576+
- example string
5577+
items:
5578+
example: example string
5579+
type: string
5580+
type: array
5581+
available_model_types:
5582+
description: All model type values the client can offer in the type filter UI.
5583+
example:
5584+
- example string
5585+
items:
5586+
example: example string
5587+
type: string
5588+
type: array
5589+
available_providers:
5590+
description: All provider values the client can offer in the provider filter
5591+
UI.
5592+
example:
5593+
- example string
5594+
items:
5595+
example: example string
5596+
type: string
5597+
type: array
5598+
available_sort_by:
5599+
description: All sort-by field values the client can offer in the sort UI.
5600+
items:
5601+
$ref: '#/apiModelCatalogSortBy'
5602+
type: array
5603+
available_sort_directions:
5604+
description: All sort-direction values the client can offer in the sort UI.
5605+
items:
5606+
$ref: '#/apiSortDirection'
5607+
type: array
55545608
data:
55555609
items:
55565610
$ref: '#/apiModelCatalogEntry'
@@ -6255,6 +6309,51 @@ apiModelCatalogEntry:
62556309
example: '"text-to-text"'
62566310
type: string
62576311
type: object
6312+
apiModelCatalogSortBy:
6313+
default: MODEL_CATALOG_SORT_BY_CREATED_AT
6314+
description: |-
6315+
Field on which to sort model catalog results.
6316+
6317+
- MODEL_CATALOG_SORT_BY_CREATED_AT: Default: sort by creation date.
6318+
- MODEL_CATALOG_SORT_BY_NAME: Sort by the model's display name (case-insensitive).
6319+
- MODEL_CATALOG_SORT_BY_PRICE: Sort by input token price.
6320+
enum:
6321+
- MODEL_CATALOG_SORT_BY_CREATED_AT
6322+
- MODEL_CATALOG_SORT_BY_NAME
6323+
- MODEL_CATALOG_SORT_BY_PRICE
6324+
example: MODEL_CATALOG_SORT_BY_CREATED_AT
6325+
type: string
6326+
apiModelCatalogUseCase:
6327+
default: MODEL_CATALOG_USE_CASE_UNSPECIFIED
6328+
description: |-
6329+
Pre-defined use-case filter for the model catalog. When set, only models
6330+
that match the selected use case are returned. The server maps each value
6331+
to a combination of `model_type`, `usecases`, and `output_modalities` checks
6332+
so the client does not need to construct those filters manually.
6333+
6334+
- MODEL_CATALOG_USE_CASE_UNSPECIFIED: No use-case filter applied; return all models.
6335+
- MODEL_CATALOG_USE_CASE_CODING: Coding-optimized models: model_type = coding, or usecases include coding,
6336+
agentic_coding, or code_generation.
6337+
- MODEL_CATALOG_USE_CASE_AGENTS: Agent-building models: usecases include tool_calling, agentic,
6338+
agent_platform, agentic_workflows, or agentic_coding.
6339+
- MODEL_CATALOG_USE_CASE_AUDIO: Audio models: model_type is audio, or usecases include audio,
6340+
text_to_speech, or voice_cloning, or output modalities include audio.
6341+
- MODEL_CATALOG_USE_CASE_IMAGE: Image models: model_type is image, or usecases include image_generation,
6342+
text_to_image, or ideogram, or output modalities include image.
6343+
- MODEL_CATALOG_USE_CASE_VIDEO: Video models: usecases include video_generation or text_to_video, or
6344+
output modalities include video.
6345+
- MODEL_CATALOG_USE_CASE_EMBEDDING: Embedding and reranking models: model_type is embedding or reranking, or
6346+
usecases include vectorization or reranking.
6347+
enum:
6348+
- MODEL_CATALOG_USE_CASE_UNSPECIFIED
6349+
- MODEL_CATALOG_USE_CASE_CODING
6350+
- MODEL_CATALOG_USE_CASE_AGENTS
6351+
- MODEL_CATALOG_USE_CASE_AUDIO
6352+
- MODEL_CATALOG_USE_CASE_IMAGE
6353+
- MODEL_CATALOG_USE_CASE_VIDEO
6354+
- MODEL_CATALOG_USE_CASE_EMBEDDING
6355+
example: MODEL_CATALOG_USE_CASE_UNSPECIFIED
6356+
type: string
62586357
apiModelEndpoint:
62596358
description: An available endpoint for a model and its capabilities
62606359
properties:

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,5 @@ lang: cURL
22
source: |-
33
curl -X GET \
44
-H "Content-Type: application/json" \
5-
"https://api.digitalocean.com/v2/gen-ai/models/catalog"
5+
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
6+
"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‎

Lines changed: 120 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,134 @@
11
description: Returns all available models.
22
operationId: genai_list_model_catalog
33
parameters:
4-
- example: 1
4+
- description: Page number for pagination.
5+
example: 1
56
in: query
67
name: page
78
schema:
89
type: integer
9-
- example: 1
10+
- description: Deprecated. Use `per_page` instead.
11+
example: 1
1012
in: query
1113
name: limit
1214
schema:
1315
type: integer
16+
- description: Partial, case-insensitive match on the model's display name.
17+
example: llama
18+
in: query
19+
name: search
20+
schema:
21+
type: string
22+
- description: |-
23+
Filter by model type. Multiple values use OR semantics.
24+
Accepted values: `chat`, `embedding`, `image`, `reasoning`, `coding`, `audio`, `reranking`.
25+
example:
26+
- chat
27+
in: query
28+
name: model_type
29+
schema:
30+
items:
31+
type: string
32+
type: array
33+
- description: |-
34+
Filter by model creator/developer. Multiple values use OR semantics.
35+
Values are data-driven; use `available_providers` from the response to discover valid options.
36+
example:
37+
- Meta
38+
in: query
39+
name: provider
40+
schema:
41+
items:
42+
type: string
43+
type: array
44+
- description: |-
45+
Filter by deployment availability. Multiple values use OR semantics.
46+
Accepted values: `serverless`, `dedicated`.
47+
example:
48+
- serverless
49+
in: query
50+
name: availability
51+
schema:
52+
items:
53+
type: string
54+
type: array
55+
- description: |-
56+
Filter by badge. Multiple values use OR semantics.
57+
Accepted values: `featured`, `new`, `preview`.
58+
example:
59+
- featured
60+
in: query
61+
name: badges
62+
schema:
63+
items:
64+
type: string
65+
type: array
66+
- description: |-
67+
Field to sort results by. Default is `MODEL_CATALOG_SORT_BY_CREATED_AT`.
68+
69+
- MODEL_CATALOG_SORT_BY_CREATED_AT: Default: sort by creation date.
70+
- MODEL_CATALOG_SORT_BY_NAME: Sort by the model's display name (case-insensitive).
71+
- MODEL_CATALOG_SORT_BY_PRICE: Sort by input token price.
72+
example: MODEL_CATALOG_SORT_BY_NAME
73+
in: query
74+
name: sort_by
75+
schema:
76+
default: MODEL_CATALOG_SORT_BY_CREATED_AT
77+
enum:
78+
- MODEL_CATALOG_SORT_BY_CREATED_AT
79+
- MODEL_CATALOG_SORT_BY_NAME
80+
- MODEL_CATALOG_SORT_BY_PRICE
81+
type: string
82+
- description: Number of items per page. Replaces the deprecated `limit` field.
83+
example: 1
84+
in: query
85+
name: per_page
86+
schema:
87+
type: integer
88+
- description: Sort direction. Defaults to descending when unspecified.
89+
example: SORT_DIRECTION_ASC
90+
in: query
91+
name: sort_direction
92+
schema:
93+
default: SORT_DIRECTION_UNSPECIFIED
94+
enum:
95+
- SORT_DIRECTION_UNSPECIFIED
96+
- SORT_DIRECTION_ASC
97+
- SORT_DIRECTION_DESC
98+
type: string
99+
- description: |-
100+
Filter by pre-defined use case. When unspecified, no use-case filter is applied.
101+
Accepted values: `MODEL_CATALOG_USE_CASE_CODING`, `MODEL_CATALOG_USE_CASE_AGENTS`,
102+
`MODEL_CATALOG_USE_CASE_AUDIO`, `MODEL_CATALOG_USE_CASE_IMAGE`,
103+
`MODEL_CATALOG_USE_CASE_EMBEDDING`, `MODEL_CATALOG_USE_CASE_VIDEO`.
104+
105+
- MODEL_CATALOG_USE_CASE_UNSPECIFIED: No use-case filter applied; return all models.
106+
- MODEL_CATALOG_USE_CASE_CODING: Coding-optimized models: model_type = coding, or usecases include coding,
107+
agentic_coding, or code_generation.
108+
- MODEL_CATALOG_USE_CASE_AGENTS: Agent-building models: usecases include tool_calling, agentic,
109+
agent_platform, agentic_workflows, or agentic_coding.
110+
- MODEL_CATALOG_USE_CASE_AUDIO: Audio models: model_type is audio, or usecases include audio,
111+
text_to_speech, or voice_cloning, or output modalities include audio.
112+
- MODEL_CATALOG_USE_CASE_IMAGE: Image models: model_type is image, or usecases include image_generation,
113+
text_to_image, or ideogram, or output modalities include image.
114+
- MODEL_CATALOG_USE_CASE_VIDEO: Video models: usecases include video_generation or text_to_video, or
115+
output modalities include video.
116+
- MODEL_CATALOG_USE_CASE_EMBEDDING: Embedding and reranking models: model_type is embedding or reranking, or
117+
usecases include vectorization or reranking.
118+
example: MODEL_CATALOG_USE_CASE_CODING
119+
in: query
120+
name: use_case
121+
schema:
122+
default: MODEL_CATALOG_USE_CASE_UNSPECIFIED
123+
enum:
124+
- MODEL_CATALOG_USE_CASE_UNSPECIFIED
125+
- MODEL_CATALOG_USE_CASE_CODING
126+
- MODEL_CATALOG_USE_CASE_AGENTS
127+
- MODEL_CATALOG_USE_CASE_AUDIO
128+
- MODEL_CATALOG_USE_CASE_IMAGE
129+
- MODEL_CATALOG_USE_CASE_VIDEO
130+
- MODEL_CATALOG_USE_CASE_EMBEDDING
131+
type: string
14132
responses:
15133
"200":
16134
content:

0 commit comments

Comments
 (0)