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)

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.

2. Swap your base URL

Anthropic SDK

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

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

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, PII-redacted if a policy applies, counted against the agent’s budget, and recorded with per-call cost attribution.

3. Authentication schemes

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

Authorization: Bearer kc_live_a_...
x-api-key: kc_live_a_...
x-knox-ai-key: kc_live_a_...

For 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:

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

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.

​AI Gateway Quickstart

​1. Create an agent

​2. Swap your base URL

​Anthropic SDK

​OpenAI SDK

​curl

​3. Authentication schemes

​4. Streaming

​Useful request/response headers

​Response caching

​Next steps

Bring your own key

Tokens & DPoP

AI Gateway Quickstart

1. Create an agent

2. Swap your base URL

Anthropic SDK

OpenAI SDK

curl

3. Authentication schemes

4. Streaming

Useful request/response headers

Response caching

Next steps