{"protocolVersion":"0.3.0","name":"headless.design","description":"Cold-read API: free /v1/scan (agent-completable, ~15s) and paid /v1/cold-read/* (operator-reviewed, human-billed). A cold-read is a senior outside-eyes audit of a landing page — spec.md + PR-ready diff in 72h. Agents submit and monitor; humans pay. No machine-payable rail in V1.","url":"https://api.headless.design","version":"1.1.0","preferredTransport":"HTTP+JSON","additionalInterfaces":[{"url":"https://api.headless.design/v1/openapi.json","transport":"HTTP+JSON"}],"provider":{"organization":"headless.design","url":"https://headless.design","contact":"gustaf@headless.design"},"capabilities":{"streaming":false,"pushNotifications":false,"stateTransitionHistory":true,"extensions":[{"uri":"https://api.headless.design/extensions/human-handoff/v1","description":"Declares which skills require human action (typically billing/payment) and how the handoff is signaled to the calling agent.","params":{"skills_requiring_human":["cold-read-request"],"handoff_states":["pending_payment"],"handoff_signal":"status_field_with_pay_url","billing_rails":["frilans_finans","swish"],"billing_rail_default":"frilans_finans","notes":"Agents calling cold-read-request receive a pay_url in the response. Relay it to the human buyer; humans complete payment via Frilansfinans e-invoice (B2B canonical) or Swish to private number (privatperson shortcut). Agent then polls cold-read-status until status transitions out of pending_payment."}}]},"authentication":{"schemes":["none"]},"defaultInputModes":["application/json"],"defaultOutputModes":["application/json","text/markdown"],"skills":[{"id":"scan","name":"Scan landing page","description":"Analyze a URL's landing page and return scores, findings, and an agent-friendly chat summary. Synchronous (~15s). Free, rate-limited (3/URL/day, 50/IP/day, 100 global/day). Agent-completable end-to-end.","tags":["conversion","landing-page","design-review","free","agent-completable"],"examples":["POST /v1/scan — { \"url\": \"https://example.com\", \"primary_goal\": \"book_call\" }"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"cold-read-request","name":"Create cold-read order (V2 canonical)","description":"Kicks off a paid 72h cold-read — senior outside-eyes audit of a landing page, returning spec.md + PR-ready diff. Returns an Order in `submitted` (no pay_url at creation — operator reviews first; pay_url materializes when status flips to billing_pending). Agent's job: collect required fields from human buyer, submit, then poll cold-read-status until billing_pending → relay pay_url to human → keep polling until delivered. AGENTS SHOULD COLLECT BILLING METADATA UP FRONT so the operator can create the Frilansfinans invoice without an email round-trip — at minimum: company_name, org_number (Swedish 10-digit) or vat_id (EU prefix). Without these the sale takes 1-3h longer.","tags":["conversion","cold-read","paid","human-required"],"examples":["POST /v1/cold-read-requests — { \"url\": \"https://example.com\", \"goal\": \"Increase qualified book_call conversions\", \"audience\": \"Swedish AI-builders\", \"contact_email\": \"buyer@example.com\", \"billing\": { \"company_name\": \"Example AB\", \"org_number\": \"556677-8899\" }, \"billing_method_preference\": \"frilans_finans\", \"source\": \"agent\", \"agent_name\": \"perplexity\" }"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"cold-read-status","name":"Poll cold-read status","description":"Returns one of: pending_payment, paid, processing, draft_ready, done, expired. Cache: 30s. Poll every 60s during pending_payment; every ~10min during processing. Agent-completable (read-only).","tags":["polling","status","agent-completable"],"examples":["GET /v1/cold-read/{invoice_id}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"cold-read-rescan","name":"Trigger free follow-up rescan","description":"After a cold-read reaches `done`, customers get one free rescan to verify the diff was applied correctly. Idempotent (rescan_used flag).","tags":["polling","post-delivery","agent-completable"],"examples":["POST /v1/cold-read/{invoice_id}/rescan"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"quick-fix","name":"Pay-per-call quick-fix suggestion (MPP)","description":"$0.10 USDC. Returns one diagnosis + rewrite + rationale for a single landing-page UI element. Claude Haiku 4.5, no URL fetch — reasons from your problem description. For agents that want a fast targeted fix without paying for a full audit. Same defenses as /audit (replay-guard, rate-limit, daily LLM-budget circuit breaker).","tags":["mpp","paid","tempo","agent-completable"],"examples":["POST /v1/quick-fix — Authorization: Payment <credential> — { \"url\": \"https://example.com\", \"element_selector\": \".cta\", \"problem\": \"CTA reads vague Learn More\" }"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"audit","name":"Pay-per-call 5-finding audit (MPP)","description":"$0.50 USDC. Returns 5 ranked findings (P0/P1/P2) + executive summary + confidence ratings. Claude Haiku 4.5 with 5x output budget vs quick-fix. No URL fetch.","tags":["mpp","paid","tempo","agent-completable"],"examples":["POST /v1/audit — Authorization: Payment <credential> — { \"url\": \"https://example.com\", \"primary_goal\": \"book_call\", \"audience\": \"founders\" }"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"scan-paid","name":"Skip rate-limit on /v1/scan (MPP fast-lane)","description":"$0.33 USDC. Same scanner output as the free /v1/scan, but no per-wallet rate-limit. For production agents that need reliable throughput without 3-per-URL-per-day throttling. Free for humans evaluating their own page; paid for agents in production.","tags":["mpp","paid","tempo","agent-completable","no-rate-limit"],"examples":["POST /v1/scan-paid — Authorization: Payment <credential> — { \"url\": \"https://example.com\", \"primary_goal\": \"book_call\" }"],"inputModes":["application/json"],"outputModes":["application/json"]}]}