Claude API (Anthropic Messages API)

Status: Production Ready Last Updated: 2025-10-25 Dependencies: None (standalone API skill) Latest Versions: @anthropic-ai/sdk@0.67.0

Quick Start (5 Minutes)

1. Get API Key

# Sign up at https://console.anthropic.com/
# Navigate to API Keys section
# Create new key and save securely
export ANTHROPIC_API_KEY="sk-ant-..."

Why this matters:

• API key required for all requests
• Keep secure (never commit to git)
• Use environment variables

2. Install SDK (Node.js)

npm install @anthropic-ai/sdk

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello, Claude!' }],
});

console.log(message.content[0].text);

CRITICAL:

• Always use server-side (never expose API key in client code)
• Set max_tokens (required parameter)
• Model names are versioned (use latest stable)

3. Or Use Direct API (Cloudflare Workers)

// No SDK needed - use fetch()
const response = await fetch('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: {
    'x-api-key': env.ANTHROPIC_API_KEY,
    'anthropic-version': '2023-06-01',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
});

const data = await response.json();

The Complete Claude API Reference

Table of Contents

1. Core API
2. Streaming Responses
3. Prompt Caching
4. Tool Use (Function Calling)
5. Vision (Image Understanding)
6. Extended Thinking Mode
7. Rate Limits
8. Error Handling
9. Platform Integrations
10. Known Issues

Core API (Messages API)

Available Models (October 2025)

Basic Message Creation

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Explain quantum computing in simple terms' }
  ],
});

console.log(message.content[0].text);

Multi-Turn Conversations

const messages = [
  { role: 'user', content: 'What is the capital of France?' },
  { role: 'assistant', content: 'The capital of France is Paris.' },
  { role: 'user', content: 'What is its population?' },
];

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages,
});

System Prompts

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: 'You are a helpful Python coding assistant. Always provide type hints and docstrings.',
  messages: [
    { role: 'user', content: 'Write a function to sort a list' }
  ],
});

CRITICAL:

• System prompt MUST come before messages array
• System prompt sets behavior for entire conversation
• Can be 1-10k tokens (affects context window)

Streaming Responses (SSE)

Using SDK Stream Helper

const stream = anthropic.messages.stream({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a short story' }],
});

// Method 1: Event listeners
stream
  .on('text', (text) => {
    process.stdout.write(text);
  })
  .on('message', (message) => {
    console.log('\n\nFinal message:', message);
  })
  .on('error', (error) => {
    console.error('Stream error:', error);
  });

// Wait for completion
await stream.finalMessage();

Streaming with Manual Iteration

const stream = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Explain AI' }],
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
    process.stdout.write(event.delta.text);
  }
}

Streaming Event Types

Cloudflare Workers Streaming

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await fetch('https://api.anthropic.com/v1/messages', {
      method: 'POST',
      headers: {
        'x-api-key': env.ANTHROPIC_API_KEY,
        'anthropic-version': '2023-06-01',
        'content-type': 'application/json',
      },
      body: JSON.stringify({
        model: 'claude-sonnet-4-5-20250929',
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Hello!' }],
        stream: true,
      }),
    });

    // Return SSE stream directly
    return new Response(response.body, {
      headers: {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive',
      },
    });
  },
};

CRITICAL:

• Errors can occur AFTER initial 200 response
• Always implement error event handlers
• Use stream.abort() to cancel
• Set proper Content-Type headers

Prompt Caching (⭐ 90% Cost Savings)

Overview

Prompt caching allows you to cache frequently used context (system prompts, documents, codebases) to:

• Reduce costs by 90% (cache reads = 10% of input token price)
• Reduce latency by 85% (time to first token)
• Cache lifetime: 5 minutes (default) or 1 hour (configurable)

Minimum Requirements

• Claude 3.5 Sonnet: 1,024 tokens minimum
• Claude 3.5 Haiku: 2,048 tokens minimum

Basic Prompt Caching

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: 'You are an AI assistant analyzing the following codebase...',
    },
    {
      type: 'text',
      text: LARGE_CODEBASE_CONTENT, // 50k tokens
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [
    { role: 'user', content: 'Explain the auth module' }
  ],
});

// Check cache usage
console.log('Cache read tokens:', message.usage.cache_read_input_tokens);
console.log('Cache creation tokens:', message.usage.cache_creation_input_tokens);

Caching in Messages

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Analyze this documentation:',
        },
        {
          type: 'text',
          text: LONG_DOCUMENTATION, // 20k tokens
          cache_control: { type: 'ephe