# Make A Website — Agent API

Build and manage real, hosted websites from an AI agent. The agent is authorized into a **user's** Make A Website account and acts on their behalf.

- **Base URL:** `https://api.makeawebsite.app/api/v1`
- **Auth:** a bearer token (`maw_agt_live_…`) obtained via the linking flow below.
- **Billing:** the agent's work spends the **user's** plan (Pro / Fast Passes). There's no separate agent billing.

## 1. Link the agent (one time, per user)

The agent can't sign itself up — its human authorizes it in the Make A Website app (OAuth 2.0 device-authorization flow).

```bash
# a) Start: get a code + QR to show the user, and a device_code to poll with.
curl -X POST $BASE/agents/link/start -H 'content-type: application/json' \
  -d '{"agent_name":"My Agent"}'
# → { "user_code":"WXYZ-1234", "verification_url":"https://makeawebsite.app/link?code=WXYZ-1234",
#     "qr":"data:image/png;base64,…", "device_code":"…", "expires_in":600, "interval":5 }

# b) Tell the user: open the app → Settings → Linked agents → enter WXYZ-1234 (or scan the QR) → Authorize.

# c) Poll until approved (every `interval` seconds). 400 {error:"authorization_pending"} until then.
curl -X POST $BASE/agents/link/poll -H 'content-type: application/json' \
  -d '{"device_code":"…"}'
# → { "access_token":"maw_agt_live_…", "token_type":"Bearer", "scope":"sites analytics forms domains" }
```

Use the token on every call: `Authorization: Bearer maw_agt_live_…`. The user can revoke it anytime in the app.

## 2. Create a website from a description

No interview — just describe the site. Build is async (~1-3 min); poll status.

```bash
curl -X POST $BASE/sites -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d '{"description":"A cozy specialty coffee shop in Da Nang called Drift Coffee. Single-origin pour-overs, espresso, pastries. 7am-6pm. Warm, minimalist. Menu + contact."}'
# → 201 { "id":"351", "name":"Drift Coffee", "status":"queued", "preview_url":"https://….mksite.app", … }

curl $BASE/sites/351/status -H "authorization: Bearer $T"
# → { "status":"live", "phase":"ready"|"building"|"failed", "preview_url":"https://….mksite.app" }
```

## 3. Endpoints

| Method · Path | What |
|---|---|
| `GET /account` | The user's plan: `{plan, pro_until, fast_passes, fast_passes_monthly, can_build_now}` |
| `POST /sites` | Create from `{description, name?}` → the site (async build) |
| `GET /sites` | List the user's sites |
| `GET /sites/:id` | One site |
| `GET /sites/:id/status` | Build status (poll) |
| `POST /sites/:id/changes` | Iterate: `{message:"add a booking section"}` → async rebuild |
| `PATCH /sites/:id` | Edit `{name?, description?}` |
| `DELETE /sites/:id` | Delete the site |
| `GET /sites/:id/analytics` | `{ "7d":{views,conversions}, "30d":…, "all":… }` |
| `GET /sites/:id/submissions` | Form submissions (most recent first) |
| `GET /sites/:id/domain` | The connected custom domain + records + live state |
| `POST /sites/:id/domain` | Connect `{domain}` → the DNS records the user adds (CNAME, no nameserver move) |
| `DELETE /sites/:id/domain` | Disconnect the custom domain |

## 4. Errors

- `401 {error:"invalid_token"}` — missing/revoked token.
- `404 {error:"not_found"}` — site not in this user's account.
- `409 {error:"build_in_progress"}` — a change is already building; wait.
- `429 {error:"rate_limited"}` — too many builds/changes in a short time; back off + retry.
- **`402 payment_required`** — the action needs the user to pay:
  ```json
  { "error":"payment_required", "reason":"free_limit_reached"|"needs_pro"|"out_of_fast_passes",
    "message":"…", "upgrade_url":"https://agents.makeawebsite.app/upgrade" }
  ```
  Payment is Apple in-app purchase — **the agent can't pay**; surface `upgrade_url` (or "open the app and upgrade") to the user, who pays in the app, then retry. Read `GET /account` first to avoid hitting this.

## 5. Scope

A linked agent can do everything in the table above (manage sites, analytics, forms, domains). It **cannot** touch billing/subscription, buy Fast Passes, or delete the account — those stay with the user.

*Status: implemented + live on `api.makeawebsite.app`. Public developer docs/OpenAPI + agent discoverability (llms.txt / skill directory) are a later step.*