The "base URL" is the host portion of every request the SDK makes — everything before /v1/messages. Normally you never think about it. But the official tooling lets you override it, and that single knob unlocks several patterns enterprises rely on: routing traffic through an internal LLM gateway, inspecting requests in a debugging proxy, or pointing tests at a local mock server that never bills a token.
How to override it
The documented mechanism is the ANTHROPIC_BASE_URL environment variable, honored by the ant CLI (which also accepts a per-command --base-url flag). Because the override lives in the environment rather than in code, the same application can talk directly to the API in one environment and through a gateway in another — the deployment configuration decides, not the source.
There is a second, stickier home for the setting: on-disk profiles. A profile's config file (configs/<profile>.json under $ANTHROPIC_CONFIG_DIR) can carry a base_url field alongside organization_id and workspace_id. Remember the documented mixing rule: when a profile is loaded, environment variables fill only fields the profile omits — they never override fields the profile sets. If a profile pins base_url, exporting ANTHROPIC_BASE_URL will not redirect it; that's a feature when you want a developer profile welded to a corporate gateway. The SDK clients also accept configuration at construction time; for the exact constructor parameter name in your language, check the official SDK repository for that language rather than guessing.
When this is useful
| Target | Why you'd do it |
|---|---|
| Internal LLM gateway | Central logging, model allow-lists, per-team cost attribution, one egress point for the security team |
| Debugging proxy | Inspect exact request/response payloads while developing |
| Local mock server | Fast, deterministic tests with zero API spend |
The gateway case is the big one for enterprises. If every service reads ANTHROPIC_BASE_URL from its deploy-time environment, the platform team can interpose a gateway later — or swap it — without a single application change. Note that a gateway sitting between your apps and the API needs its own credential story; on Claude Platform on AWS, the documented pattern for handing a bearer-token-only gateway a credential is a short-term API key generated from AWS credentials via AWS's token-generator libraries.
sk-ant-api... key means nothing to your internal gateway unless the gateway forwards it, and gateway-issued credentials mean nothing to the real API. Decide which side authenticates the client, and test the pair together.What NOT to use it for
Overriding the base URL does not turn the first-party client into a 3P client. The third-party platforms differ in more than hostname: Amazon Bedrock and Google Vertex AI have their own request paths, signing, and credentials, which is why the Python SDK ships dedicated clients — AnthropicBedrockMantle, AnthropicVertex, AnthropicFoundry — rather than asking you to repoint Anthropic(). The same goes for Claude Platform on AWS: its regional endpoint (https://aws-external-anthropic.{region}.api.aws/v1/...) requires SigV4 signing with the service name aws-external-anthropic and an anthropic-workspace-id header, so you use AnthropicAWS(), which constructs the region-based URL itself. Use the base-URL override to interpose infrastructure in front of a platform, not to impersonate a different platform.
Testing the override
Whatever you point at, verify end to end before trusting it: make one real call through the new URL and confirm the response arrives and the traffic shows up where you expect (gateway logs, proxy console, mock-server assertions). With the ant CLI, --debug prints the full HTTP request and response to stderr with the API key redacted — the quickest way to confirm which host was actually hit.
Where to go next
See the full env var list for where ANTHROPIC_BASE_URL sits among the SDK's settings, mocking Claude API calls in tests for the local-server pattern, and customizing the HTTP client for proxy and transport-level control.