//DOCS OpenAI Gateway

OpenAI-Compatible AI Gateway

Punk is an OpenAI-compatible AI gateway for production agents. If an app already calls client.chat.completions.create(...), the first integration is a base URL change: send the same request shape through Punk, add identity headers, and inspect the route explanation that comes back with every run.

Use this path when you want agent observability, exact caching, governance, trace-based learning, provider failover, and route explanations without changing the rest of the application.

Install

You do not need the Punk SDK for gateway-only traffic. Keep using the official OpenAI client:

npm install openai

Create a Punk tenant API key in the hosted dashboard, then point the OpenAI client at Punk:

export PUNK_BASE_URL=https://app.punktechnologies.com
export PUNK_API_KEY=pk_...

Provider keys and BYOK credentials live in Punk's hosted control plane, not in this app.

For production-like enterprise traffic, start with an observe-mode key and use Enterprise Pilot for the pilot sequence.

First-Run Checklist

1. Set the OpenAI client base URL to $PUNK_BASE_URL/v1.
2. Use the Punk tenant API key as the OpenAI client key or bearer token.
3. Send X-Punk-App, X-Punk-Agent, and X-Punk-Subject.
4. Send one deterministic request and record x-punk-run-id plus x-punk-route.
5. Open the run explanation. Check readiness separately with an admin key when you are validating deployment posture.

Working curl smoke test:

curl -sS -D /tmp/punk-headers -o /tmp/punk-body \
  "$PUNK_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $PUNK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Punk-App: support-app" \
  -H "X-Punk-Agent: support-agent" \
  -H "X-Punk-Subject: user-123" \
  -d '{
    "model": "gpt-4o-mini",
    "temperature": 0,
    "messages": [
      { "role": "user", "content": "Classify this ticket: I was charged twice. Return JSON." }
    ]
  }'

RUN_ID=$(awk 'tolower($1)=="x-punk-run-id:" {print $2}' /tmp/punk-headers | tr -d '\r' | tail -n 1)
ROUTE=$(awk 'tolower($1)=="x-punk-route:" {print $2}' /tmp/punk-headers | tr -d '\r' | tail -n 1)

jq -r '.choices[0].message.content' /tmp/punk-body
printf 'route=%s runId=%s\n' "$ROUTE" "$RUN_ID"

curl -sS -H "Authorization: Bearer $PUNK_API_KEY" \
  "$PUNK_BASE_URL/api/v1/runs/$RUN_ID" \
  | jq '{route: .run.route, provider: .run.provider, explanation: .run.routeExplanation}'

Admin readiness check:

curl -sS -H "Authorization: Bearer ${PUNK_ADMIN_API_KEY:-$PUNK_API_KEY}" \
  "$PUNK_BASE_URL/api/v1/readiness" \
  | jq '{summary, attention: [.items[]? | select(.status=="attention") | {id, message, action}]}'

The first request normally routes live. Repeat the exact same safe request to test exact_cache. In observe mode, Punk returns the live provider response and records would-have optimization as ghost evidence in the run explanation. Artifact and model-substitution routes require repeated stable traffic, replay/shadow evidence, and promotion.

One-Line Integration

import OpenAI from "openai";

const punkBaseUrl = process.env.PUNK_BASE_URL ?? "https://app.punktechnologies.com";

const client = new OpenAI({
  baseURL: `${punkBaseUrl.replace(/\/$/, "")}/v1`,
  apiKey: process.env.PUNK_API_KEY,
  defaultHeaders: {
    "X-Punk-App": "support-app",
    "X-Punk-Agent": "support-agent",
    "X-Punk-Subject": "user-123"
  }
});

const result = await client.chat.completions.create({
  model: "gpt-4o-mini",
  temperature: 0,
  messages: [
    { role: "user", content: "Classify this ticket: I was charged twice." }
  ]
});

console.log(result.choices[0]?.message?.content);

Everything above the client constructor stays OpenAI-shaped. Streaming, tools, response_format, and normal model parameters continue to use the OpenAI client surface.

What Punk Adds

Read The Route

The OpenAI SDK exposes response headers through .withResponse():

const { data, response } = await client.chat.completions
  .create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Say hello." }]
  })
  .withResponse();

console.log(data.choices[0]?.message?.content);
console.log(response.headers.get("x-punk-route"));
console.log(response.headers.get("x-punk-run-id"));

Then inspect the run:

curl -sS -H "Authorization: Bearer $PUNK_API_KEY" \
  "$PUNK_BASE_URL/api/v1/runs/<runId>" \
  | jq .run.routeExplanation

First-Run Troubleshooting

When To Add The SDK

The gateway sees model traffic. Add @punktechnologies/sdk when you also want Punk to see application context the model request does not include:

Read next: SDK, Agent Observability & Tool Caching, API.

For OpenRouter provider/model slugs through the same OpenAI-compatible wire, see OpenRouter.