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_GATEWAY_KEY:?set IQ_GATEWAY_KEY}"

curl -sS -i https://gateway.iq-routing.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IQ_GATEWAY_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?request_id=<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_GATEWAY_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 operator's per-org overrides plus the focus-mode bias plus the circuit-breaker state shape the resolved tuple. The six default capabilities are reason-heavy, tool-call-strict, long-context-128k, vision, cheap-fast, and json-mode.

curl -sS -i https://gateway.iq-routing.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IQ_GATEWAY_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 resolver decision tree plus the override mechanics. The operator can override the default capability mapping via the capabilities dashboard editor at /settings/capabilities.

Common gotchas

curl defaults to no timeout. A stuck connection hangs forever. Add --max-time 60 to align with the gateway's 30-second p99 plus a margin.

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 ...

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_GATEWAY_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 →