Skip to main content

Model Gateway - Catalog

The ModelGatewayCatalogService provides read-only access to the list of models configured in the IBM watsonx.ai Model Gateway.

Quick Start​

ModelGatewayCatalogService catalog = ModelGatewayCatalogService.builder()
    .baseUrl(CloudRegion.DALLAS)
    .apiKey(WATSONX_API_KEY)
    .build();

List<ModelGatewayModel> models = catalog.listModels();
models.forEach(m -> System.out.println(m.id() + " (" + m.ownedBy() + ")"));
// → gpt-4o (openai)
// → claude-3-5-sonnet (anthropic)

Service Configuration​

Basic Setup​

ModelGatewayCatalogService catalog = ModelGatewayCatalogService.builder()
    .baseUrl(CloudRegion.DALLAS)
    .apiKey(WATSONX_API_KEY)
    .build();

Builder Parameters​

ParameterTypeRequiredDescription
apiKeyStringConditionalAPI key for IBM Cloud authentication
authenticatorAuthenticatorConditionalCustom authentication (alternative to apiKey)
baseUrlString / CloudRegionYeswatsonx.ai ML endpoint
timeoutDurationNoRequest timeout (default: 60 seconds)
logRequestsBooleanNoEnable request logging (default: false)
logResponsesBooleanNoEnable response logging (default: false)
httpClientHttpClientNoCustom HTTP client
verifySslBooleanNoSSL certificate verification (default: true)
versionStringNoAPI version override

Either apiKey or authenticator must be provided.

Operations​

listModels​

Returns all models configured across all providers in the gateway.

List<ModelGatewayModel> models = catalog.listModels();

for (ModelGatewayModel model : models) {
    System.out.println("UUID:     " + model.uuid());
    System.out.println("ID:       " + model.id());
    System.out.println("Alias:    " + model.optionalAlias().orElse("(none)"));
    System.out.println("Provider: " + model.ownedBy());
    System.out.println();
}

getModel​

Retrieves a single model by its UUID or alias. Both are accepted identifiers.

// By alias
ModelGatewayModel model = catalog.getModel("gpt-4o");

// By UUID
ModelGatewayModel model = catalog.getModel("123e4567-e89b-12d3-a456-426614174000");

System.out.println("ID:       " + model.id());
System.out.println("Provider: " + model.ownedBy());
System.out.println("Created:  " + model.created());
model.optionalMetadata().ifPresent(meta -> {
    System.out.println("Family:   " + meta.modelFamily());
    System.out.println("Region:   " + meta.region());
    System.out.println("Cost/1k:  " + meta.cost());
});

ModelGatewayModel​

Each model returned by the catalog exposes the following fields.

Core Fields​

MethodTypeDescription
uuid()StringUnique identifier assigned by the gateway
object()StringAlways "model"
created()LongUnix timestamp (seconds) when this configuration was created
ownedBy()StringProvider in the format <type>:<name> (e.g., "openai:my-provider")
id()StringOfficial provider-side model identifier (e.g., "gpt-4o-2024-11-20")
alias()StringOptional friendly name - use this with getModel() instead of the full id
description()StringOptional user-defined description
metadata()ModelGatewayModel.MetadataOptional additional configuration - may be null

ModelGatewayModel.Metadata​

MethodTypeDescription
cost()DoubleCost per 1 000 tokens in USD
modelFamily()StringModel series (e.g., "gpt-4", "claude-3")
recommenderLabel()StringLabel used by the Recommender API
region()StringDeployment region (e.g., "us-east-1")
batch()BooleanWhether the model is preferred for batch requests
contextWindow()IntegerMaximum tokens the model can process in a single request

All Metadata fields may be null when not set by the administrator.