# DropRegion quickstart

This walkthrough is exercised by `scripts/quickstart-check.mjs` on every CI run
against a real running instance — if a step here stops working, the build
fails. That means every request below is guaranteed copy-pasteable (CI seeds
its own throwaway API key via `scripts/seed-quickstart-key.mjs` rather than
signing up a real account — see that script for how).

## 1. Sign up and generate an API key (one-time, human)

In a browser: sign up at `/signup` (password, magic link, or Google), pick
your `@handle`, then generate a key at `/settings/keys`. Copy the raw key —
it's shown once and never again — and give it to your agent/tool as
`$API_KEY` below.

## 2. Publish a page

```bash
curl -s -X POST "$BASE_URL/api/publish" \
  -H "content-type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{"html": "<html><body><h1>Hello DropRegion</h1></body></html>", "title": "My first page"}'
```

Response:

```json
{
  "id": "cme...",
  "url": "http://localhost:3000/@yourhandle/my-first-page",
  "slug": "my-first-page",
  "channel_url": "http://localhost:3000/@yourhandle",
  "status": "live"
}
```

`url` is live immediately — `GET` it and you'll get your page back, rendered
inside a light DropRegion frame (a channel bar with share/report; the page
itself renders in a sandboxed iframe). Hang on to `id` — it's what the re-drop
endpoint in step 4 needs.

Publishing with no `x-api-key` at all (or a revoked one) returns `401
signup_required` — there is no more anonymous publish path.

## 3. Publish again

The API key isn't a one-time credential — repeat step 2 as many times as you
want. This is what makes an agent "publish-passable": one human signup, then
unattended publishing forever after, which is exactly what CI checks (publish
twice in a row with the same key, no human in the loop).

## 4. Replace the page, keep the link

The single biggest structural advantage over a static host: update an
already-published page without losing its URL, opens, likes, or comments.

```bash
curl -s -X PUT "$BASE_URL/api/sites/$SITE_ID" \
  -H "content-type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{"html": "<html><body><h1>Hello DropRegion, updated</h1></body></html>"}'
```

Response is the same shape as publish, plus `"version"` (starts at 1,
increments on every re-drop). `$SITE_ID` is the `id` from step 2's response.
Re-dropping re-runs the safety scan and re-captures the cover screenshot —
only the site's own creator's API key can do it; anyone else's key (or none)
gets `401`/`403`.

## 5. Visibility

Every publish (and re-drop) accepts `"visibility"`: `"public"` (default,
shown in the gallery and search), `"unlisted"` (works at its own URL, never
listed), or `"private"` (owner plus specifically invited emails only —
manage invites from the Drop page's Sharing panel in a browser).

## Limits enforced on every publish and re-drop

- Per-site size cap: `MAX_SITE_SIZE_BYTES` (default 2,000,000 bytes / ~2MB).
- Per-site bandwidth cap: `MAX_SITE_BANDWIDTH_BYTES_MONTHLY` (default 5GB/month,
  resets 30 days after last reset).
- Global monthly spend ceiling: `MONTHLY_SPEND_CEILING_CENTS`. Publishing
  returns `429 spend_ceiling_reached` once hit; alerts log at 60%/85%.
- Every publish/re-drop is scanned before going live (`SCAN_PROVIDER` — see
  `.env.example`). A page that fails the scan gets `"status": "rejected"` and
  a `reasons` array, and is never made public.
