1# Claude API — Ruby
2 
3> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby.
4 
5## Installation
6 
7```bash
8gem install anthropic
9```
10 
11## Client Initialization
12 
13```ruby
14require "anthropic"
15 
16# Default (uses ANTHROPIC_API_KEY env var)
17client = Anthropic::Client.new
18 
19# Explicit API key
20client = Anthropic::Client.new(api_key: "your-api-key")
21```
22 
23---
24 
25## Basic Message Request
26 
27```ruby
28message = client.messages.create(
29  model: :"claude-opus-4-8",
30  max_tokens: 16000,
31  messages: [
32    { role: "user", content: "What is the capital of France?" }
33  ]
34)
35# content is an array of polymorphic block objects (TextBlock, ThinkingBlock,
36# ToolUseBlock, ...). .type is a Symbol — compare with :text, not "text".
37# .text raises NoMethodError on non-TextBlock entries.
38message.content.each do |block|
39  puts block.text if block.type == :text
40end
41```
42 
43---
44 
45## Extended Thinking
46 
47> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
48> **Older models:** Use `thinking: { type: "enabled", budget_tokens: N }` (must be < `max_tokens`, min 1024).
49 
50```ruby
51message = client.messages.create(
52  model: :"claude-opus-4-8",
53  max_tokens: 16000,
54  thinking: { type: "adaptive" },
55  messages: [{ role: "user", content: "Solve: 27 * 453" }]
56)
57 
58message.content.each do |block|
59  case block.type
60  when :thinking then puts "Thinking: #{block.thinking}"
61  when :text then puts "Response: #{block.text}"
62  end
63end
64```
65 
66---
67 
68## Prompt Caching
69 
70`system_:` (trailing underscore — avoids shadowing `Kernel#system`) takes an array of text blocks; set `cache_control` on the last block. Plain hashes work via the `OrHash` type alias. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
71 
72```ruby
73message = client.messages.create(
74  model: :"claude-opus-4-8",
75  max_tokens: 16000,
76  system_: [
77    { type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } }
78  ],
79  messages: [{ role: "user", content: "Summarize the key points" }]
80)
81```
82 
83For 1-hour TTL: `cache_control: { type: "ephemeral", ttl: "1h" }`. There's also a top-level `cache_control:` on `messages.create` that auto-places on the last cacheable block.
84 
85Verify hits via `message.usage.cache_creation_input_tokens` / `message.usage.cache_read_input_tokens`.
86 
87---
88 
89## Stop Details
90 
91When `stop_reason` is `:refusal`, the response includes structured `stop_details`:
92 
93```ruby
94if message.stop_reason == :refusal && message.stop_details
95  puts "Category: #{message.stop_details.category}"     # e.g. :cyber, :bio, :reasoning_extraction, :frontier_llm, or nil — see docs for the full set
96  puts "Explanation: #{message.stop_details.explanation}"
97end
98```
99 
100**Refusal fallbacks (Claude Fable 5) — opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. New `claude-fable-5` code should include the server-side `fallbacks` parameter (beta header `server-side-fallback-2026-06-01`, `fallbacks: [{model: "claude-opus-4-8"}]` on the beta messages call) by default. The exact Ruby binding (and the client-side middleware for providers without server-side support) is not documented here — WebFetch the Ruby SDK repo's `examples/` from `shared/live-sources.md`; full semantics in `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason.
101 
102---
103 
104## Beta Features
105 
106`betas:` is only valid on `client.beta.messages.create`, not the non-beta path.
107 
108### Task budgets
109 
110```ruby
111response = client.beta.messages.create(
112  model: :"claude-opus-4-8",
113  max_tokens: 16000,
114  output_config: { task_budget: { type: :tokens, total: 64_000 } },
115  tools: [...],
116  messages: [...],
117  betas: ["task-budgets-2026-03-13"]
118)
119```
120 
121---
122 
123## Error Type
124 
125`APIStatusError` exposes a `.type` field for programmatic error classification:
126 
127```ruby
128begin
129  client.messages.create(...)
130rescue Anthropic::Errors::APIStatusError => e
131  puts e.type  # :rate_limit_error, :overloaded_error, etc.
132end
133```
134