0
# Anthropic Java SDK
1

2
The Anthropic Java SDK provides convenient access to the Anthropic REST API from applications written in Java. It offers type-safe, idiomatic Java interfaces for Claude's advanced language capabilities including message generation, streaming responses, tool use, structured outputs, and deployment across multiple platforms (Anthropic API, AWS Bedrock, Google Vertex AI).
3

4
## Package Information
5

6
- **Package Name**: com.anthropic/anthropic-java
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Minimum Java Version**: Java 8
10
- **Current Version**: 2.11.0
11

12
### Installation
13

14
**Gradle:**
15

16
```kotlin
17
implementation("com.anthropic:anthropic-java:2.11.0")
18
```
19

20
**Maven:**
21

22
```xml
23
<dependency>
24
  <groupId>com.anthropic</groupId>
25
  <artifactId>anthropic-java</artifactId>
26
  <version>2.11.0</version>
27
</dependency>
28
```
29

30
## Core Imports
31

32
```java { .api }
33
import com.anthropic.client.AnthropicClient;
34
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
35
import com.anthropic.models.messages.Message;
36
import com.anthropic.models.messages.MessageCreateParams;
37
import com.anthropic.models.messages.Model;
38
```
39

40
## Basic Usage
41

42
```java
43
import com.anthropic.client.AnthropicClient;
44
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
45
import com.anthropic.models.messages.Message;
46
import com.anthropic.models.messages.MessageCreateParams;
47
import com.anthropic.models.messages.Model;
48

49
// Create client from environment (ANTHROPIC_API_KEY)
50
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
51

52
// Build message parameters
53
MessageCreateParams params = MessageCreateParams.builder()
54
    .maxTokens(1024L)
55
    .addUserMessage("Hello, Claude")
56
    .model(Model.CLAUDE_SONNET_4_5)
57
    .build();
58

59
// Create message
60
Message message = client.messages().create(params);
61

62
// Access response
63
System.out.println(message.content());
64
```
65

66
## Architecture
67

68
The SDK is organized into several key components:
69

70
- **Client Layer**: `AnthropicClient` (synchronous) and `AnthropicClientAsync` (asynchronous)
71
- **Service Layer**: Type-safe service interfaces for Messages, Models, Completions, and Beta APIs
72
- **Model Layer**: Immutable request/response models with builder patterns
73
- **Platform Adapters**: Backend implementations for Direct API, AWS Bedrock, and Google Vertex AI
74
- **HTTP Integration**: OkHttp-based HTTP client with extensibility for custom implementations
75

76
## Capabilities
77

78
### Client Setup and Configuration
79

80
Create and configure the Anthropic client with authentication, timeouts, retries, and proxy settings.
81

82
```java { .api }
83
package com.anthropic.client.okhttp;
84

85
public final class AnthropicOkHttpClient {
86
    public static Builder builder();
87
    public static AnthropicClient fromEnv();
88

89
    public static final class Builder {
90
        public Builder fromEnv();
91
        public Builder apiKey(String apiKey);
92
        public Builder authToken(String authToken);
93
        public Builder baseUrl(String baseUrl);
94
        public Builder backend(Backend backend);
95
        public Builder timeout(Duration timeout);
96
        public Builder maxRetries(int maxRetries);
97
        public Builder proxy(Proxy proxy);
98
        public AnthropicClient build();
99
    }
100
}
101
```
102

103
```java { .api }
104
package com.anthropic.client;
105

106
public interface AnthropicClient {
107
    AnthropicClientAsync async();
108
    WithRawResponse withRawResponse();
109
    AnthropicClient withOptions(Consumer<ClientOptions.Builder> modifier);
110
    MessageService messages();
111
    ModelService models();
112
    CompletionService completions();
113
    BetaService beta();
114
    void close();
115
}
116
```
117

118
[Client Setup and Configuration](./client-setup.md)
119

120
### Message Creation
121

122
Send messages to Claude models with full control over system prompts, conversation history, model selection, and generation parameters.
123

