Skip to content
IQ

Anthropic · Node

The @anthropic-ai/sdk package accepts baseURL and apiKey on the client constructor. Swap the base URL and your client.messages.create calls route through the gateway.

Drop-in switch

const client = new Anthropic({
  baseURL: "https://gateway.iq-routing.com",
  apiKey: process.env.IQ_API_KEY,
});

The gateway exposes the Anthropic surface at /v1/messages; the SDK appends /v1/messages itself when constructing the request URL. Pass the gateway origin only.

Verify it routes

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

const client = new Anthropic({
  baseURL: "https://gateway.iq-routing.com",
  apiKey: process.env.IQ_API_KEY!,
  timeout: 60_000,
  maxRetries: 0,
});

const response = await client.messages
  .create({
    model: "claude-haiku-5-5",
    max_tokens: 64,
    messages: [{ role: "user", content: "Summarise: routing-aware gateway." }],
  })
  .withResponse();

console.log("X-Request-Id:", response.response.headers.get("x-request-id"));
console.log(response.data.content[0]);

Drop into a fresh pnpm init project with @anthropic-ai/sdk. Set IQ_API_KEY in your environment, run with npx tsx verify.ts.

Using capability aliases

Pass cap:<name> in the model field to request a capability; inspect the response model to see which model answered and manage your organization's overrides at /settings/capabilities.

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

const anthropic = new Anthropic({
  baseURL: "https://gateway.iq-routing.com",
  apiKey: process.env.IQ_API_KEY!,
});

const message = await anthropic.messages.create({
  model: "cap:reason-heavy",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Plan the migration in three phases." }],
});

The resolved provider plus model surface in the x-iq-routing response header (a JSON-encoded payload with chosen_provider and chosen_model fields, among others), so the SDK consumer can inspect which concrete model handled the request. See the capability aliases docs for the full list of default capabilities and how to override them. You can override the default capability mapping for your org via the capabilities dashboard editor at /settings/capabilities.

Common gotchas

The Node SDK retries some errors by default (see the Retries section of the Anthropic TypeScript SDK README). Set maxRetries: 0 to avoid burning attempts inside the cooldown window and handle backoff in your own queue.

Streaming via client.messages.stream works transparently. The MessageStream instance exposes .finalMessage() and event listeners that match the direct-to-Anthropic shape exactly.

Tool use (the tools parameter on messages.create) is forwarded without modification. The gateway's tool_choice defaults align with Anthropic's defaults so existing tool-using clients work without behaviour changes.

The gateway forwards anthropic-beta identifiers to Anthropic and Claude Bedrock, may normalize the comma-separated values or add required beta identifiers, and omits them for other providers.

Browser usage is rejected by the SDK by default. The gateway's recommended pattern is server-side: call the SDK from your own backend with the gateway base URL; the gateway authenticates with your gw_live_ key, never the upstream Anthropic key.

The gateway allows up to 600 seconds per provider attempt and 1800 seconds across the fallback loop; streaming limits cover upstream stream readiness rather than the full token stream, so set an explicit client timeout if you need a shorter limit.

When every upstream provider in the fallback chain is exhausted before that ceiling is hit, the gateway returns 503 (an overloaded_error in the Anthropic error body). That response carries no Retry-After header, so back off on your own schedule. Rate-limit and daily-budget 429s carry Retry-After; monthly-budget and spend-ceiling 429s do not. With maxRetries: 0, a caller-side queue should read Retry-After when it is present and apply its own backoff otherwise, including on the 503. Every error body on this surface carries a request_id field for correlation against the gateway's requests view.

Try this in the playground

Run this snippet against your gateway key →