or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

batches.md beta-features.md client.md completions.md errors.md files.md index.md messages.md models.md skills.md streaming.md tools.md types.md

tile.json

Client Initialization and Configuration

The Anthropic client is the primary interface for interacting with the Anthropic API. It handles authentication, configuration, and provides access to all API resource endpoints.

Import

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

CommonJS:

const Anthropic = require('@anthropic-ai/sdk');

Client Class

class Anthropic extends BaseAnthropic {
  constructor(options?: ClientOptions);

  // Resource endpoints
  completions: Completions;
  messages: Messages;
  models: Models;
  beta: Beta;

  // Instance methods
  withOptions(options: Partial<ClientOptions>): this;

  // Static constants
  static HUMAN_PROMPT: string;
  static AI_PROMPT: string;
  static DEFAULT_TIMEOUT: number;
}

ClientOptions

Complete configuration options for the Anthropic client.

interface ClientOptions {
  /**
   * API key for authentication.
   * Can be a static string or async function for dynamic credentials.
   * Defaults to process.env['ANTHROPIC_API_KEY']
   */
  apiKey?: string | ApiKeySetter | null;

  /**
   * Alternative authentication token.
   * Defaults to process.env['ANTHROPIC_AUTH_TOKEN']
   */
  authToken?: string | null;

  /**
   * Custom API base URL.
   * Defaults to process.env['ANTHROPIC_BASE_URL'] or 'https://api.anthropic.com'
   */
  baseURL?: string | null;

  /**
   * Request timeout in milliseconds.
   * Default: 600000 (10 minutes)
   *
   * For non-streaming requests with large max_tokens, timeout is dynamically
   * calculated: min(10 minutes, (60 * max_tokens) / 128000 hours)
   */
  timeout?: number;

  /**
   * Maximum number of retry attempts for failed requests.
   * Default: 2
   *
   * Retries occur for:
   * - Network errors (connection failures)
   * - 408 Request Timeout
   * - 409 Conflict
   * - 429 Rate Limit
   * - 5xx Server errors
   */
  maxRetries?: number;

  /**
   * Additional fetch options passed to all requests.
   * Can include headers, signal, credentials, etc.
   */
  fetchOptions?: RequestInit;

  /**
   * Custom fetch implementation.
   * If not provided, uses global fetch.
   */
  fetch?: typeof fetch;

  /**
   * Default headers included with every request.
   * Can be overridden per-request by setting header to null.
   */
  defaultHeaders?: HeadersLike;

  /**
   * Default query parameters included with every request.
   * Can be removed per-request by setting param to undefined.
   */
  defaultQuery?: Record<string, string | undefined>;

  /**
   * Enable client-side usage (browser environments).
   * Default: false
   *
   * WARNING: Enabling this in browsers exposes API credentials.
   * Only use with appropriate security mitigations.
   */
  dangerouslyAllowBrowser?: boolean;

  /**
   * Logging level for SDK operations.
   * Defaults to process.env['ANTHROPIC_LOG'] or 'warn'
   */
  logLevel?: LogLevel;

  /**
   * Custom logger instance.
   * Defaults to globalThis.console
   */
  logger?: Logger;
}

Supporting Types

// Dynamic API key function
type ApiKeySetter = () => Promise<string>;

// Log levels (most to least verbose)
type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'off';

// Logger interface (compatible with console, pino, winston, etc.)
interface Logger {
  debug(...args: any[]): void;
  info(...args: any[]): void;
  warn(...args: any[]): void;
  error(...args: any[]): void;
}

// Header types
type HeadersLike = Record<string, string | string[] | undefined> | Headers;

Basic Initialization

Default Configuration

Uses environment variables for authentication:

const client = new Anthropic();
// Uses process.env.ANTHROPIC_API_KEY

Explicit API Key

const client = new Anthropic({
  apiKey: 'your-api-key-here',
});

Dynamic API Key

For rotating credentials or runtime key fetching:

const client = new Anthropic({
  apiKey: async () => {
    // Fetch key from secure storage
    const key = await fetchKeyFromVault();
    return key;
  },
});

The function is called before each request, allowing for:

Credential rotation
Token refresh
Runtime key management

Configuration Examples

Custom Timeout

const client = new Anthropic({
  timeout: 30 * 1000, // 30 seconds
});

Disable Retries

const client = new Anthropic({
  maxRetries: 0,
});

Custom Base URL

For proxies or custom endpoints:

const client = new Anthropic({
  baseURL: 'https://proxy.example.com/anthropic',
});

Custom Headers

Add headers to all requests:

const client = new Anthropic({
  defaultHeaders: {
    'X-Custom-Header': 'value',
    'User-Agent': 'MyApp/1.0',
  },
});

Browser Usage (Not Recommended)

const client = new Anthropic({
  apiKey: 'your-api-key',
  dangerouslyAllowBrowser: true, // SECURITY WARNING
});

WARNING: This exposes your API key in client-side code. Only use for:

Internal tools with trusted users
Development/debugging with temporary keys
Environments where key exposure is acceptable