124
```java { .api }
125
package com.anthropic.services.blocking;
126

127
public interface MessageService {
128
    Message create(MessageCreateParams params);
129
    Message create(MessageCreateParams params, RequestOptions requestOptions);
130
    StreamResponse<RawMessageStreamEvent> createStreaming(MessageCreateParams params);
131
    MessageTokensCount countTokens(MessageCountTokensParams params);
132
    BatchService batches();
133
}
134
```
135

136
```java { .api }
137
package com.anthropic.models.messages;
138

139
public final class MessageCreateParams {
140
    public static Builder builder();
141

142
    public static final class Builder {
143
        public Builder maxTokens(long maxTokens);
144
        public Builder messages(List<MessageParam> messages);
145
        public Builder addMessage(MessageParam message);
146
        public Builder addUserMessage(String content);
147
        public Builder addAssistantMessage(String content);
148
        public Builder model(Model model);
149
        public Builder model(String value);
150
        public Builder system(String system);
151
        public Builder temperature(double temperature);
152
        public Builder topK(long topK);
153
        public Builder topP(double topP);
154
        public Builder stopSequences(List<String> stopSequences);
155
        public Builder metadata(Metadata metadata);
156
        public Builder thinking(ThinkingConfigParam thinking);
157
        public Builder enabledThinking(long budgetTokens);
158
        public Builder toolChoice(ToolChoice toolChoice);
159
        public Builder tools(List<ToolUnion> tools);
160
        public Builder addTool(Tool tool);
161
        public Builder serviceTier(ServiceTier serviceTier);
162
        public MessageCreateParams build();
163
    }
164
}
165
```
166

167
```java { .api }
168
package com.anthropic.models.messages;
169

170
public final class Message {
171
    public String id();
172
    public List<ContentBlock> content();
173
    public Model model();
174
    public Optional<StopReason> stopReason();
175
    public Optional<String> stopSequence();
176
    public Usage usage();
177

178
    public static Builder builder();
179
}
180
```
181

182
```java { .api }
183
package com.anthropic.models.messages;
184

185
public enum Model {
186
    // Claude 4.5 Sonnet - Best for agents and coding
187
    CLAUDE_SONNET_4_5("claude-sonnet-4-5"),
188
    CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929"),
189

190
    // Claude 4 Sonnet - High-performance with extended thinking
191
    CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514"),
192
    CLAUDE_SONNET_4_0("claude-sonnet-4-0"),
193
    CLAUDE_4_SONNET_20250514("claude-4-sonnet-20250514"),
194

195
    // Claude 4 Opus - Most capable models
196
    CLAUDE_OPUS_4_0("claude-opus-4-0"),
197
    CLAUDE_OPUS_4_20250514("claude-opus-4-20250514"),
198
    CLAUDE_4_OPUS_20250514("claude-4-opus-20250514"),
199
    CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805"),
200

201
    // Claude 4.5 Haiku - Hybrid model with instant responses and extended thinking
202
    CLAUDE_HAIKU_4_5("claude-haiku-4-5"),
203
    CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001"),
204

205
    // Claude 3.5 Haiku - Fastest and most compact
206
    CLAUDE_3_5_HAIKU_LATEST("claude-3-5-haiku-latest"),
207
    CLAUDE_3_5_HAIKU_20241022("claude-3-5-haiku-20241022"),
208

209
    // Claude 3.7 Sonnet - High-performance with early extended thinking (DEPRECATED)
210
    // End-of-life: February 19, 2026
211
    CLAUDE_3_7_SONNET_LATEST("claude-3-7-sonnet-latest"),
212
    CLAUDE_3_7_SONNET_20250219("claude-3-7-sonnet-20250219"),
213

214
    // Claude 3 Opus - Excels at writing and complex tasks (DEPRECATED)
215
    // End-of-life: January 5, 2026
216
    CLAUDE_3_OPUS_LATEST("claude-3-opus-latest"),
217
    CLAUDE_3_OPUS_20240229("claude-3-opus-20240229"),
218

219
    // Claude 3 Haiku - Previous fast and cost-effective model
220
    CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307");
221

222
    public static Model of(String value);
223
    public String asString();
224
}
225
```
226

