1# Claude API — cURL / Raw HTTP
2 
3Use these examples when the user needs raw HTTP requests or is working in a language without an official SDK.
4 
5## Setup
6 
7```bash
8export ANTHROPIC_API_KEY="your-api-key"
9```
10 
11---
12 
13## Basic Message Request
14 
15```bash
16curl https://api.anthropic.com/v1/messages \
17  -H "Content-Type: application/json" \
18  -H "x-api-key: $ANTHROPIC_API_KEY" \
19  -H "anthropic-version: 2023-06-01" \
20  -d '{
21    "model": "claude-opus-4-7",
22    "max_tokens": 16000,
23    "messages": [
24      {"role": "user", "content": "What is the capital of France?"}
25    ]
26  }'
27```
28 
29### Parsing the response
30 
31Use `jq` to extract fields from the JSON response. Do not use `grep`/`sed` —
32JSON strings can contain any character and regex parsing will break on quotes,
33escapes, or multi-line content.
34 
35```bash
36# Capture the response, then extract fields
37response=$(curl -s https://api.anthropic.com/v1/messages \
38  -H "Content-Type: application/json" \
39  -H "x-api-key: $ANTHROPIC_API_KEY" \
40  -H "anthropic-version: 2023-06-01" \
41  -d '{"model":"claude-opus-4-7","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}')
42 
43# Print the first text block (-r strips the JSON quotes)
44echo "$response" | jq -r '.content[0].text'
45 
46# Read usage fields
47input_tokens=$(echo "$response" | jq -r '.usage.input_tokens')
48output_tokens=$(echo "$response" | jq -r '.usage.output_tokens')
49 
50# Read stop reason (for tool-use loops)
51stop_reason=$(echo "$response" | jq -r '.stop_reason')
52 
53# Extract all text blocks (content is an array; filter to type=="text")
54echo "$response" | jq -r '.content[] | select(.type == "text") | .text'
55```
56 
57 
58---
59 
60## Streaming (SSE)
61 
62```bash
63curl https://api.anthropic.com/v1/messages \
64  -H "Content-Type: application/json" \
65  -H "x-api-key: $ANTHROPIC_API_KEY" \
66  -H "anthropic-version: 2023-06-01" \
67  -d '{
68    "model": "claude-opus-4-7",
69    "max_tokens": 64000,
70    "stream": true,
71    "messages": [{"role": "user", "content": "Write a haiku"}]
72  }'
73```
74 
75The response is a stream of Server-Sent Events:
76 
77```
78event: message_start
79data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}}
80 
81event: content_block_start
82data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
83 
84event: content_block_delta
85data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
86 
87event: content_block_stop
88data: {"type":"content_block_stop","index":0}
89 
90event: message_delta
91data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}
92 
93event: message_stop
94data: {"type":"message_stop"}
95```
96 
97---
98 
99## Tool Use
100 
101```bash
102curl https://api.anthropic.com/v1/messages \
103  -H "Content-Type: application/json" \
104  -H "x-api-key: $ANTHROPIC_API_KEY" \
105  -H "anthropic-version: 2023-06-01" \
106  -d '{
107    "model": "claude-opus-4-7",
108    "max_tokens": 16000,
109    "tools": [{
110      "name": "get_weather",
111      "description": "Get current weather for a location",
112      "input_schema": {
113        "type": "object",
114        "properties": {
115          "location": {"type": "string", "description": "City name"}
116        },
117        "required": ["location"]
118      }
119    }],
120    "messages": [{"role": "user", "content": "What is the weather in Paris?"}]
121  }'
122```
123 
124When Claude responds with a `tool_use` block, send the result back:
125 
126```bash
127curl https://api.anthropic.com/v1/messages \
128  -H "Content-Type: application/json" \
129  -H "x-api-key: $ANTHROPIC_API_KEY" \
130  -H "anthropic-version: 2023-06-01" \
131  -d '{
132    "model": "claude-opus-4-7",
133    "max_tokens": 16000,
134    "tools": [{
135      "name": "get_weather",
136      "description": "Get current weather for a location",
137      "input_schema": {
138        "type": "object",
139        "properties": {
140          "location": {"type": "string", "description": "City name"}
141        },
142        "required": ["location"]
143      }
144    }],
145    "messages": [
146      {"role": "user", "content": "What is the weather in Paris?"},
147      {"role": "assistant", "content": [
148        {"type": "text", "text": "Let me check the weather."},
149        {"type": "tool_use", "id": "toolu_abc123", "name": "get_weather", "input": {"location": "Paris"}}
150      ]},
151      {"role": "user", "content": [
152        {"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "72°F and sunny"}
153      ]}
154    ]
155  }'
156```
157 
158---
159 
160## Prompt Caching
161 
162Put `cache_control` on the last block of the stable prefix. See `shared/prompt-caching.md` for placement patterns and the silent-invalidator audit checklist.
163 
164```bash
165curl https://api.anthropic.com/v1/messages \
166  -H "Content-Type: application/json" \
167  -H "x-api-key: $ANTHROPIC_API_KEY" \
168  -H "anthropic-version: 2023-06-01" \
169  -d '{
170    "model": "claude-opus-4-7",
171    "max_tokens": 16000,
172    "system": [
173      {"type": "text", "text": "<large shared prompt...>", "cache_control": {"type": "ephemeral"}}
174    ],
175    "messages": [{"role": "user", "content": "Summarize the key points"}]
176  }'
177```
178 
179For 1-hour TTL: `"cache_control": {"type": "ephemeral", "ttl": "1h"}`. Top-level `"cache_control"` on the request body auto-places on the last cacheable block. Verify hits via the response `usage.cache_creation_input_tokens` / `usage.cache_read_input_tokens` fields.
180 
181---
182 
183## Extended Thinking
184 
185> **Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Opus 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
186> **Older models:** Use `"type": "enabled"` with `"budget_tokens": N` (must be < `max_tokens`, min 1024).
187 
188```bash
189# Opus 4.7 / 4.6: adaptive thinking (recommended)
190curl https://api.anthropic.com/v1/messages \
191  -H "Content-Type: application/json" \
192  -H "x-api-key: $ANTHROPIC_API_KEY" \
193  -H "anthropic-version: 2023-06-01" \
194  -d '{
195    "model": "claude-opus-4-7",
196    "max_tokens": 16000,
197    "thinking": {
198      "type": "adaptive"
199    },
200    "output_config": {
201      "effort": "high"
202    },
203    "messages": [{"role": "user", "content": "Solve this step by step..."}]
204  }'
205```
206 
207---
208 
209## Required Headers
210 
211| Header              | Value              | Description                |
212| ------------------- | ------------------ | -------------------------- |
213| `Content-Type`      | `application/json` | Required                   |
214| `x-api-key`         | Your API key       | Authentication             |
215| `anthropic-version` | `2023-06-01`       | API version                |
216| `anthropic-beta`    | Beta feature IDs   | Required for beta features |
217