# plaingateway

> plaingateway is an LLM API gateway with OpenRouter's API: the same paths, request fields, response shapes and errors.
> One prepaid key reaches every routed model through OpenAI-compatible and Anthropic-compatible endpoints, at a discount to list price.

## Make a first call

- Base URL (OpenAI-compatible): https://api.plaingateway.com/api/v1
- Base URL for the Anthropic SDK (it appends /v1/messages): https://api.plaingateway.com/api
- Auth header: `Authorization: Bearer <key>`. `X-Api-Key: <key>` also works.
- Key format: `sk-pg-v1-` followed by 64 hex characters.
- Get a key: a human signs up at https://plaingateway.com/signup (one email confirmation click, then a card payment of at least 5 USD), then creates a key at https://plaingateway.com/settings/keys. The key is shown once. There is no free tier and no API that creates keys.
- Model ids are `author/slug`, for example `openai/gpt-5.6-luna`. List every model with `GET https://api.plaingateway.com/api/v1/models` (no key needed) or see https://plaingateway.com/models.

```sh
curl https://api.plaingateway.com/api/v1/chat/completions \
  -H "Authorization: Bearer $PLAINGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-5.6-luna", "messages": [{"role": "user", "content": "Say hello in five words."}], "max_tokens": 32}'
```

Expected response (200, values vary):

```json
{
  "id": "gen-6f2d0c5e9a1b4c7d8e3f2a10",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "openai/gpt-5.6-luna",
  "provider": "OpenAI",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": { "role": "assistant", "content": "Hello! How are you today?" }
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 11, "total_tokens": 23, "cost": 0.0000156 }
}
```

Response headers: `X-PG-Host` (the serving host), `X-PG-Cost-USD` (the charge in USD; a trailer on streams), `X-Generation-Id` (look it up at `GET /generation?id=`).

Errors are JSON with the HTTP status in `error.code`:

```json
{ "error": { "message": "User not found.", "code": 401 } }
```

401 bad or missing key, 402 balance too low or key spend limit reached, 400 bad request or unknown model id, 404 no host left after routing filters, 408 provider timeout, 413 body over 32 MiB, 429 provider rate limit (with Retry-After), 502 provider error, 503 a gateway store is unavailable (retry). `/messages` returns Anthropic's error shape instead.

## More

