# siteglass — agent integration guide

**You built or edited a web app. siteglass tests what you actually shipped.**

Point it at your app's URL and siteglass crawls it in a real headless
browser, has an LLM map what's there, **derives end-to-end test flows**
(sign-up, login, search, checkout…), **runs them**, and hands back per-step
pass/fail with screenshots, a video, and a full DOM session replay. When a
selector drifts (because your last edit moved the DOM), it **self-heals**
the step at runtime. No install, no CI, no SDK — just HTTP/JSON.

It's built for agents: **authenticate with an API key or a Nostr keypair —
no email, no browser, no human in the loop.**

Base URL: `https://siteglass.io` · All requests/responses are JSON.

---

## 1. Authenticate (pick one)

**API key (simplest).** Create an account and keep the key:

```bash
curl -sX POST https://siteglass.io/api/signup -d '{}'
# -> { "account_id": "...", "api_key": "sgk-like-token", ... }
```

Send it on every call: `Authorization: Bearer <api_key>`. Generate more
named keys later with `POST /api/auth/api-keys {"label":"ci-bot"}`.

**Nostr keypair (stateless, no stored secret).** Sign each request as a
NIP-98 event (kind 27235) and send `Authorization: Nostr <base64(event)>`.
Bootstrap an account from just your pubkey:

```bash
# event = {kind:27235, created_at:<now>, content:"",
#          tags:[["u","https://siteglass.io/api/auth/nostr"],["method","POST"]]}
# sign it (id = sha256 of the NIP-01 serialization, sig = BIP-340 schnorr)
curl -sX POST https://siteglass.io/api/auth/nostr \
  -H "Authorization: Nostr $(printf '%s' "$EVENT_JSON" | base64 -w0)"
# -> { account_id, session_token, api_key, pubkey }
```

Thereafter send the same `Authorization: Nostr <event>` header (re-signed
per request, u-tag = the request URL) on any endpoint — fully stateless.

A `session_token` from login also works as a `Bearer` token.

## 2. Register the app and prove you control it

```bash
curl -sX POST https://siteglass.io/api/sites \
  -H "Authorization: Bearer $KEY" -d '{"domain":"https://myapp.example.com"}'
# -> { site_id, verify_token, instructions: { dns_txt, well_known, meta_tag } }
```

Do **one** of (pick whichever your stack makes easy — vibecoded apps on
`*.vercel.app` / `*.lovable.app` usually do the meta tag):

- DNS: a `TXT` record `siteglass-verify=<verify_token>`
- File: serve `<verify_token>` at `/.well-known/siteglass.txt`
- Meta: `<meta name="siteglass-verify" content="<verify_token>">` on the homepage

```bash
curl -sX POST https://siteglass.io/api/sites/$SITE/verify -H "Authorization: Bearer $KEY"
# -> { verified: true, method: "meta" | "dns-txt" | "well-known" }
```

(Targets can include a scheme + port, e.g. `http://localhost:3000`, for
local/preview builds.)

## 3. Scan it

```bash
CRAWL=$(curl -sX POST https://siteglass.io/api/sites/$SITE/crawl \
  -H "Authorization: Bearer $KEY" | jq -r .crawl_id)
# poll until DONE:
curl -s https://siteglass.io/api/crawls/$CRAWL -H "Authorization: Bearer $KEY"
# -> { status, page_count, discovered, report_md, findings:[...], pages:[...] }
```

`findings` are deterministic (HTTP errors, slow loads, missing meta,
forms). `report_md` is the LLM narrative of what the site is and how it's
organized.

## 4. Generate and run test flows

```bash
# derive executable flows from the scan
curl -sX POST https://siteglass.io/api/crawls/$CRAWL/flows -H "Authorization: Bearer $KEY"
# -> { flows: [ { id, name, description, destructive } ] }

# run one (full=false dry-runs destructive submits; full=true submits for real)
RUN=$(curl -sX POST https://siteglass.io/api/flows/$FLOW/run \
  -H "Authorization: Bearer $KEY" -d '{"full":false}' | jq -r .run_id)

curl -s https://siteglass.io/api/flow-runs/$RUN -H "Authorization: Bearer $KEY"
# -> { status, passed, failed, skipped, repaired,
#      steps:[ { idx, action, description, status, error, url,
#                screenshot_url, target, repaired_to } ],
#      video_url, rrweb_url }
```

Step `status` is `ok | fail | skipped | repaired`. A `repaired` step shows
the original locator (`target`) and the LLM's fix (`repaired_to`) — useful
signal that your last change moved something. `video_url` and `rrweb_url`
are capability URLs (the run id is the token) you can embed or replay.

## 5. Authenticated flows (test behind login)

Flows use `{{username}}` / `{{password}}` placeholders. Give siteglass a
test account two ways:

- **Provide one** (existing test user):
  `POST /api/sites/$SITE/credentials {"vars":{"username":"...","password":"..."}}`
- **Let it make one**: **Run Full** a sign-up flow — siteglass generates
  credentials, actually registers the account, and (on success) stores
  them as this site's test credentials. Login flows then run authenticated.

---

## Minimal end-to-end (one block)

```bash
B=https://siteglass.io; KEY=$(curl -sX POST $B/api/signup -d '{}' | jq -r .api_key)
H="Authorization: Bearer $KEY"
SITE=$(curl -sX POST $B/api/sites -H "$H" -d '{"domain":"https://myapp.example"}' | jq -r .site_id)
# ...place the verify token, then:
curl -sX POST $B/api/sites/$SITE/verify -H "$H"
CRAWL=$(curl -sX POST $B/api/sites/$SITE/crawl -H "$H" | jq -r .crawl_id)
# poll $B/api/crawls/$CRAWL until DONE, then:
curl -sX POST $B/api/crawls/$CRAWL/flows -H "$H"
# run each flow id from the response and read $B/api/flow-runs/<run_id>
```

## Notes

- **Payment**: the first scan per site is free; after that, scans (2 credits)
  and flow runs (1 credit) draw from a prepaid **credit** balance. Top up in
  USD — `POST /api/account/topup {"usd":10}` returns a Lightning invoice; pay
  it and credits land. Balance + costs are on `GET /api/account`.
- **Feedback**: tell us anything — `POST /api/feedback {"message":"…","context":"…"}`
  (the optional `context` is wherever you are, e.g. a URL or step). Same auth.
- **Idempotency**: re-running a saved flow is a regression test — wire it
  into your build loop and re-run after each change set.
- **Determinism caveat**: flows are LLM-derived; treat a green run as a
  smoke signal, and read the screenshots/replay for anything that matters.

Questions / preview access: open an account at `https://siteglass.io/portal`.