227
[Message Creation](./messages.md)
228

229
### Streaming Responses
230

231
Stream message generation in real-time, receiving content as it's generated rather than waiting for the complete response.
232

233
```java { .api }
234
package com.anthropic.core.http;
235

236
public interface StreamResponse<T> extends Closeable {
237
    Stream<T> stream();
238
    void close();
239
}
240
```
241

242
```java { .api }
243
package com.anthropic.models.messages;
244

245
public final class RawMessageStreamEvent {
246
    public Optional<RawMessageStartEvent> messageStart();
247
    public Optional<RawMessageDeltaEvent> messageDelta();
248
    public Optional<RawMessageStopEvent> messageStop();
249
    public Optional<RawContentBlockStartEvent> contentBlockStart();
250
    public Optional<RawContentBlockDeltaEvent> contentBlockDelta();
251
    public Optional<RawContentBlockStopEvent> contentBlockStop();
252

253
    public boolean isMessageStart();
254
    public boolean isContentBlockDelta();
255
}
256
```
257

258
```java { .api }
259
package com.anthropic.helpers;
260

261
public final class MessageAccumulator {
262
    public static MessageAccumulator create();
263

264
    public RawMessageStreamEvent accumulate(RawMessageStreamEvent event);
265
    public Message message();
266
}
267
```
268

269
[Streaming Responses](./streaming.md)
270

271
### Tool Use and Function Calling
272

273
Enable Claude to use external tools and functions, with automatic parameter validation and result handling.
274

275
```java { .api }
276
package com.anthropic.models.messages;
277

278
public final class Tool {
279
    public static Builder builder();
280

281
    public static final class Builder {
282
        public Builder inputSchema(InputSchema inputSchema);
283
        public Builder name(String name);
284
        public Builder description(String description);
285
        public Builder cacheControl(CacheControlEphemeral cacheControl);
286
        public Tool build();
287
    }
288

289
    public InputSchema inputSchema();
290
    public String name();
291
    public Optional<String> description();
292

293
    public static final class InputSchema {
294
        public static Builder builder();
295
    }
296
}
297
```
298

299
```java { .api }
300
package com.anthropic.models.messages;
301

302
public final class ToolChoice {
303
    public static ToolChoice ofAuto(ToolChoiceAuto auto);
304
    public static ToolChoice ofAny(ToolChoiceAny any);
305
    public static ToolChoice ofTool(ToolChoiceTool tool);
306
    public static ToolChoice ofNone(ToolChoiceNone none);
307

308
    public Optional<ToolChoiceAuto> auto();
309
    public Optional<ToolChoiceAny> any();
310
    public Optional<ToolChoiceTool> tool();
311
    public boolean isAuto();
312
    public boolean isAny();
313
    public boolean isTool();
314
}
315
```
316

317
```java { .api }
318
package com.anthropic.models.messages;
319

320
public final class ToolUseBlock {
321
    public String id();
322
    public String name();
323
    public Object input();
324

325
    public static Builder builder();
326
}
327
```
328

329
```java { .api }
330
package com.anthropic.models.messages;
331

332
public final class ToolResultBlockParam {
333
    public static Builder builder();
334

335
    public static final class Builder {
336
        public Builder toolUseId(String toolUseId);
337
        public Builder content(String content);
338
        public Builder contentAsJson(Object content);
339
        public Builder isError(boolean isError);
340
        public ToolResultBlockParam build();
341
    }
342
}
343
```
344

345
[Tool Use and Function Calling](./tools.md)
346

347
### Structured Outputs
348

349
Generate responses that conform to JSON schemas, automatically derived from Java classes or explicitly defined.
350