- [For AI agents](https://plaingateway.com/docs/overview/agents.md): the whole bootstrap on one page
- [Full docs as one Markdown file](https://plaingateway.com/llms-full.txt)
- [OpenAPI 3.1 description](https://plaingateway.com/openapi.json)
- [Docs](https://plaingateway.com/docs): every page also answers as Markdown with a .md suffix or `Accept: text/markdown`
- [Models and prices](https://plaingateway.com/models)

## Docs pages

- [Quickstart](https://plaingateway.com/docs/overview/quickstart.md): Get a key, then make a first request with curl, Python or TypeScript.
- [For AI agents](https://plaingateway.com/docs/overview/agents.md): Everything an AI agent needs to make its first call, on one page.
- [FAQ](https://plaingateway.com/docs/overview/faq.md): Answers about top-ups, hosts, cost and privacy.
- [Image inputs](https://plaingateway.com/docs/overview/image-inputs.md): Send images in chat completions and Messages requests.
- [Models](https://plaingateway.com/docs/overview/models.md): Find model IDs, prices, capabilities and hosts.
- [Principles](https://plaingateway.com/docs/overview/principles.md): How pricing, host choice, compatibility and data handling work.
- [Current key](https://plaingateway.com/docs/api/api-keys.md): Read the calling key's spend limit and usage with GET /auth/key.
- [Chat completions](https://plaingateway.com/docs/api/chat-completions.md): Create a chat completion or stream.
- [Completions](https://plaingateway.com/docs/api/completions.md): Create a legacy text completion.
- [Credits](https://plaingateway.com/docs/api/credits.md): Read total credits and usage.
- [Endpoints](https://plaingateway.com/docs/api/endpoints.md): List the hosts of one model with their prices and measured uptime, latency and throughput.
- [Errors](https://plaingateway.com/docs/api/errors.md): Error bodies, every status the gateway returns, and what to do about each.
- [Generation](https://plaingateway.com/docs/api/generation.md): Look up cost and usage for one request.
- [Headers](https://plaingateway.com/docs/api/headers.md): Authentication, attribution and Anthropic request headers, and the cost and host headers on every response.
- [Messages](https://plaingateway.com/docs/api/messages.md): Create an Anthropic-shaped message.
- [Models](https://plaingateway.com/docs/api/models.md): List model IDs and prices with GET /models.
- [Responses](https://plaingateway.com/docs/api/responses.md): Create an OpenAI Responses-shaped result.
- [API keys](https://plaingateway.com/docs/auth/api-keys.md): Create, limit, disable and revoke the keys that call the API.
- [Management keys](https://plaingateway.com/docs/auth/management-keys.md): There are no management keys: manage keys in the dashboard.
- [Auto top-up](https://plaingateway.com/docs/billing/auto-recharge.md): Top up by card automatically when the balance falls below a threshold.
- [Bonus and referral credit](https://plaingateway.com/docs/billing/bonus-and-referral-credit.md): The first top-up bonus and the credit a referrer earns.
- [Wallet and top-ups](https://plaingateway.com/docs/billing/credits.md): Add credit to the prepaid wallet and see when usage is charged.
- [Invoices](https://plaingateway.com/docs/billing/invoices.md): Find the invoice for each card payment.
- [Refunds](https://plaingateway.com/docs/billing/refunds.md): What a refund or dispute does to your wallet and referral credit.
- [Taxes](https://plaingateway.com/docs/billing/taxes.md): How tax is handled on card payments.
- [Changelog](https://plaingateway.com/docs/changelog.md): Dated changes to the API and the documentation.
- [App attribution](https://plaingateway.com/docs/features/app-attribution.md): Name the app behind a request.
- [Error handling](https://plaingateway.com/docs/features/errors.md): When to retry, and when to stop.
- [Prompt caching](https://plaingateway.com/docs/features/prompt-caching.md): Reuse a long prompt prefix at the cached token price.
- [Rate limits](https://plaingateway.com/docs/features/rate-limits.md): What happens when a host rate limits a request.
- [Reasoning tokens](https://plaingateway.com/docs/features/reasoning-tokens.md): Set how much a model reasons, and read how many tokens it used.
- [Structured outputs](https://plaingateway.com/docs/features/structured-outputs.md): Ask for JSON that matches a schema.
- [Tool calling](https://plaingateway.com/docs/features/tool-calling.md): Let a model call your functions, then send back the results.
- [Usage accounting](https://plaingateway.com/docs/features/usage-accounting.md): See what each request cost and when the wallet is charged.
- [Zero data retention](https://plaingateway.com/docs/features/zero-data-retention.md): Route only to hosts that keep no prompts or outputs.
- [Aider](https://plaingateway.com/docs/integrations/aider.md): Configure Aider to call plaingateway.
- [Anthropic SDK](https://plaingateway.com/docs/integrations/anthropic-sdk.md): Configure the Anthropic SDK to call plaingateway.
- [Claude Code](https://plaingateway.com/docs/integrations/claude-code.md): Configure Claude Code to call plaingateway.
- [Cline](https://plaingateway.com/docs/integrations/cline.md): Configure Cline to call plaingateway.
- [Codex CLI](https://plaingateway.com/docs/integrations/codex-cli.md): Configure Codex CLI to call plaingateway.
- [Continue](https://plaingateway.com/docs/integrations/continue.md): Configure Continue to call plaingateway.
- [Cursor](https://plaingateway.com/docs/integrations/cursor.md): Configure Cursor to call plaingateway.
- [Kilo Code](https://plaingateway.com/docs/integrations/kilo-code.md): Configure Kilo Code to call plaingateway.
- [LangChain](https://plaingateway.com/docs/integrations/langchain.md): Configure LangChain to call plaingateway.
- [LibreChat](https://plaingateway.com/docs/integrations/librechat.md): Configure LibreChat to call plaingateway.
- [n8n](https://plaingateway.com/docs/integrations/n8n.md): Configure n8n to call plaingateway.
- [Open WebUI](https://plaingateway.com/docs/integrations/open-webui.md): Configure Open WebUI to call plaingateway.
- [OpenAI SDK](https://plaingateway.com/docs/integrations/openai-sdk.md): Configure the OpenAI SDK to call plaingateway.
- [OpenCode](https://plaingateway.com/docs/integrations/opencode.md): Configure OpenCode to call plaingateway.
- [SillyTavern](https://plaingateway.com/docs/integrations/sillytavern.md): Configure SillyTavern to call plaingateway.
- [Vercel AI SDK](https://plaingateway.com/docs/integrations/vercel-ai-sdk.md): Configure the Vercel AI SDK to call plaingateway.
- [From Anthropic](https://plaingateway.com/docs/migrate/from-anthropic.md): Move an Anthropic Messages client to plaingateway.
- [From OpenAI](https://plaingateway.com/docs/migrate/from-openai.md): Move an OpenAI client to plaingateway.
- [From OpenRouter](https://plaingateway.com/docs/migrate/from-openrouter.md): Move OpenRouter traffic to plaingateway.
- [Data policies](https://plaingateway.com/docs/privacy/data-policies.md): What plaingateway keeps, and how to limit which hosts see a request.
- [Data Processing Addendum](https://plaingateway.com/docs/privacy/dpa.md): Request a data processing addendum.
- [Provider logging](https://plaingateway.com/docs/privacy/provider-logging.md): Hosts keep data under their own policies.
- [Subprocessors](https://plaingateway.com/docs/privacy/subprocessors.md): Companies that process data for plaingateway.
- [Referral dashboard](https://plaingateway.com/docs/referral/dashboard.md): Find your referral code, link and earnings.
- [How referral works](https://plaingateway.com/docs/referral/how-it-works.md): Share your code and earn credit on the top-ups of accounts you refer.
- [Payouts](https://plaingateway.com/docs/referral/payouts.md): Referral earnings are paid as wallet credit.
- [Referral rules](https://plaingateway.com/docs/referral/rules.md): What blocks or reverses referral credit.
- [Model fallbacks](https://plaingateway.com/docs/routing/model-fallbacks.md): Name other models to try when the first one fails.
- [Model variants](https://plaingateway.com/docs/routing/model-variants.md): Change host order with a :floor or :nitro suffix.
- [Provider routing](https://plaingateway.com/docs/routing/provider-routing.md): Filter and order the hosts that serve a request.