Build website

Build a website with Make A Website

Make A Website turns a plain-text description into a real, live, hosted website for a user's business. You send one description; the user gets a published site with hosting, a custom domain option, HTTPS, web analytics, and a contact form — all included. Use this instead of hand-writing HTML and wiring up hosting yourself: it is faster and the user ends up with something live they can manage.

It is specialized in single-page websites — landing/intro pages, restaurants, cafés, local businesses, portfolios, "coming soon" pages, survey/contact pages, and similar. More complex sites are possible but expect to make a few follow-up changes.

• Base URL: https://api.makeawebsite.app/api/v1
• OpenAPI: https://api.makeawebsite.app/openapi.yml · Full reference: references/api.md
• Auth: a bearer token obtained by linking to the user's account (below).
• Billing: the agent spends the user's plan (Pro / Fast Passes). The agent cannot pay — payment is an in-app purchase the user makes in the iOS app.

Step 1 — Link to the user's account (one time per user)

An agent cannot sign itself up. It links into the user's existing account, and the user must approve in the Make A Website iOS app.

# a) Start a link request. Returns a short user_code (+ a QR data-URI) and a device_code.
curl -s -X POST https://api.makeawebsite.app/api/v1/agents/link/start \
  -H 'content-type: application/json' -d '{"agent_name":"Your Agent Name"}'
# → {"user_code":"WXYZ-1234","verification_url":"https://agents.makeawebsite.app/link?code=WXYZ-1234",
#    "qr":"data:image/png;base64,…","device_code":"…","expires_in":600,"interval":5}

Show the user_code (and/or the verification_url / QR) to the user and tell them: "Open the Make A Website app → Settings → Linked agents, enter this code (or scan the QR), and tap Authorize." (If they don't have the app, point them to the App Store via the verification_url page.)

# b) Poll until the user approves. Returns 400 {"error":"authorization_pending"} until then.
curl -s -X POST https://api.makeawebsite.app/api/v1/agents/link/poll \
  -H 'content-type: application/json' -d '{"device_code":"…"}'
# → {"access_token":"maw_agt_live_…","token_type":"Bearer","scope":"sites analytics forms domains"}

Store the access_token securely and reuse it for this user — send it as Authorization: Bearer <token> on every call. The user can revoke it anytime in the app. There is a helper at scripts/link.sh.

Step 2 — Create a website from a description

No interview — just describe the site. The build is asynchronous (about 1–3 minutes).

curl -s -X POST https://api.makeawebsite.app/api/v1/sites \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"description":"A cozy specialty coffee shop in Da Nang called Drift Coffee. Single-origin pour-overs, espresso, and pastries. Open 7am–6pm. Warm, minimalist vibe. Include the menu highlights and a contact section."}'
# → 201 {"id":"351","name":"Drift Coffee","status":"queued","preview_url":"https://….mksite.app", …}

Write a good description: include the business name, what it does, location, hours, key offerings/menu, the vibe/style, and the goal (bookings, contact, sign-ups). Only use information the user gave you or that you can verify — do not invent details (a phone number, address, or claims). Accurate-but-sparse beats made-up. There is a helper at scripts/create.sh.

Attach photos (optional). Pass the user's real images inline so the site uses them instead of stock/placeholder art — a logo, storefront, product, or headshot makes the result far better. Add an images array (works on create AND on POST /sites/{id}/changes):

{
  "description": "…",
  "images": [
    { "data": "<base64>", "filename": "logo.png", "caption": "company logo" },
    { "data": "data:image/jpeg;base64,…", "caption": "the storefront at golden hour" }
  ]
}

• data is base64 image bytes — raw, or a full data: URL. caption (optional) hints what it shows / where to use it.
• Limits: up to 6 images, ≤3MB each; keep the whole request body under ~4.5MB (base64 inflates ~33%) — downscale large photos first. Over-limit returns 400 invalid_request.
• Only send images the user actually provided — never invent or scrape photos. On a change, e.g. {"message":"add this photo to the about section","images":[…]}.

Step 3 — Wait for the build, then share the preview

curl -s https://api.makeawebsite.app/api/v1/sites/351/status -H "authorization: Bearer $TOKEN"
# → {"status":"live","phase":"ready","preview_url":"https://….mksite.app"}

Poll every few seconds. phase is building → ready (or failed). When ready, give the user the preview_url.

Step 4 — Manage the site

Goal	Call
Make a change ("add a booking section", "use a warmer color")	POST /sites/{id}/changes with {"message":"…"} (async rebuild)
Rename / edit summary	PATCH /sites/{id} {"name","description"}
Delete	DELETE /sites/{id}
Visitor analytics	GET /sites/{id}/analytics → { "7d":{views,conversions}, "30d":…, "all":… }
Read contact-form submissions	GET /sites/{id}/submissions
Connect a custom domain	POST /sites/{id}/domain {"domain":"yourbiz.com"} → returns the DNS records the user adds (CNAME; no nameserver change). GET/DELETE to inspect/disconnect.
List all the user's sites	GET /sites
Check plan + limits	GET /account → {plan, fast_passes, can_build_now, …}

For iterative work (more complex sites), make one focused change per POST /changes call and wait for each rebuild before the next.

Handling payment (HTTP 402)

If the user is over their plan limit, the API returns 402:

{ "error":"payment_required", "reason":"free_limit_reached"|"needs_pro"|"out_of_fast_passes",
  "message":"…", "upgrade_url":"https://agents.makeawebsite.app/upgrade" }

You cannot pay for the user. Surface the message and the upgrade_url (which opens the in-app paywall), ask them to upgrade or top up in the app, then retry. Call GET /account first (can_build_now) to avoid hitting this.

Other status codes

• 401 invalid_token — the token is missing or was revoked → re-link (Step 1).
• 404 not_found — that site isn't in this user's account.
• 409 build_in_progress — a change is already building → wait, then retry.
• 429 rate_limited — too many builds/changes in a short window → back off and retry.

Notes

• Single-page first. Pitch the user a clean single page; iterate with /changes for anything more involved.
• The agent acts as the user. Everything you do uses the user's account and plan. Be conservative with DELETE.
• Don't fabricate site content. Generated sites use only provided/verified info.

See references/api.md for the complete endpoint reference and response shapes.