# API reference

Spec: [openapi.json](https://kilowatt.sh/openapi.json) (OpenAPI 3.1). Signup endpoints live at `https://kilowatt.sh` and need no auth.

## Checkout: reserve a founding spot

### POST /api/checkout

Creates a Stripe Checkout session (subscription mode) and returns its URL. The human opens it and pays. No auth.

Body (JSON, or `application/x-www-form-urlencoded`, which redirects straight to Checkout with 303):

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `plan` | string | no | `pro` ($39/month, default) or `lite` ($19/month) |
| `email` | string | no | Prefills Checkout. Format and mail domain are checked |
| `agent` | boolean | no | `true` if an AI agent is calling |
| `ref` | string | no | Where you found Kilowatt (max 100 chars) |

Responses:

| Status | Meaning |
| --- | --- |
| 201 | `{"ok":true,"checkout_url":"https://checkout.stripe.com/...","session_id":"cs_...","plan":"pro","price_usd_month":39,"expires_at":"...","founding_spots_left":N}` |
| 400 | Bad plan or email |
| 409 | `founding_full` (all 100 reserved; use the waitlist) or `already_reserved` (email already has a spot) |
| 503 | `checkout_unavailable`; use the waitlist |

After payment, Stripe sends the subscriber to `https://kilowatt.sh/welcome?session_id=...`, which shows the spot number and a billing-portal button. The spot is recorded by a signature-verified Stripe webhook.

### GET /api/checkout

`checkout_open`, `founding_cap`, `founding_reserved`, `founding_spots_left`, and the plans with prices.

### Billing

Cancel anytime from the billing portal. Every charge made before your API key is delivered is refunded in full on request. If we don't deliver your key, we refund every charge. Manage or cancel at [kilowatt.sh/account](https://kilowatt.sh/account).

## Waitlist (free, doesn't reserve a spot)

### POST /api/waitlist

No auth. Idempotent per email (case-insensitive).

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `email` | string | yes | Max 254 chars; format and mail domain are checked |
| `use_case` | string | no | Max 500 chars |
| `agent` | boolean | no | `true` if an AI agent is submitting |
| `plan` | string | no | `pro`, `lite`, or `undecided` |
| `ref` | string | no | Max 100 chars. Also accepted as `?ref=` |

Headers: `X-Client: <agent name>` (optional, stored).

| Status | Meaning |
| --- | --- |
| 201 | Added. Body has `position`, `message`, and current counts |
| 200 | Email already registered; same body with `already_registered: true` |
| 303 | Form posts redirect to `/?joined=<position>#join` |
| 400 | Validation error: `{"ok":false,"error":"..."}` |
| 429 | Rate limited (5 new signups per 10 min per IP, 20 per /24 network). `Retry-After` header and `retry_after_seconds` |

### GET /api/waitlist

Counts: `founding_cap`, `founding_reserved`, `founding_spots_left`, `checkout_open`, `waitlist_signups`, `total_signups`. Real numbers; nothing is padded.

## Data and MCP

- `GET /models.json`, `GET /plans.json`: the model lineup and plans (same data as these docs).
- `POST /mcp`: MCP server (JSON-RPC 2.0 over streamable HTTP). See [MCP](https://kilowatt.sh/docs/mcp).

## Inference (with the API key you receive at launch)

| Endpoint | Compatible with |
| --- | --- |
| `POST https://api.kilowatt.sh/v1/chat/completions` | OpenAI Chat Completions |
| `GET https://api.kilowatt.sh/v1/models` | OpenAI models list |
| `POST https://api.kilowatt.sh/v1/messages` | Anthropic Messages (Claude Code) |

Model ids: `deepseek-v4.1-flash`, `glm-5.3-flash`, and `auto` (router). Auth: `Authorization: Bearer <key>` (OpenAI) or `x-api-key` / `ANTHROPIC_AUTH_TOKEN` (Anthropic). Limit errors are HTTP 429 with `Retry-After`. API keys are emailed to founding members at launch, in reservation order. Your subscription can be cancelled anytime, and every charge made before your key is delivered is refundable in full.

---
Source: https://kilowatt.sh/docs/api · Markdown: https://kilowatt.sh/docs/api.md · All docs: https://kilowatt.sh/llms-full.txt