From 19b43c2e5239c6ff614c6bf134e8fdfcd2b5bdf1 Mon Sep 17 00:00:00 2001 From: sippili Date: Tue, 11 Aug 2026 17:56:15 +0530 Subject: [PATCH 1/3] MS-1141: Update docs for List Model Catalog search, filters, pagination, and badges --- .../resources/gen-ai/definitions.yml | 69 ++++++++++- .../curl/genai_list_model_catalog.yml | 2 +- .../gen-ai/genai_list_model_catalog.yml | 114 +++++++++++++++++- 3 files changed, 180 insertions(+), 5 deletions(-) diff --git a/specification/resources/gen-ai/definitions.yml b/specification/resources/gen-ai/definitions.yml index 4fff1c4e9..fa01e8d0c 100644 --- a/specification/resources/gen-ai/definitions.yml +++ b/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,17 @@ 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. +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. apiModelEndpoint: description: An available endpoint for a model and its capabilities properties: diff --git a/specification/resources/gen-ai/examples/curl/genai_list_model_catalog.yml b/specification/resources/gen-ai/examples/curl/genai_list_model_catalog.yml index 224cdd787..f0c02d669 100644 --- a/specification/resources/gen-ai/examples/curl/genai_list_model_catalog.yml +++ b/specification/resources/gen-ai/examples/curl/genai_list_model_catalog.yml @@ -2,4 +2,4 @@ lang: cURL source: |- curl -X GET \ -H "Content-Type: application/json" \ - "https://api.digitalocean.com/v2/gen-ai/models/catalog" + "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" diff --git a/specification/resources/gen-ai/genai_list_model_catalog.yml b/specification/resources/gen-ai/genai_list_model_catalog.yml index 299ae276f..1dcadfce2 100644 --- a/specification/resources/gen-ai/genai_list_model_catalog.yml +++ b/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: '"example string"' + 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 +- default: MODEL_CATALOG_SORT_BY_CREATED_AT + 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: '"example string"' + in: query + name: sort_by + schema: + 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 +- default: SORT_DIRECTION_UNSPECIFIED + description: Sort direction. Defaults to descending when unspecified. + example: '"example string"' + in: query + name: sort_direction + schema: + enum: + - SORT_DIRECTION_UNSPECIFIED + - SORT_DIRECTION_ASC + - SORT_DIRECTION_DESC + type: string +- default: MODEL_CATALOG_USE_CASE_UNSPECIFIED + 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: '"example string"' + in: query + name: use_case + schema: + 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: From 0b14e95a076f8b124256e5d928670660f1915495 Mon Sep 17 00:00:00 2001 From: sippili Date: Wed, 12 Aug 2026 14:56:27 +0530 Subject: [PATCH 2/3] fix catalog enum schemas and param defaults/examples --- .../resources/gen-ai/definitions.yml | 34 +++++++++++++++++++ .../curl/genai_list_model_catalog.yml | 1 + .../gen-ai/genai_list_model_catalog.yml | 20 +++++------ 3 files changed, 45 insertions(+), 10 deletions(-) diff --git a/specification/resources/gen-ai/definitions.yml b/specification/resources/gen-ai/definitions.yml index fa01e8d0c..ec595d7fb 100644 --- a/specification/resources/gen-ai/definitions.yml +++ b/specification/resources/gen-ai/definitions.yml @@ -6313,6 +6313,16 @@ 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: |- @@ -6320,6 +6330,30 @@ apiModelCatalogUseCase: 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: diff --git a/specification/resources/gen-ai/examples/curl/genai_list_model_catalog.yml b/specification/resources/gen-ai/examples/curl/genai_list_model_catalog.yml index f0c02d669..95fd8ea87 100644 --- a/specification/resources/gen-ai/examples/curl/genai_list_model_catalog.yml +++ b/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" \ + -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" diff --git a/specification/resources/gen-ai/genai_list_model_catalog.yml b/specification/resources/gen-ai/genai_list_model_catalog.yml index 1dcadfce2..bb4be4568 100644 --- a/specification/resources/gen-ai/genai_list_model_catalog.yml +++ b/specification/resources/gen-ai/genai_list_model_catalog.yml @@ -14,7 +14,7 @@ parameters: schema: type: integer - description: Partial, case-insensitive match on the model's display name. - example: '"example string"' + example: llama in: query name: search schema: @@ -55,17 +55,17 @@ parameters: items: type: string type: array -- default: MODEL_CATALOG_SORT_BY_CREATED_AT - description: |- +- 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: '"example string"' + 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 @@ -77,19 +77,18 @@ parameters: name: per_page schema: type: integer -- default: SORT_DIRECTION_UNSPECIFIED - description: Sort direction. Defaults to descending when unspecified. - example: '"example string"' +- 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 -- default: MODEL_CATALOG_USE_CASE_UNSPECIFIED - description: |- +- 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`, @@ -108,10 +107,11 @@ parameters: 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: '"example string"' + 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 From 5b7f0e4a4c0c5babb959305f836bba458a5d4fcf Mon Sep 17 00:00:00 2001 From: sippili Date: Wed, 12 Aug 2026 16:47:30 +0530 Subject: [PATCH 3/3] fix: add examples --- .../resources/gen-ai/genai_list_model_catalog.yml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/specification/resources/gen-ai/genai_list_model_catalog.yml b/specification/resources/gen-ai/genai_list_model_catalog.yml index bb4be4568..90d7172e4 100644 --- a/specification/resources/gen-ai/genai_list_model_catalog.yml +++ b/specification/resources/gen-ai/genai_list_model_catalog.yml @@ -22,6 +22,8 @@ parameters: - description: |- Filter by model type. Multiple values use OR semantics. Accepted values: `chat`, `embedding`, `image`, `reasoning`, `coding`, `audio`, `reranking`. + example: + - chat in: query name: model_type schema: @@ -31,6 +33,8 @@ parameters: - 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. + example: + - Meta in: query name: provider schema: @@ -40,6 +44,8 @@ parameters: - description: |- Filter by deployment availability. Multiple values use OR semantics. Accepted values: `serverless`, `dedicated`. + example: + - serverless in: query name: availability schema: @@ -49,6 +55,8 @@ parameters: - description: |- Filter by badge. Multiple values use OR semantics. Accepted values: `featured`, `new`, `preview`. + example: + - featured in: query name: badges schema: