Deployment Service

The DeploymentService allows you to interact with models deployed in IBM watsonx.ai deployment spaces. Instead of referencing a modelId, every request targets a deploymentId (the identifier of an already-deployed asset). It supports the same operations as ChatService and TimeSeriesService (chat, streaming chat, time series forecasting), plus the ability to inspect a deployment's metadata via findById.

What is a Deployment Space?

A deployment space is an IBM watsonx.ai workspace that contains deployable assets, their deployments, and associated environments. Assets (foundation models, prompt-tuned models, prompt templates) are promoted from projects into a deployment space before they can be deployed. A single asset can be deployed to multiple spaces (for example, a test space and a production space).

Once deployed, each deployment is identified by a unique deploymentId. You use this ID in every DeploymentService request instead of a modelId.

Quick Start

DeploymentService deploymentService = DeploymentService.builder()
    .baseUrl(CloudRegion.DALLAS)
    .apiKey(WATSONX_API_KEY)
    .build();

var chatRequest = DeploymentChatRequest.builder()
    .deploymentId(WATSONX_DEPLOYMENT_ID)
    .messages(UserMessage.text("Hello!"))
    .build();

var response = deploymentService.chat(chatRequest);
System.out.println(response.toAssistantMessage().content());

Overview

The DeploymentService enables you to:

Send synchronous and streaming chat requests to a deployed model.
Run time series forecasting against a deployed TTM model, with optional futureData for exogenous features.
Retrieve deployment metadata (findById) including status, inference endpoints, asset type, and hardware configuration.

Service Configuration

Basic Setup

DeploymentService deploymentService = DeploymentService.builder()
    .baseUrl(CloudRegion.DALLAS)   // or use a URL string
    .apiKey(WATSONX_API_KEY)
    .build();

All routing is done through the deploymentId in each request, so no projectId, spaceId, or modelId is required.

Builder Parameters

Parameter	Type	Required	Description
`apiKey`	String	Conditional	API key for IBM Cloud authentication
`authenticator`	Authenticator	Conditional	Custom authentication (alternative to `apiKey`)
`baseUrl`	String/CloudRegion	Yes	watsonx.ai ML endpoint
`timeout`	Duration	No	Default request timeout (default: 60 seconds)
`logRequests`	Boolean	No	Enable request logging (default: false)
`logResponses`	Boolean	No	Enable response logging (default: false)
`httpClient`	HttpClient	No	Custom HTTP client
`verifySsl`	Boolean	No	SSL certificate verification (default: true)
`parameters`	ChatParameters	No	Default chat parameters applied to every chat request
`tools`	List<Tool>	No	Default tools available to the model
`messageInterceptor`	MessageInterceptor<DeploymentChatRequest>	No	Post-processing hook for the complete assistant message
`partialResponseInterceptor`	PartialResponseInterceptor<DeploymentChatRequest>	No	Post-processing hook for each streamed content token
`toolInterceptor`	ToolInterceptor<DeploymentChatRequest>	No	Post-processing hook for function call arguments

Either apiKey or authenticator must be provided. projectId, spaceId, and modelId are ignored, and a warning is logged if they are set on a request's parameters object.

Chat operations

Synchronous Chat

var chatRequest = DeploymentChatRequest.builder()
    .deploymentId(WATSONX_DEPLOYMENT_ID)
    .messages(
        SystemMessage.of("You are a helpful assistant."),
        UserMessage.text("Hello, how are you?")
    ).build();

ChatResponse response = deploymentService.chat(chatRequest);

Streaming Chat

var chatRequest = DeploymentChatRequest.builder()
    .deploymentId(WATSONX_DEPLOYMENT_ID)
    .messages(UserMessage.text("Tell me a joke."))
    .build();

CompletableFuture<ChatResponse> future = deploymentService.chatStreaming(chatRequest,
    new ChatHandler() {
        @Override
        public void onPartialResponse(String partial, PartialChatResponse partialResponse) {
            System.out.print(partial);
        }

        @Override
        public void onCompleteResponse(ChatResponse response) {
            System.out.println("\n[Done]");
        }

        @Override
        public void onError(Throwable error) {
            error.printStackTrace();
        }
    }
);

future.join(); // wait for completion

Cancelling a Stream

Both chatStreaming and generateStreaming return a future that can be cancelled to stop the stream early:

future.cancel(true);

Cancellation aborts the response body subscription and closes the connection, so the model stops streaming. After cancel(...) returns, no further callback reaches the handler, not even onError, because stopping the stream is a decision of the caller rather than a failure. A callback that is already running is allowed to finish.

The future ends in the cancelled state, so a later get() or join() throws a CancellationException. Cancelling twice is a no-op, and so is cancelling a stream that has already completed. Calling cancel(...) from inside a callback is safe. See Chat for the full contract.

Time Series Forecasting

The DeploymentService supports time series forecasting via forecast(), with one key addition over TimeSeriesService: futureData, exogenous features known in advance for the forecast horizon (e.g. holidays, scheduled events).

InputSchema schema = InputSchema.builder()
    .timestampColumn("date")
    .addIdColumn("ID1")
    .build();

ForecastData historicalData = ForecastData.create()
    .addAll("date", "2020-01-01T00:00:00", "2020-01-01T01:00:00", "2020-01-05T01:00:00")
    .addAll("ID1", "D1", "D1", "D1")
    .addAll("TARGET1", 1.46, 2.34, 4.55);

ForecastData futureData = ForecastData.create()
    .add("date", "2021-01-01T00:00:00")
    .add("ID1", "D1")
    .add("TARGET1", 5);

TimeSeriesParameters parameters = TimeSeriesParameters.builder()
    .futureData(futureData)
    .build();

TimeSeriesRequest request = TimeSeriesRequest.builder()
    .deploymentId(WATSONX_DEPLOYMENT_ID)
    .inputSchema(schema)
    .data(historicalData)
    .parameters(parameters)
    .build();

ForecastResponse result = deploymentService.forecast(request);
System.out.println("Output data points: " + result.outputDataPoints());

futureData is only supported by DeploymentService. When using TimeSeriesService directly, it is not available.

Finding a Deployment

Use findById to inspect a deployment's metadata, status, and inference endpoints:

var request = FindByIdRequest.builder()
    .deploymentId(WATSONX_DEPLOYMENT_ID)
    .spaceId(WATSONX_SPACE_ID)
    .build();

DeploymentResource resource = deploymentService.findById(request);

FindByIdRequest Parameters

Parameter	Type	Required	Description
`deploymentId`	String	Yes	The unique deployment identifier
`projectId`	String	Conditional	Project ID where the deployment resides
`spaceId`	String	Conditional	Space ID (alternative to `projectId`)
`transactionId`	String	No	Request tracking ID

Either projectId or spaceId must be provided.

DeploymentResource

Field	Type	Description
`metadata().id()`	String	Deployment unique identifier
`metadata().name()`	String	Human-readable name
`metadata().description()`	String	Deployment description
`metadata().createdAt()`	String	Creation timestamp
`metadata().modifiedAt()`	String	Last modification timestamp
`metadata().spaceId()`	String	Space where the deployment lives
`metadata().projectId()`	String	Project where the deployment lives
`metadata().tags()`	List<String>	Tags
`entity().deployedAssetType()`	String	Type of deployed asset (`prompt_tune`, `foundation_model`, `custom_foundation_model`)
`entity().baseModelId()`	String	The underlying foundation model
`entity().status().state()`	String	Deployment state (e.g., `ready`, `failed`)
`entity().status().inference()`	List<Inference>	List of inference endpoints
`entity().status().message()`	Message	Status message with `level()` and `text()`
`entity().status().failure()`	ApiErrorResponse	Error details if state is `failed`
`entity().asset()`	ModelRel	Model asset reference with `id()` and `rev()`
`entity().promptTemplate()`	SimpleRel	Prompt template reference (if applicable)
`entity().hardwareSpec()`	HardwareSpec	Hardware specification (`id`, `name`, `numNodes`)
`entity().online().parameters()`	Map<String, Object>	Online deployment parameters (e.g., `serving_name`)
`entity().custom()`	Map<String, Object>	User-defined metadata

Deployment Spaces Documentation
Creating online deployments - how to obtain a deploymentId
Setup & Prerequisites - creating spaces and deployments
Deployments API Reference
ChatService Documentation
Time Series Service Documentation
Sample Code

What is a Deployment Space?​

Quick Start​

Overview​

Service Configuration​

Basic Setup​

Builder Parameters​

Chat operations​

Synchronous Chat​

Streaming Chat​

Cancelling a Stream​

Time Series Forecasting​

Finding a Deployment​

FindByIdRequest Parameters​

DeploymentResource​

Related Resources​