# AIgateway — quick reference for agents

> One OpenAI-compatible API to 150+ frontier and open-weight models. Drop-in replacement for the OpenAI SDK; aggregator-native primitives (sub-accounts, evals, replays, batches, signed URLs, webhooks) for everything OpenAI doesn't model.

## Endpoints

- HTTP API: `https://api.aigateway.sh/v1`
- MCP server: `https://api.aigateway.sh/mcp` (Streamable HTTP, MCP 2025-03-26)
- OpenAPI 3.1 JSON: `https://aigateway.sh/openapi.json`
- Markdown reference (this file's sibling): `https://aigateway.sh/reference.md`
- Capability map: `https://aigateway.sh/llms.txt`
- Live catalog: `https://aigateway.sh/llms-full.txt` (every model + price + capabilities)
- Agent integration playbook: `https://aigateway.sh/agents.md`

## Auth

Every request needs:

```
Authorization: Bearer sk-aig-...
```

Get a key at https://aigateway.sh/signin (free tier: 60 req/day, no card).

## Install

```bash
pip install aigateway-py openai        # Python: our SDK + openai for chat
pnpm add aigateway-js openai           # Node/TS: our SDK + openai for chat
npm i -g aigateway-cli                 # aig CLI: `aig login`, `aig call`, `aig tail`, `aig init`
```

Use **aigateway-py / aigateway-js** for our aggregator-native primitives (sub-accounts, evals, replays, async jobs, signed URLs, webhook verify). Use **openai** for chat / embeddings / images / audio — drop-in compat, the exact path our own SDK recommends. `aigateway-js` declares `openai` as a peer dependency precisely for this reason.

## Quickstart

```python
# pip install aigateway-py openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.aigateway.sh/v1",
    api_key="sk-aig-...",
)

resp = client.chat.completions.create(
    model="anthropic/claude-opus-4.7",   # any of 150+ slugs
    messages=[{"role": "user", "content": "Hi"}],
)
```

```typescript
// pnpm add aigateway-js openai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.aigateway.sh/v1",
  apiKey: process.env.AIG_KEY,
});

await client.chat.completions.create({
  model: "moonshot/kimi-k2.6",
  messages: [{ role: "user", content: "Hi" }],
});
```

### aig CLI — zero-config

```bash
npm i -g aigateway-cli
aig login                                   # device auth via browser
aig call moonshot/kimi-k2.6 "hello"         # streams to stdout
aig tail                                    # live log stream
aig init                                    # scaffold .aigrc in cwd
```

## Using aigateway-py / aigateway-js for primitives

```python
from aigateway import AIgateway
client = AIgateway(api_key="sk-aig-...")

# Async video job
job = client.jobs.create_video(model="runwayml/gen-4", prompt="...", duration=5)
done = client.jobs.wait(job.id)

# Scoped sub-account key per customer
sub = client.sub_accounts.create(name="acme", spend_cap_cents=50_000)

# Run an eval across candidates; use its alias to route to the current winner
run = client.evals.create(
    name="prod-summarize",
    candidate_models=["anthropic/claude-opus-4.7", "moonshot/kimi-k2.6"],
    dataset=[...], metric="quality",
)
# Then model="eval:prod-summarize" routes to the winner automatically.
```

## Webhook signing

Every callback (job results + lifecycle events) carries:

- `x-aig-signature: t=<unix>,v1=<hex>` — HMAC-SHA256 over `${t}.${raw_body}`
- `x-aig-event-type: <event>`
- `x-aig-delivery-id: <uuid>` — stable across retries
- `x-aig-attempt: <n>` — 1-indexed attempt counter

Get the signing secret from `GET /v1/webhook-secret`. Failed deliveries retry on `0s, 30s, 2m, 10m, 1h, 6h`.

Both SDKs ship verifiers: `verify_webhook(payload, sig, secret)` (Python) / `verifyWebhook(payload, sig, secret)` (Node).

## Errors

OpenAI-shaped envelope: `{ error: { message, type, code } }`. Types: `invalid_request_error`, `authentication_error`, `budget_exceeded`, `model_not_found`, `rate_limit_error`, `provider_error`, `timeout_error`. On 429 honor `Retry-After`.

## Rate limits (RPM, per key)

| Tier | RPM |
|------|-----|
| Free | 10 |
| Starter | 120 |
| Pro | 600 |
| Business | 3,000 |
| Agent | 6,000 |
| Enterprise | 30,000+ |

## Cost attribution

Tag any request with `x-aig-tag: <feature>` then read aggregates from `GET /v1/usage/by-tag?month=YYYY-MM`. For per-customer spend, mint sub-accounts (`POST /v1/sub-accounts`) and read `GET /v1/usage/by-sub-account`.

## Where to next

- Full per-endpoint reference: https://aigateway.sh/reference.md
- HTML reference: https://aigateway.sh/reference
- Agent integration playbook: https://aigateway.sh/agents.md
- Model catalog: https://aigateway.sh/models
- Pricing: https://aigateway.sh/pricing