curl

Two flags change. The Authorization header carries your gateway key; the URL carries the gateway origin. Every other request and response shape matches the upstream provider exactly. Use this recipe to verify connectivity from a shell or a CI pipeline without an SDK in scope.

Drop-in switch

-H "Authorization: Bearer gw_live_xxxxxxxx"
https://gateway.iq-routing.com/v1/chat/completions

The body shape is the OpenAI /v1/chat/completions shape. The Anthropic shape lives at /v1/messages with the same authorization header.

Verify it routes

#!/usr/bin/env bash
set -euo pipefail

: "${IQ_API_KEY:?set IQ_API_KEY}"

curl -sS -i https://gateway.iq-routing.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IQ_API_KEY}" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Summarise: routing-aware gateway."}],
    "max_tokens": 64
  }' | tee /tmp/iq-response.txt

echo
echo "Request id:"
grep -i '^x-request-id:' /tmp/iq-response.txt | tr -d '\r'

The -i flag prints headers; the grep line surfaces the X-Request-Id value. Paste that into /requests/<uuid> to see the routing decision.

For the Anthropic surface:

curl -sS -i https://gateway.iq-routing.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${IQ_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-haiku-4-5-20251001",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Say hello."}]
  }'

The Anthropic surface accepts both Authorization: Bearer <key> and x-api-key: <key> for compatibility with the official Anthropic SDK default.

Using capability aliases

The cap:<name> syntax in the model field tells the gateway to pick a concrete model at routing time based on the capability's stable intent rather than a pinned model id. The gateway weighs your org's capability overrides and current provider health when resolving which model actually handles the request, so a cap:reason-heavy call can land on a different concrete model over time without your code changing. Five default capabilities resolve to a concrete model: reason-heavy, tool-call-strict, long-context-128k, vision, and json-mode. A sixth, cheap-fast, is accepted too but currently routes like auto -- see capability aliases.

curl -sS -i https://gateway.iq-routing.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IQ_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "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 shell consumer can grep the headers to see 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

curl defaults to no timeout. A stuck connection hangs forever. The gateway's own worst case is up to 600 seconds per provider attempt and 1800 seconds (30 minutes) across a full fallback chain before it gives up with a 504. Most requests finish in a few seconds; add --max-time 60 (or whatever your product can tolerate) if you want your own script to fail faster than the gateway's ceiling.

The --retry family of flags retries on the entire request. The gateway's 429 carries Retry-After; use --retry 0 and have your shell loop respect the header explicitly:

curl -sS -i --max-time 60 --retry 0 ...

When every upstream provider in the fallback chain is exhausted before the timeout above is hit, the gateway returns 503 with an overloaded_error type in the response body, and no Retry-After header -- back off on your own schedule for that case. 429 (the per-team rate-limit window) is the one status that carries Retry-After; read it and apply your own backoff rather than relying on --retry.

JSON-encoded bodies need careful shell escaping. The single-quote pattern above (-d '{"...": "..."}') is portable; double-quote-with-backslash is fragile across BSD and GNU sed derivatives. Use jq -n or a heredoc when the body contains user-supplied content.

The CI/CD pattern: store IQ_API_KEY as a secret (GitHub Actions secrets, Vercel env vars, etc.); never inline it. The gateway revokes keys via the dashboard's /keys page; a leaked key is an operator-actionable revocation, not a redeploy.

Try this in the playground

Run this snippet against your gateway key →