Skip to main content

API Reference

1 min read

Complete reference for the Claude API and SDK usage

title: API Reference description: Complete reference for the Claude API and SDK usage

The Claude API provides programmatic access to Claude's capabilities. This reference covers authentication, endpoints, and best practices for integrating Claude into your applications.

Overview

The Claude API uses a REST architecture with JSON request and response bodies. All requests require authentication via API key.

Base URL

Text
https://api.anthropic.com

API Versions

| Version | Status | Notes | |---------|--------|-------| | 2024-01-01 | Current | Latest stable version | | 2023-06-01 | Supported | Previous stable version | | 2023-01-01 | Deprecated | Will be removed |

Always specify the version in your requests:

Bash
curl https://api.anthropic.com/v1/messages \
  -H "anthropic-version: 2024-01-01"

Quick Start

Basic Request

Bash
curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2024-01-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Response Format

JSON
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

Available Models

| Model | ID | Best For | |-------|-----|----------| | Claude Opus 4.5 | claude-opus-4-5-20251101 | Complex reasoning, research | | Claude Sonnet 4 | claude-sonnet-4-20250514 | Balanced performance | | Claude Haiku 3.5 | claude-haiku-3-5-20241022 | Fast, simple tasks |

Core Endpoints

Messages API

The primary endpoint for conversations:

Text
POST /v1/messages

Request Body:

JSON
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [
    {"role": "user", "content": "What is the capital of France?"}
  ]
}

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | model | string | Yes | Model ID to use | | messages | array | Yes | Conversation messages | | max_tokens | integer | Yes | Maximum response length | | system | string | No | System prompt | | temperature | float | No | Randomness (0-1) | | stream | boolean | No | Enable streaming |

Streaming Responses

For real-time responses, enable streaming:

Bash
curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2024-01-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Tell me a story"}
    ]
  }'

Stream events:

Text
event: message_start
event: content_block_start
event: content_block_delta
event: content_block_stop
event: message_delta
event: message_stop

SDKs

Python

Python
from anthropic import Anthropic

client = Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

print(message.content[0].text)

TypeScript/JavaScript

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

const client = new Anthropic();

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

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

Error Handling

Error Response Format

JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive integer"
  }
}

Common Error Types

| Type | HTTP Status | Description | |------|-------------|-------------| | invalid_request_error | 400 | Invalid parameters | | authentication_error | 401 | Invalid API key | | permission_error | 403 | Insufficient permissions | | not_found_error | 404 | Resource not found | | rate_limit_error | 429 | Too many requests | | api_error | 500 | Server error | | overloaded_error | 529 | API overloaded |

Retry Strategy

TypeScript
async function callWithRetry(fn: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Rate Limits

Rate limits vary by tier:

| Tier | Requests/min | Tokens/min | |------|--------------|------------| | Free | 5 | 20,000 | | Build | 50 | 100,000 | | Scale | 1,000 | 400,000 |

Check headers for current usage:

Text
x-ratelimit-limit-requests: 50
x-ratelimit-limit-tokens: 100000
x-ratelimit-remaining-requests: 49
x-ratelimit-remaining-tokens: 99500

Best Practices

1. Use System Prompts

Set consistent behavior with system prompts:

JSON
{
  "system": "You are a helpful coding assistant. Always explain your reasoning and provide working code examples.",
  "messages": [...]
}

2. Manage Context Length

Monitor token usage and truncate when needed:

TypeScript
const MAX_CONTEXT_TOKENS = 100000;

function trimMessages(messages, maxTokens) {
  // Keep system message + recent messages
  // Estimate ~4 chars per token
}

3. Handle Streaming Properly

TypeScript
const stream = await client.messages.stream({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }]
});

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

Next Steps

Sources

Generated with AI using Claude AI by Anthropic

Model: Claude Opus 4.5 · Generated: 2025-12-09 · Build: v0.9.0-b4563d6

Edit this page on GitHub
DebuggingAuthentication