Logging Configuration

// Set log level via environment
// export ANTHROPIC_LOG=debug

// Or via options
const client = new Anthropic({
  logLevel: 'debug', // Shows all HTTP requests/responses
});

// Custom logger (pino example)
import pino from 'pino';

const logger = pino();
const client = new Anthropic({
  logger: logger.child({ component: 'anthropic-sdk' }),
  logLevel: 'debug',
});

Log levels:

debug: All requests/responses with headers and bodies (may expose sensitive data)
info: General informational messages
warn: Warnings and errors (default)
error: Only errors
off: No logging

Custom Fetch Implementation

For Node.js proxies or custom network handling:

// Node.js with undici proxy
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://proxy.example.com:8080');
const client = new Anthropic({
  fetchOptions: {
    dispatcher: proxyAgent, // undici-specific
  },
});

// Bun with built-in proxy support
const client = new Anthropic({
  fetchOptions: {
    proxy: 'http://proxy.example.com:8080',
  },
});

// Deno with HTTP client
const httpClient = Deno.createHttpClient({
  proxy: { url: 'http://proxy.example.com:8080' },
});
const client = new Anthropic({
  fetchOptions: {
    client: httpClient,
  },
});

// Custom fetch function
const client = new Anthropic({
  fetch: async (url, init) => {
    // Add custom logic
    console.log('Fetching:', url);
    return fetch(url, init);
  },
});

Instance Methods

withOptions()

Create a new client with modified options while preserving existing configuration:

withOptions(options: Partial<ClientOptions>): Anthropic;

Example:

const originalClient = new Anthropic({
  apiKey: 'key-1',
  timeout: 60000,
});

// Create new client with different timeout
const timeoutClient = originalClient.withOptions({
  timeout: 120000,
});

// Create new client with different API key
const secondClient = originalClient.withOptions({
  apiKey: 'key-2',
});

// Original client unchanged
console.log(originalClient.timeout); // 60000
console.log(timeoutClient.timeout); // 120000

Use cases:

Multi-tenant applications with different API keys
Different timeout requirements per use case
Testing with different configurations

Resource Endpoints

The client provides access to all API resources:

client.messages    // Messages API (primary conversational interface)
client.completions // Legacy completions API
client.models      // Model information
client.beta        // Beta features namespace

Messages

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

See messages.md

Models

const models = await client.models.list();
const model = await client.models.retrieve('claude-sonnet-4-5-20250929');

See models.md

Beta Features

const message = await client.beta.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
  betas: ['code-execution-2025-05-22'],
  tools: [{ name: 'code_execution', type: 'code_execution_20250522' }],
});

See beta-features.md

Static Constants

Legacy prompt delimiters for the old text completions API:

Anthropic.HUMAN_PROMPT: string    // '\n\nHuman:'
Anthropic.AI_PROMPT: string       // '\n\nAssistant:'
Anthropic.DEFAULT_TIMEOUT: number // 600000 (10 minutes)

Example:

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

const prompt = `${Anthropic.HUMAN_PROMPT} What is 2+2?${Anthropic.AI_PROMPT}`;

// Used with legacy completions API
const completion = await client.completions.create({
  model: 'claude-2.1',
  prompt,
  max_tokens_to_sample: 100,
});

Note: These are for the legacy completions API. The modern Messages API uses structured message objects instead.

Per-Request Options

Override client configuration for individual requests:

interface RequestOptions {
  timeout?: number;
  maxRetries?: number;
  headers?: HeadersLike;
  query?: Record<string, string | undefined>;
  signal?: AbortSignal;
  idempotencyKey?: string;
}

Example:

// Shorter timeout for this request
const message = await client.messages.create(
  {
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Quick question' }],
  },
  {
    timeout: 10000, // 10 seconds
    maxRetries: 0,
    headers: {
      'X-Request-ID': 'custom-id',
    },
  }
);

// Manual cancellation with AbortController
const controller = new AbortController();
const promise = client.messages.create(
  { /* params */ },
  { signal: controller.signal }
);

// Cancel request after 5 seconds
setTimeout(() => controller.abort(), 5000);

Environment Variables

The SDK reads configuration from environment variables:

# Authentication
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_AUTH_TOKEN=...

# Configuration
ANTHROPIC_BASE_URL=https://custom-endpoint.example.com
ANTHROPIC_LOG=debug

# Runtime-specific variables are also supported
NODE_ENV=production

Priority order:

Explicit constructor options
Environment variables
Default values

Error Handling

The client will throw errors when:

// No API key provided
try {
  const client = new Anthropic(); // No apiKey, env var not set
} catch (error) {
  // AnthropicError: Missing API Key
}

// Browser usage without explicit permission
try {
  const client = new Anthropic({ apiKey: 'key' }); // In browser
} catch (error) {
  // AnthropicError: Browser usage not allowed
}

// Invalid configuration
try {
  const client = new Anthropic({
    maxRetries: -1, // Invalid
  });
} catch (error) {
  // Configuration validation error
}

