> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Gateway Quickstart

> Route your first AI call through the gateway with a one-line base-URL swap — Anthropic or OpenAI SDK, a phantom token, and every guardrail on by default.

# AI Gateway Quickstart

You adopt the AI Gateway by pointing your existing AI SDK at your agent's gateway URL and using a **phantom token** as the API key. No new SDK, no code rewrite.

## 1. Create an agent

In the dashboard, go to **AI Gateway → New gateway**, then add an agent. Pick the upstream provider (Anthropic or OpenAI) and the route that injects your provider key. When the agent is created you get two things:

* an **agent URL** — `https://<your-slug>.knoxcall.com/v1/ai/<agent-slug>` (sandbox: `https://sandbox-<your-slug>.knoxcall.com/...`)
* a **phantom token** — `kc_live_a_…` (shown once at mint time)

<Note>
  The data plane is served on your tenant's **proxy subdomain** (`<slug>.knoxcall.com`), not `api.knoxcall.com`. Always use the `agent_url` returned at agent creation as your base URL.
</Note>

## 2. Swap your base URL

### Anthropic SDK

```python theme={"dark"}
from anthropic import Anthropic

client = Anthropic(
    base_url="https://acme.knoxcall.com/v1/ai/support-bot",  # your agent URL
    api_key="kc_live_a_...",                                  # your phantom token
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize this ticket…"}],
)
print(msg.content[0].text)
```

### OpenAI SDK

```python theme={"dark"}
from openai import OpenAI

client = OpenAI(
    base_url="https://acme.knoxcall.com/v1/ai/support-bot",
    api_key="kc_live_a_...",
)

resp = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Summarize this ticket…"}],
)
print(resp.choices[0].message.content)
```

### curl

```bash theme={"dark"}
curl https://acme.knoxcall.com/v1/ai/support-bot/v1/messages \
  -H "Authorization: Bearer kc_live_a_..." \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

That's it. The call is now authenticated by the phantom token, screened by the [prompt firewall](/ai-gateway/firewall), [PII-redacted](/ai-gateway/pii-redaction) if a policy applies, counted against the agent's [budget](/ai-gateway/budgets-finops), and recorded with per-call [cost attribution](/ai-gateway/budgets-finops).

## 3. Authentication schemes

The phantom token can be sent three ways — use whichever your SDK makes easiest:

```http theme={"dark"}
Authorization: Bearer kc_live_a_...
x-api-key: kc_live_a_...
x-knox-ai-key: kc_live_a_...
```

For [DPoP](/ai-gateway/tokens-and-dpop)-bound tokens, also send a `DPoP` proof header on every request.

## 4. Streaming

Streaming works unchanged — set `stream: true` (or `Accept: text/event-stream`). PII redaction runs **inside** the stream, so redactions appear as the tokens arrive rather than after the response completes:

```python theme={"dark"}
with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "…"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="")
```

## Useful request/response headers

| Header                     | Direction | Meaning                                                                                       |
| -------------------------- | --------- | --------------------------------------------------------------------------------------------- |
| `X-KC-User`                | request   | SCIM user id for per-user cost attribution                                                    |
| `X-KC-Conversation-Id`     | request   | conversation id — scopes the reversible PII token map **and the response cache** across turns |
| `X-Request-Id`             | response  | UUID for this call (appears in audit logs)                                                    |
| `X-Knox-AI-Budget-Pct`     | response  | current budget utilization %                                                                  |
| `X-Knox-AI-Tools-Stripped` | response  | tools removed by the agent's tool allowlist                                                   |
| `X-Knox-AI-Cache`          | response  | present on a cache hit (`exact` or `semantic`)                                                |

## Response caching

Set `cache_mode` on an agent to `exact` (byte-identical requests replay a saved
response) or `semantic` (a request that *means the same thing* as a prior one
replays it, matched by embedding similarity).

<Warning>
  The `X-KC-Conversation-Id` header is the cache's isolation boundary. **Exact and
  semantic cache hits only ever occur within the same conversation id**, so a cached
  response can never cross conversations. Because of this, your conversation ids
  **must be unguessable and unique per end-user conversation** — never a constant or
  a value one end-user could guess for another. A request with no conversation id is
  cached byte-exact only (never semantically), and never shares with a conversation.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Bring your own key" icon="key" href="/ai-gateway/byo-key">
    Why AI features use your own Anthropic key, and how to add it.
  </Card>

  <Card title="Tokens & DPoP" icon="shield-halved" href="/ai-gateway/tokens-and-dpop">
    Mint scoped, sender-constrained tokens for agents and CI.
  </Card>
</CardGroup>