351
```java { .api }
352
package com.anthropic.models.beta.messages;
353

354
public final class MessageCreateParams {
355
    public static Builder builder();
356

357
    public static final class Builder {
358
        public <T> StructuredMessageCreateParams.Builder<T> outputFormat(Class<T> clazz);
359
        public <T> StructuredMessageCreateParams.Builder<T> outputFormat(
360
            Class<T> clazz,
361
            JsonSchemaLocalValidation validation
362
        );
363
        public Builder outputFormat(BetaJsonOutputFormat outputFormat);
364
    }
365
}
366
```
367

368
```java { .api }
369
package com.anthropic.models.beta.messages;
370

371
public final class StructuredMessageCreateParams<T> {
372
    public static final class Builder<T> {
373
        public Builder<T> model(Model model);
374
        public Builder<T> maxTokens(long maxTokens);
375
        public Builder<T> addUserMessage(String content);
376
        public Builder<T> system(String system);
377
        public Builder<T> temperature(double temperature);
378
        public StructuredMessageCreateParams<T> build();
379
    }
380
}
381
```
382

383
```java { .api }
384
package com.anthropic.models.beta.messages;
385

386
public final class StructuredMessage<T> {
387
    public String id();
388
    public List<StructuredContentBlock<T>> content();
389
    public Model model();
390
    public Usage usage();
391
}
392
```
393

394
```java { .api }
395
package com.anthropic.core;
396

397
public enum JsonSchemaLocalValidation {
398
    YES,
399
    NO
400
}
401
```
402

403
[Structured Outputs](./structured-outputs.md)
404

405
### Platform Adapters
406

407
Deploy Claude on AWS Bedrock or Google Vertex AI using platform-specific authentication and configuration.
408

409
**AWS Bedrock:**
410

411
```java { .api }
412
package com.anthropic.bedrock.backends;
413

414
public final class BedrockBackend implements Backend {
415
    public static Builder builder();
416
    public static BedrockBackend fromEnv();
417

418
    public static final class Builder {
419
        public Builder fromEnv();
420
        public Builder fromEnv(AwsCredentialsProvider provider);
421
        public Builder awsCredentials(AwsCredentials credentials);
422
        public Builder awsCredentialsProvider(AwsCredentialsProvider provider);
423
        public Builder apiKey(String apiKey);
424
        public Builder region(Region region);
425
        public BedrockBackend build();
426
    }
427
}
428
```
429

430
**Google Vertex AI:**
431

432
```java { .api }
433
package com.anthropic.vertex.backends;
434

435
public final class VertexBackend implements Backend {
436
    public static Builder builder();
437
    public static VertexBackend fromEnv();
438

439
    public static final class Builder {
440
        public Builder fromEnv();
441
        public Builder googleCredentials(GoogleCredentials credentials);
442
        public Builder region(String region);
443
        public Builder project(String project);
444
        public VertexBackend build();
445
    }
446
}
447
```
448

449
[Platform Adapters](./platform-adapters.md)
450

451
### Error Handling
452

453
Handle API errors with a comprehensive exception hierarchy for different failure scenarios.
454

455
```java { .api }
456
package com.anthropic.errors;
457

458
public class AnthropicException extends RuntimeException {
459
    public AnthropicException(String message);
460
    public AnthropicException(String message, Throwable cause);
461
}
462
```
463

464
```java { .api }
465
package com.anthropic.errors;
466

467
public class AnthropicServiceException extends AnthropicException {
468
    public int statusCode();
469
    public Headers headers();
470
}
471
```
472

473
```java { .api }
474
package com.anthropic.errors;
475

476
public final class BadRequestException extends AnthropicServiceException {}
477
public final class UnauthorizedException extends AnthropicServiceException {}
478
public final class PermissionDeniedException extends AnthropicServiceException {}
479
public final class NotFoundException extends AnthropicServiceException {}
480
public final class RateLimitException extends AnthropicServiceException {}
481
public final class InternalServerException extends AnthropicServiceException {}
482
```
483

484
```java { .api }
485
package com.anthropic.errors;
486

487
public final class AnthropicIoException extends AnthropicException {}
488
public final class AnthropicInvalidDataException extends AnthropicException {}
489
```
490