See errors.md for complete error handling documentation.

TypeScript Support

The client is fully typed with TypeScript:

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

// All types are exported
import type {
  ClientOptions,
  Message,
  MessageParam,
  MessageCreateParams,
} from '@anthropic-ai/sdk';

const client: Anthropic = new Anthropic();

// Type inference works automatically
const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
});

// message is typed as Anthropic.Message
console.log(message.content[0].type); // TypeScript knows the shape

Runtime Compatibility

The SDK supports multiple JavaScript runtimes:

Node.js

// Node.js 20+ (LTS or later)
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();

Deno

// Deno v1.28.0+
import Anthropic from 'npm:@anthropic-ai/sdk';
const client = new Anthropic();

Bun

// Bun 1.0+
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();

Edge Runtimes

// Cloudflare Workers
export default {
  async fetch(request) {
    const client = new Anthropic({
      apiKey: env.ANTHROPIC_API_KEY,
    });
    // ...
  },
};

// Vercel Edge Functions
import Anthropic from '@anthropic-ai/sdk';
export const config = { runtime: 'edge' };
export default async function handler(req) {
  const client = new Anthropic();
  // ...
}

Browsers

// NOT recommended - exposes API key
const client = new Anthropic({
  apiKey: 'your-key', // Will be visible in browser
  dangerouslyAllowBrowser: true,
});

For production browser apps: Use a backend proxy to keep credentials secure.

Advanced Usage

Request ID Tracking

All responses include a request ID for debugging:

const message = await client.messages.create({ /* ... */ });
console.log(message._request_id); // 'req_018EeWyXxfu5pfWkrYcMdjWG'

// Or access via withResponse()
const { data, response, request_id } = await client.messages
  .create({ /* ... */ })
  .withResponse();

console.log(request_id); // Same ID
console.log(response.headers.get('request-id'));

Raw Response Access

Access underlying HTTP response:

// Get response before body is parsed
const response = await client.messages.create({ /* ... */ }).asResponse();
console.log(response.status);
console.log(response.headers.get('x-ratelimit-remaining'));

// Get both parsed data and response
const { data, response, request_id } = await client.messages
  .create({ /* ... */ })
  .withResponse();

console.log(data.content); // Parsed message
console.log(response.status); // 200

Keep-Alive Configuration

For long-running connections, TCP keep-alive is automatically configured when supported by the fetch implementation. This reduces idle connection timeouts on some networks.

Override via custom fetch options if needed.

Best Practices

Credential Management

// ✅ Good: Use environment variables
const client = new Anthropic(); // Reads from ANTHROPIC_API_KEY

// ✅ Good: Use credential manager
const client = new Anthropic({
  apiKey: async () => await credentialManager.getKey(),
});

// ❌ Bad: Hardcode keys
const client = new Anthropic({
  apiKey: 'sk-ant-...', // Don't commit this!
});

Timeout Configuration

// ✅ Good: Set reasonable timeouts
const client = new Anthropic({
  timeout: 120000, // 2 minutes for typical requests
});

// ✅ Good: Use streaming for long operations
const stream = await client.messages.stream({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 4000,
  messages: [{ role: 'user', content: 'Long task...' }],
});

// ❌ Bad: Very short timeout without streaming
const client = new Anthropic({
  timeout: 5000, // Too short for API processing
});

Error Handling

// ✅ Good: Handle specific errors
try {
  const message = await client.messages.create({ /* ... */ });
} catch (error) {
  if (error instanceof Anthropic.APIError) {
    console.error('API error:', error.status, error.message);
    console.error('Request ID:', error.requestID);
  } else if (error instanceof Anthropic.APIConnectionError) {
    console.error('Network error:', error.message);
  } else {
    throw error;
  }
}

Resource Reuse

// ✅ Good: Reuse client instance
const client = new Anthropic();

async function processMany(inputs) {
  return Promise.all(
    inputs.map(input =>
      client.messages.create({ /* ... */ })
    )
  );
}

// ❌ Bad: Create new client per request
async function processBad(input) {
  const client = new Anthropic(); // Wasteful
  return client.messages.create({ /* ... */ });
}

Version

Tile

Files

client.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Client Initialization and Configuration

Import

Client Class

ClientOptions

Supporting Types

Basic Initialization

Default Configuration

Explicit API Key

Dynamic API Key

Configuration Examples

Custom Timeout

Disable Retries

Custom Base URL

Custom Headers

Browser Usage (Not Recommended)

Logging Configuration

Custom Fetch Implementation

Instance Methods

withOptions()

Resource Endpoints

Messages

Models

Beta Features

Static Constants

Per-Request Options

Environment Variables

Error Handling

TypeScript Support

Runtime Compatibility

Node.js

Deno

Bun

Edge Runtimes

Browsers

Advanced Usage

Request ID Tracking

Raw Response Access

Keep-Alive Configuration

Best Practices

Credential Management

Timeout Configuration

Error Handling

Resource Reuse

See Also

client.mddocs/