7.4 KiB
7.4 KiB
API Reference
API endpoints and programmatic access to Claude Code functionality.
Admin API
Usage Reports
Get Claude Code Usage Report:
GET /v1/admin/claude-code/usage
Query parameters:
start_date: Start date (YYYY-MM-DD)end_date: End date (YYYY-MM-DD)user_id: Filter by userworkspace_id: Filter by workspace
Response:
{
"usage": [
{
"date": "2025-11-06",
"user_id": "user-123",
"requests": 150,
"tokens": 45000,
"cost": 12.50
}
]
}
Example:
curl https://api.anthropic.com/v1/admin/claude-code/usage \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d start_date=2025-11-01 \
-d end_date=2025-11-06
Cost Reports
Get Cost Report:
GET /v1/admin/usage/cost
Query parameters:
start_date: Start dateend_date: End dategroup_by:user|project|model
Response:
{
"costs": [
{
"group": "user-123",
"input_tokens": 100000,
"output_tokens": 50000,
"cost": 25.00
}
],
"total": 250.00
}
User Management
List Users:
GET /v1/admin/users
Get User:
GET /v1/admin/users/{user_id}
Update User:
PATCH /v1/admin/users/{user_id}
Remove User:
DELETE /v1/admin/users/{user_id}
Messages API
Create Message
Endpoint:
POST /v1/messages
Request:
{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "Explain this code"
}
]
}
With Skills:
{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 4096,
"skills": [
{
"type": "custom",
"custom": {
"name": "code-reviewer",
"description": "Reviews code quality",
"instructions": "Check for bugs, security issues..."
}
}
],
"messages": [...]
}
Response:
{
"id": "msg_123",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "This code implements..."
}
],
"usage": {
"input_tokens": 100,
"output_tokens": 200
}
}
Stream Messages
Streaming response:
{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 4096,
"stream": true,
"messages": [...]
}
Server-sent events:
event: message_start
data: {"type":"message_start","message":{...}}
event: content_block_delta
data: {"type":"content_block_delta","delta":{"text":"Hello"}}
event: message_stop
data: {"type":"message_stop"}
Count Tokens
Endpoint:
POST /v1/messages/count_tokens
Request:
{
"model": "claude-sonnet-4-5-20250929",
"messages": [
{
"role": "user",
"content": "Count these tokens"
}
]
}
Response:
{
"input_tokens": 15
}
Files API
Upload File
Endpoint:
POST /v1/files
Request (multipart/form-data):
curl https://api.anthropic.com/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-F file=@document.pdf \
-F purpose=user_upload
Response:
{
"id": "file-123",
"object": "file",
"bytes": 12345,
"created_at": 1699564800,
"filename": "document.pdf",
"purpose": "user_upload"
}
List Files
Endpoint:
GET /v1/files
Response:
{
"data": [
{
"id": "file-123",
"filename": "document.pdf",
"bytes": 12345
}
]
}
Download File
Endpoint:
GET /v1/files/{file_id}/content
Delete File
Endpoint:
DELETE /v1/files/{file_id}
Models API
List Models
Endpoint:
GET /v1/models
Response:
{
"data": [
{
"id": "claude-sonnet-4-5-20250929",
"type": "model",
"display_name": "Claude Sonnet 4.5"
}
]
}
Get Model
Endpoint:
GET /v1/models/{model_id}
Response:
{
"id": "claude-sonnet-4-5-20250929",
"type": "model",
"display_name": "Claude Sonnet 4.5",
"created_at": 1699564800
}
Skills API
Create Skill
Endpoint:
POST /v1/skills
Request:
{
"name": "my-skill",
"description": "Skill description",
"instructions": "Detailed instructions...",
"version": "1.0.0"
}
List Skills
Endpoint:
GET /v1/skills
Response:
{
"data": [
{
"id": "skill-123",
"name": "my-skill",
"description": "Skill description"
}
]
}
Update Skill
Endpoint:
PATCH /v1/skills/{skill_id}
Request:
{
"description": "Updated description",
"instructions": "Updated instructions..."
}
Delete Skill
Endpoint:
DELETE /v1/skills/{skill_id}
Client SDKs
TypeScript/JavaScript
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY
});
const message = await client.messages.create({
model: 'claude-sonnet-4-5-20250929',
max_tokens: 1024,
messages: [
{ role: 'user', content: 'Hello, Claude!' }
]
});
console.log(message.content);
Python
import anthropic
client = anthropic.Anthropic(
api_key=os.environ.get("ANTHROPIC_API_KEY")
)
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude!"}
]
)
print(message.content)
Error Handling
Error Response Format
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Invalid API key"
}
}
Error Types
invalid_request_error: Invalid request parameters authentication_error: Invalid API key permission_error: Insufficient permissions not_found_error: Resource not found rate_limit_error: Rate limit exceeded api_error: Internal API error overloaded_error: Server overloaded
Retry Logic
async function withRetry(fn: () => Promise<any>, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (error.status === 529 && i < maxRetries - 1) {
await new Promise(r => setTimeout(r, 1000 * (i + 1)));
continue;
}
throw error;
}
}
}
Rate Limits
Headers
Response headers include rate limit info:
anthropic-ratelimit-requests-limit: 1000
anthropic-ratelimit-requests-remaining: 999
anthropic-ratelimit-requests-reset: 2025-11-06T12:00:00Z
anthropic-ratelimit-tokens-limit: 100000
anthropic-ratelimit-tokens-remaining: 99500
anthropic-ratelimit-tokens-reset: 2025-11-06T12:00:00Z
Best Practices
- Monitor rate limit headers
- Implement exponential backoff
- Batch requests when possible
- Use caching to reduce requests
Authentication
API Key
Include API key in requests:
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
Workspace Keys
For organization workspaces:
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $WORKSPACE_API_KEY" \
-H "anthropic-version: 2023-06-01"
See Also
- API documentation: https://docs.anthropic.com/api
- Client SDKs: https://docs.anthropic.com/api/client-sdks
- Rate limits: https://docs.anthropic.com/api/rate-limits
- Error handling: https://docs.anthropic.com/api/errors