Guide — the developer loop

curl https://twin-browser.com/api/v1/run \
  -H "Authorization: Bearer ab_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.acme.com/invoices",
    "prompt": "export last month as CSV",
    "success": { "kind": "urlIncludes", "value": "/exports" }
  }'

# → 200 { "success": true, "path": [ … ], "credits_charged": 10, "engineRev": "…" }
#
# success is a structured condition — one of:
#   { "kind": "urlIncludes", "value": "…" }   { "kind": "textVisible", "value": "…" }
#   { "kind": "statusText", "match": "…" }    { "kind": "extracted" }
#   { "kind": "allOf" | "anyOf", "conditions": [ … ] }

# A sign-in run that hits a 2FA/approval wall PARKS by default (hitl) instead of failing:
# → 200 { "status": "paused", "sessionId": "…", "reason": "…", "challenge": "sms-code" }
#
# Three ways forward from a paused run:
#   1. POST /api/v1/runs/{id}/resume   { "sessionId": "…", "code": "123456" }
#   2. Watch + drive it yourself:
#        GET  /api/v1/runs/{id}/stream          (SSE screencast, free)
#        POST /api/v1/runs/{id}/input           { "event": { "kind": "click", "x": 0.42, "y": 0.61 } }
#        (coordinates are 0..1 viewport fractions; kinds: click | fill | key | scroll | goto)
#   3. POST /api/v1/connect/sessions — send your END-USER a link to sign in by hand.
#
# Two result codes tell you what a run needs:
#   "code": "credential_missing" + missingSecret → store it via POST /secrets, or use a connect link
#   "code": "connect_required"  + connectUrl     → a ready one-time link; hand it to the user

# Same body as /run — but fronted by the semantic cache:
curl https://twin-browser.com/api/v1/dispatch \
  -H "Authorization: Bearer ab_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.acme.com/invoices",
    "prompt": "download last month'"'"'s invoices as a CSV",
    "success": { "kind": "urlIncludes", "value": "/exports" }
  }'

# HIT  → your re-phrased request matches an already-compiled skill for that host:
#        deterministic blind replay, no LLM              (~2 credits)
# MISS → live discovery + minimize, then cached with its embedding
#        so the NEXT similar request is a hit            (~10 credits)
# The verified action path is returned in BOTH modes.

# Or manage skills explicitly:
#   POST /api/v1/skills                  { "target": "…", "goal": "…", "as": "acme-export" }   (~50 cr)
#   POST /api/v1/skills/acme-export/run  → deterministic replay, no LLM                        (~1 cr)
#   GET  /api/v1/skills                  → list compiled skills

curl https://twin-browser.com/api/v1/extract \
  -H "Authorization: Bearer ab_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com",
    "fields": ["title", "points", "url"]
  }'

# → 200 { …structured result…, "credits_charged": 5 }
#
# Describe the output with "fields" (flat list) or "schema" (JSON-schema-like) —
# or neither: a per-host extraction template (see GET /api/v1/templates) matches
# many URLs and returns structured data deterministically, zero LLM, 0 metered cost.
#   "template": "name" forces one; "template": false disables (then schema/fields required)
#   "waitMs": 2000 adds settle time for JS-hydrated pages

# Run a goal and stream the LIVE browser view back as Server-Sent Events:
curl -N https://twin-browser.com/api/v1/live \
  -H "Authorization: Bearer ab_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "url": "…", "prompt": "…", "success": { "kind": "extracted" } }'

# event: meta    → { "runId": "…" }
# event: frame   → JPEG frames of the browser
# event: step    → on a 2FA wall: { "type": "await-user", "token": "…", "challenge": "sms-code" }
#                  answer with POST /api/v1/live/resume { "token": "…", "code": "123456" }
# event: result  → terminal result; a durable video is then at GET /api/v1/runs/{id}/video

# Prefer fire-and-forget? Submit the same body as an async job:
#   POST /api/v1/jobs → 202 { "jobId": "…" }     (optional callbackUrl + callbackSecret,
#   GET  /api/v1/jobs/{id}                        HMAC-signed completion webhook)
#   GET  /api/v1/jobs/{id}/stream                 (SSE status frames instead of polling)
#   POST /api/v1/jobs/{id}/cancel                 (full refund of reserved credits)

# Mint a one-time link your END-USER opens to sign in by hand — password, 2FA,
# CAPTCHA — inside a Twin-Browser-hosted browser. The session is captured; the
# password is never stored.
curl https://twin-browser.com/api/v1/connect/sessions \
  -H "Authorization: Bearer ab_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "host": "linkedin.com", "account": "work", "redirectUri": "https://yourapp.com/done" }'

# → 201 { "id": "…", "url": "https://…", "expiresAt": "…", "ttlMinutes": 30 }
#   (the url is shown once; the link is scoped to that one host)

# Check whether the user finished before re-running:
#   GET /api/v1/connect/sessions
#   → { "sessions": [{ "id", "host", "account", "status", … }] }
#     status: pending | active | connected | failed | expired | cancelled

# Re-run the original task afterwards → "sessionRestored": true — already logged in.

# Store credentials once, reference them by name — values are write-only,
# encrypted at rest, and redacted from every log and stream:
curl https://twin-browser.com/api/v1/secrets \
  -H "Authorization: Bearer ab_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ACME_PASSWORD", "value": "…" }'

# Then in a prompt: "sign in as jo@acme.com with {{secret:ACME_PASSWORD}}"

# Which logins do I already have? (metadata only — never a credential)
#   GET /api/v1/accounts?host=acme.com
#   → { "accounts": [{ "label": "work", "host": "acme.com", "emailPreview": "j…@acme.com" }] }
# Pass a label as "account" on any run and that login + its saved session apply.