API Reference · v1

The Weavn API returns a structured conversion audit for any URL. POST a URL, get back a JSON object with a score, ranked findings, AI-rewritten copy, and industry benchmarks.

Base URL

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from the developer portal.

Keep your API key secret. Do not expose it in client-side code.

Errors

webdoc uses standard HTTP status codes. Error responses include a machine-readable code field for programmatic handling.

Rate limits

10 concurrent requests per API key. No per-minute limit. Batch endpoint accepts up to 10 URLs per request.

POST /api/v1/scan

Submit a URL for a full conversion audit. Returns synchronously by default, or via webhook in async mode.

RESPONSE · 200 OK

{  "scan_id": "scan_01HXYZ7K2M9N3P4Q",  "url": "https://acme-saas.com",  "score": 61,  "industry": "B2B SaaS",  "benchmark": {    "industry_avg": 54,    "top_quartile": 78,    "percentile": 63  },  "findings": [    {      "priority": 1,      "severity": "critical",      "category": "value_proposition",      "title": "Hero headline is feature-led, not outcome-led",      "estimated_lift": "12-18% conversion uplift",      "fix": "Rewrite to outcome-led, present tense."    }  ],  "rewritten_copy": {    "headline": "Ship projects on time, every time.",    "cta_primary": "Start free — no credit card"  },  "cost_usd": 0.15,  "duration_ms": 87340}

POST /api/v1/scan/batch

Submit up to 10 URLs in a single request. Always async — results delivered via webhook.

GET /api/v1/scans

Retrieve a list of your scans, most recent first.

GET /api/v1/scans/{id}

Retrieve a single scan by ID.

POST /api/v1/webhooks

Register a webhook endpoint. webdoc will POST a signed payload to your URL whenever the specified events occur.

GET /api/v1/webhooks

List all registered webhook endpoints for your API key.

DELETE /api/v1/webhooks/{id}

Remove a registered webhook. No further deliveries will be attempted to this endpoint.

Webhooks

webdoc sends a POST request to your webhook URL when an async scan completes or fails.

Register webhooks in the developer portal or via the webhooks API.

Events

Delivery

Every webhook POST includes an X-Webdoc-Signature header containing the HMAC-SHA256 hex of the raw request body. Verify it against your webhook secret using timing-safe comparison.

Your endpoint must respond with HTTP 200 within 10 seconds. Non-200 responses trigger a retry.

Retries

Webhooks are retried up to 3 times on failure. Attempt 1: immediate. Attempt 2: 5 minutes after failure. Attempt 3: 30 minutes after failure. Each attempt has a 10-second timeout. After 3 failures the webhook is marked failed and no further retries occur. Acknowledge immediately with 200 and process asynchronously to avoid timeouts.

Score

Integer 0–100. Benchmarked against all sites webdoc has scanned in the same industry category.

Page type

The page type classified by the scanner before check execution. Determines which page-type-specific checks apply.

Score profile

The weight profile used to compute the overall score. Reflects how dimension scores were weighted for this site's classification.

Findings

Findings summary

Triage counts computed from the findings array. Use this for dashboard display without iterating all findings.

Benchmark

Strengths

Top passing checks where this site performs genuinely above average. Only returned when checks pass with specific visible evidence. Array may be empty — never padded.

Rewritten copy

AI-rewritten alternatives for the most conversion-critical copy elements on the page.

Dimensions

Scores across each of the 8 revenue dimensions. Each contributes a weighted portion of the overall score.

Dimension benchmarks

Per-dimension scores benchmarked against corpus data for this site's vertical. Only present when the benchmark field is requested or the fields array is empty.

Metadata