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

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

Retry 429 and 5xx responses with exponential backoff. Do not retry 400, 401, 402, or 422 — they will fail identically until the request or account state changes.

Rate limits

60 requests per minute per API key — a 429 with a Retry-After header (seconds) when exceeded. Each key also has a monthly scan quota, surfaced via the X-RateLimit-* response headers. The 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": "sc_3f9a2c7e8b1d4f60",  "url": "https://acme-saas.com",  "score": 61,  "verdict": "Fair",  "scanned_at": "2026-06-14T12:00:00.000Z",  "pages_scanned": 1,  "page_type": "homepage",  "findings_summary": 23,  "dimensions": {    "conversion_architecture": 58,    "trust_signals": 79,    "message_clarity": 71,    "traffic_readiness": 44,    "technical_foundation": 65,    "objection_handling": 41,    "offer_clarity": 53  },  "findings": [    {      "id": "finding_001",      "title": "Hero headline is feature-led, not outcome-led",      "severity": "critical",      "dimension": "Conversion Architecture",      "impact": "high",      "impact_estimate": "12-18% conversion lift",      "explanation": "Headline names the feature set, not the customer outcome.",      "fix_steps": ["Lead with the outcome", "Name the audience", "Trim to one supporting line"],      "rewritten_copy": "Ship every project on time — wherever your team works.",      "confidence": "high",      "fix_effort": "hours",      "priority": 1    }  ],  "copy_rewrites": {    "headline": "Ship every project on time — wherever your team works",    "subheadline": "The project workspace built for distributed teams.",    "cta": "Start free"  },  "metadata": { "word_count": 1240, "cta_count": 3, "tech_stack": ["Next.js", "Vercel"] },  "scan_meta": { "site_type": "saas", "duration_ms": 87340, "cost_usd": 0.15, "tokens_used": 18240, "cached": false }}

POST /api/v1/scan/batch

Submit up to 10 URLs in a single request. Synchronous by default — returns a results array plus a summary object. Pass async: true for a 202 with batch_id, scan_ids, and poll_urls; each result is delivered to your registered webhook endpoints as it completes.

GET /api/v1/scans

Retrieve a list of your scans, most recent first.

Each response adds next_cursor (a string, or null on the last page) and has_more (boolean) alongside scans. Paginate by passing next_cursor back as cursor until has_more is false.

GET /api/v1/scans/{id}

Retrieve a single scan by ID.

POST /api/v1/webhooks

Register a webhook endpoint. Weavn 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

Remove a registered webhook by id, passed in the JSON body. No further deliveries are attempted to that endpoint. Returns a deleted:true acknowledgement.

Webhooks

Weavn 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-Weavn-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 Weavn 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

How the overall score was weighted for this site's classification. An object carrying the weighted score, the profile label, and the per-dimension weights applied.

Findings

Full-depth findings (the default). With finding_depth: 'brief', each finding is trimmed to id, title, severity, dimension, explanation, and confidence.

Findings summary

A single integer: the total number of findings in the findings array. Use it for dashboard display without iterating the array.

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

Coverage scores across the 7 revenue dimensions. Each value is an integer 0–100; the weight each dimension contributes to the overall score is returned separately in score_profile.weights.

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 & scan_meta

Two objects accompany every scan: metadata describes the scanned page, scan_meta describes the run and its billing. Note scan_id, url, and scanned_at are top-level response fields — not nested here.