Structured metadata output

Request

{
  "url": "https://example.com/article",
  "output": "metadata",
  "wait_for": { "event": "load", "selector": "main", "timeout_ms": 15000 },
  "fail_on_status": [404, 429, 500, 502, 503]
}

The response is application/json with filename vipercapture-metadata.json and costs one credit. It is produced after navigation, waits, custom CSS, cleanup, CAPTCHA checks, and lazy loading, so it describes the final DOM rather than the original response bytes.

Schema

{
  "title": "Page title",
  "description": "Meta description or null",
  "canonical_url": "https://example.com/canonical",
  "language": "en",
  "robots": "index,follow",
  "theme_color": "#ffffff",
  "open_graph": { "og:title": "Page title" },
  "twitter": { "twitter:card": "summary_large_image" },
  "icons": [
    { "rel": "icon", "href": "https://example.com/favicon.ico", "sizes": null, "type": "image/x-icon" }
  ],
  "headings": [{ "level": 1, "text": "Main heading" }],
  "links": {
    "total": 23,
    "sample": [{ "text": "About", "href": "https://example.com/about" }]
  },
  "source_type": "url",
  "final_url": "https://example.com/article",
  "navigation_status": 200,
  "blocked_subresources": 0,
  "schema_version": 1
}

String values are trimmed and capped at 2,048 characters. Meta maps contain at most 32 first-seen keys; icons at most 16; headings and sampled links at most 100 each. links.total counts all anchors even when only the first 100 are returned. Missing scalar values are null. Duplicate meta keys keep the first value.

Renderer fields

ViperCapture appends schema_version, source_type, final_url, navigation_status, and blocked_subresources. Inline HTML/Markdown has a null navigation status and uses its resolved page URL. Do not publish metadata documents blindly: final URLs and DOM metadata may contain user-specific or sensitive information.

Limitations

The response describes one rendered page. It is not a recursive crawl, sitemap, accessibility audit, or SEO score. It does not follow sampled links. Send a separate request for each authorized public page and follow the site’s terms and rate limits.