Claude API cURL Guide

<!-- name: 'Data: Claude API reference — cURL' description: Raw API reference for Claude API for use with cURL or else Raw HTTP ccVersion: 2.1.111 --> # Claude API — cURL / Raw HTTP Use these examples when the user needs raw HTTP requests or is working in a language without an official SDK. ## Setup ```bash export ANTHROPIC_API_KEY="your-api-key" ``` --- ## Basic Message Request ```bash curl https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "{{OPUS_ID}}", "max_tokens": 16000, "messages": [ {"role": "user", "content": "What is the capital of France?"} ] }' ``` ### Parsing the response Use `jq` to extract fields from the JSON response. Do not use `grep`/`sed` — JSON strings can contain any character and regex parsing will break on quotes, escapes, or multi-line content. ```bash # Capture the response, then extract fields response=$(curl -s https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{"model":"{{OPUS_ID}}","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}') # Print the first text block (-r strips the JSON quotes) echo "$response" | jq -r '.content[0].text' # Read usage fields input_tokens=$(echo "$response" | jq -r '.usage.input_tokens') output_tokens=$(echo "$response" | jq -r '.usage.output_tokens') # Read stop reason (for tool-use loops) stop_reason=$(echo "$response" | jq -r '.stop_reason') # Extract all text blocks (content is an array; filter to type=="text") echo "$response" | jq -r '.content[] | select(.type == "text") | .text' ``` --- ## Streaming (SSE) ```bash curl https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "{{OPUS_ID}}", "max_tokens": 64000, "stream": true, "messages": [{"role": "user", "content": "Write a haiku"}] }' ``` The response is a stream of Server-Sent Events: ``` event: message_start data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}} event: content_block_start data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} event: content_block_delta data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}} event: content_block_stop data: {"type":"content_block_stop","index":0} event: message_delta data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}} event: message_stop data: {"type":"message_stop"} ``` --- ## Tool Use ```bash curl https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "{{OPUS_ID}}", "max_tokens": 16000, "tools": [{ "name": "get_weather", "description": "Get current weather for a location", "input_schema": { "type": "object", "properties": { "location": {"type": "string", "description": "City name"} }, "required": ["location"] } }], "messages": [{"role": "user", "content": "What is the weather in Paris?"}] }' ``` When Claude responds with a `tool_use` block, send the result back: ```bash curl https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "{{OPUS_ID}}", "max_tokens": 16000, "tools": [{ "name": "get_weather", "description": "Get current weather for a location", "input_schema": { "type": "object", "properties": { "location": {"type": "string", "description": "City name"} }, "required": ["location"] } }], "messages": [ {"role": "user", "content": "What is the weather in Paris?"}, {"role": "assistant", "content": [ {"type": "text", "text": "Let me check the weather."}, {"type": "tool_use", "id": "toolu_abc123", "name": "get_weather", "input": {"location": "Paris"}} ]}, {"role": "user", "content": [ {"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "72°F and sunny"} ]} ] }' ``` --- ## Prompt Caching Put `cache_control` on the last block of the stable prefix. See `shared/prompt-caching.md` for placement patterns and the silent-invalidator audit checklist. ```bash curl https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "{{OPUS_ID}}", "max_tokens": 16000, "system": [ {"type": "text", "text": "<large shared prompt...>", "cache_control": {"type": "ephemeral"}} ], "messages": [{"role": "user", "content": "Summarize the key points"}] }' ``` For 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. --- ## Extended Thinking > **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. > **Older models:** Use `"type": "enabled"` with `"budget_tokens": N` (must be < `max_tokens`, min 1024). ```bash # Opus 4.7 / 4.6: adaptive thinking (recommended) curl https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "{{OPUS_ID}}", "max_tokens": 16000, "thinking": { "type": "adaptive" }, "output_config": { "effort": "high" }, "messages": [{"role": "user", "content": "Solve this step by step..."}] }' ``` --- ## Required Headers | Header | Value | Description | | ------------------- | ------------------ | -------------------------- | | `Content-Type` | `application/json` | Required | | `x-api-key` | Your API key | Authentication | | `anthropic-version` | `2023-06-01` | API version | | `anthropic-beta` | Beta feature IDs | Required for beta features |