491
[Error Handling](./errors.md)
492

493
## Core Types
494

495
### Content Blocks
496

497
```java { .api }
498
package com.anthropic.models.messages;
499

500
public final class ContentBlock {
501
    public static ContentBlock ofText(TextBlock text);
502
    public static ContentBlock ofThinking(ThinkingBlock thinking);
503
    public static ContentBlock ofToolUse(ToolUseBlock toolUse);
504

505
    public Optional<TextBlock> text();
506
    public Optional<ThinkingBlock> thinking();
507
    public Optional<ToolUseBlock> toolUse();
508

509
    public boolean isText();
510
    public boolean isThinking();
511
    public boolean isToolUse();
512

513
    public TextBlock asText();
514
    public ThinkingBlock asThinking();
515
    public ToolUseBlock asToolUse();
516

517
    public <T> T accept(Visitor<T> visitor);
518

519
    public interface Visitor<T> {
520
        T visitText(TextBlock text);
521
        T visitThinking(ThinkingBlock thinking);
522
        T visitToolUse(ToolUseBlock toolUse);
523
    }
524
}
525
```
526

527
```java { .api }
528
package com.anthropic.models.messages;
529

530
public final class TextBlock {
531
    public String text();
532
    public String type();
533

534
    public static Builder builder();
535
}
536
```
537

538
```java { .api }
539
package com.anthropic.models.messages;
540

541
public final class ThinkingBlock {
542
    public String thinking();
543
    public String type();
544

545
    public static Builder builder();
546
}
547
```
548

549
### Message Parameters
550

551
```java { .api }
552
package com.anthropic.models.messages;
553

554
public final class MessageParam {
555
    public Role role();
556
    public List<ContentBlockParam> content();
557

558
    public static Builder builder();
559

560
    public enum Role {
561
        USER("user"),
562
        ASSISTANT("assistant");
563

564
        public static Role of(String value);
565
        public String asString();
566
    }
567
}
568
```
569

570
### Usage Information
571

572
```java { .api }
573
package com.anthropic.models.messages;
574

575
public final class Usage {
576
    public long inputTokens();
577
    public long outputTokens();
578
    public Optional<Long> cacheCreationInputTokens();
579
    public Optional<Long> cacheReadInputTokens();
580

581
    public static Builder builder();
582
}
583
```
584

585
### Stop Reasons
586

587
```java { .api }
588
package com.anthropic.models.messages;
589

590
public enum StopReason {
591
    END_TURN("end_turn"),
592
    MAX_TOKENS("max_tokens"),
593
    STOP_SEQUENCE("stop_sequence"),
594
    TOOL_USE("tool_use"),
595
    PAUSE_TURN("pause_turn"),
596
    REFUSAL("refusal");
597

598
    public static StopReason of(String value);
599
    public String asString();
600
}
601
```
602

603
### Request Options
604

605
```java { .api }
606
package com.anthropic.core;
607

608
public final class RequestOptions {
609
    public static Builder builder();
610

611
    public static final class Builder {
612
        public Builder timeout(Duration timeout);
613
        public Builder responseValidation(boolean validation);
614
        public RequestOptions build();
615
    }
616
}
617
```
618

619
### Client Options
620

621
```java { .api }
622
package com.anthropic.core;
623

624
public final class ClientOptions {
625
    public HttpClient httpClient();
626
    public String baseUrl();
627
    public Headers headers();
628
    public Duration timeout();
629
    public int maxRetries();
630
    public boolean responseValidation();
631

632
    public static Builder builder();
633

634
    public static final class Builder {
635
        public Builder httpClient(HttpClient httpClient);
636
        public Builder baseUrl(String baseUrl);
637
        public Builder timeout(Duration timeout);
638
        public Builder timeout(Timeout timeout);
639
        public Builder maxRetries(int maxRetries);
640
        public Builder responseValidation(boolean validation);
641
        public Builder putHeader(String name, String value);
642
        public Builder putQueryParam(String key, String value);
643
        public ClientOptions build();
644
    }
645
}
646
```
647