HTTP client for the Anthropic API using Req.

This module provides HTTP client functionality for interacting with the Anthropic API. It handles authentication, versioning, beta features, and configurable timeouts.

Configuration

Pass HTTP options per client, so different clients in one application can behave differently (say, retries for batch polling but none for one-shot creates):

client = Claudio.Client.new(%{
  token: "your-api-key",
  timeout: 60_000,        # Connection timeout in ms (default: 60s)
  recv_timeout: 120_000,  # Receive timeout in ms (default: 120s)
  retry: true
})

Each key given to new/2 wins. Keys you leave out, or pass as nil, fall back to the application environment, then to the built-in defaults:

# config/config.exs
config :claudio,
  default_api_version: "2023-06-01",
  default_beta_features: []

config :claudio, Claudio.Client,
  timeout: 60_000,
  recv_timeout: 120_000,
  retry: true

Timeouts

timeout controls connection establishment; recv_timeout controls how long to wait for data once connected. For long streaming operations, raise recv_timeout (e.g. recv_timeout: 600_000 for 10 minutes). Both take a non-negative integer (ms) or :infinity; anything else raises ArgumentError when the client is built.

Retries

retry: retries transient failures — HTTP 408, 429, 500, 502, 503, 504, 529 (overloaded) and connection timeouts/refusals — on every method, including the POSTs the Messages API uses:

• retry: true — 3 retries; honours Retry-After (integer seconds) on 429, 503 and 529, else backs off 1s, 2s, 4s
• retry: [delay: 1000, max_retries: 3, max_delay: 10_000] — delay doubles per attempt, capped at max_delay (all in ms); Retry-After still wins when the server sends it (Retry-After is not capped by max_delay)
• retry: false — no retries at all (not even Req's GET/HEAD default)

Without retry: (unset or nil at every level), Req's default applies: only GET/HEAD requests are retried. Any other value, or an unknown key in the keyword list, raises ArgumentError. Streaming requests are never retried.

Retries can duplicate work. After an ambiguous failure — a timeout, a closed connection, a 5xx — the API may already have processed the request, and the retry sends it again: a second message is generated and billed, and a create call (a batch, a file upload, an Admin invite) can run twice. None of these endpoints take an idempotency key, so set retry: false where a duplicate is unacceptable. After an ambiguous failure, retry only if your application can deduplicate requests or reconcile the outcome.

Usage

# Simple client with defaults
client = Claudio.Client.new(%{
  token: "your-api-key"
})

# With explicit version
client = Claudio.Client.new(%{
  token: "your-api-key",
  version: "2023-06-01"
})

# With beta features (per-feature betas are normally declared by the
# `Claudio.Messages.Request` helpers; set them here only for ad-hoc flags)
client = Claudio.Client.new(%{
  token: "your-api-key",
  version: "2023-06-01",
  beta: ["context-management-2025-06-27"]
})

# Custom endpoint (for testing or proxies)
client = Claudio.Client.new(
  %{token: "key", version: "2023-06-01"},
  "https://custom.api.endpoint/v1/"
)

Return Value

Returns a Req.Request struct that can be used with Claudio.Messages, Claudio.Batches, and other API modules.