webdoc API

The webdoc 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.

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.

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 a Webdoc-Signature header. Compute HMAC-SHA256 of the raw request body using your webhook secret and compare with timing-safe equality.

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

Retries

webdoc retries failed deliveries up to 5 times with exponential backoff: 30s, 5m, 30m, 2h, 8h. 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.

Findings

Benchmark

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.

Metadata