Wayfern API reference

Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -X POST https://api.wayfern.com/api/tokens \
  -H "Authorization: Bearer <DASHBOARD_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI scraper",
    "scopes": ["search", "captcha", "mcp", "web"],
    "expiresAt": "2026-12-31T23:59:59.000Z"
  }'

{
  "token": {
    "id": "0f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
    "name": "CI scraper",
    "tokenPrefix": "wf_AbC3dEf",
    "scopes": ["search", "captcha", "mcp", "web"],
    "lastUsedAt": null,
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "revokedAt": null,
    "createdAt": "2026-06-22T10:00:00.000Z"
  },
  "plaintext": "wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

{
  "tokens": [
    {
      "id": "0f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "name": "CI scraper",
      "tokenPrefix": "wf_AbC3dEf",
      "scopes": ["search", "captcha", "mcp", "web"],
      "lastUsedAt": "2026-06-22T11:30:00.000Z",
      "expiresAt": null,
      "revokedAt": null,
      "createdAt": "2026-06-22T10:00:00.000Z"
    }
  ],
  "total": 1
}

import { chromium } from "playwright";

// Connect to a Wayfern browser by opening the CDP WebSocket with a link token.
// Sessions are created implicitly when this connection opens; there is no REST
// endpoint to "create" a session.
const browser = await chromium.connectOverCDP(
  "wss://browser.wayfern.com/ws?token=<LINK_TOKEN>",
);
const context = browser.contexts()[0];
const page = await context.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: "wss://browser.wayfern.com/ws?token=<LINK_TOKEN>",
});
const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await browser.disconnect();

wss://browser.wayfern.com/ws?token=<LINK_TOKEN>&country=US&region=CA&city=<CITY>&isp=<ISP>&session=run42

{
  "locations": [
    { "code": "US", "name": "United States" },
    { "code": "GB", "name": "United Kingdom" }
  ]
}

{
  "type": "connected",
  "connectionId": "0c2c3a1e-...",
  "instanceId": "inst-...",
  "contextId": "ctx-..."
}

curl -X POST https://api.wayfern.com/api/search/v1 \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "serverless browsers",
    "engines": ["google"],
    "limit": 10
  }'

{
  "query": {
    "text": "serverless browsers",
    "lang": "en",
    "region": "US",
    "engines_requested": ["google"]
  },
  "meta": {
    "request_id": "8a1f0c2e-7b3d-4e5f-9a0b-1c2d3e4f5a6b",
    "requested_at": "2026-06-22T10:00:00.000Z",
    "took_ms": 842,
    "engines_failed": [],
    "version": "2.1"
  },
  "results": [
    {
      "rank": 1,
      "absolute_rank": 1,
      "type": "organic",
      "url": "https://example.com/serverless-browsers",
      "title": "Serverless Browsers, Explained",
      "description": "A practical guide to running headless browsers at scale.",
      "ad": false,
      "engine": "google"
    }
  ],
  "serp_features": [
    {
      "type": "people_also_search",
      "engine": "google",
      "title": "People also search for",
      "items": [
        {
          "query": "headless browser automation",
          "url": "https://www.google.com/search?q=headless+browser+automation"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "has_more": true,
    "next_start": 50
  }
}

{
  "engines": [
    { "id": "google", "label": "Google" },
    { "id": "bing", "label": "Bing" },
    { "id": "duckduckgo", "label": "DuckDuckGo" }
  ]
}

{
  "error": "captcha_detected",
  "code": 429,
  "request_id": "8a1f0c2e-7b3d-4e5f-9a0b-1c2d3e4f5a6b",
  "message": "captcha_detected",
  "reason": "google"
}

{
  "error": "blocked",
  "code": 403,
  "request_id": "3b7c1d0e-9f2a-4c58-8d31-6e0a5b4c7d92",
  "message": "blocked: https://example.com/pricing",
  "reason": "https://example.com/pricing"
}

curl -X POST https://api.wayfern.com/api/v1/scrape \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "formats": ["markdown", "links"],
    "onlyMainContent": true,
    "maxAge": 3600000
  }'

{
  "success": true,
  "data": {
    "markdown": "# Pricing\n\nStart free, then pay for what you use.",
    "links": [
      {
        "url": "https://example.com/docs",
        "text": "Documentation",
        "external": false,
        "rel": []
      }
    ],
    "metadata": {
      "title": "Pricing - Example",
      "description": "Usage-based pricing with no seat fees.",
      "language": "en",
      "canonical": "https://example.com/pricing",
      "robots": "index, follow",
      "author": null,
      "publishedTime": null,
      "modifiedTime": "2026-07-01T09:12:00.000Z",
      "keywords": ["pricing", "plans"],
      "favicon": "https://example.com/favicon.ico",
      "themeColor": "#070314",
      "siteName": "Example",
      "openGraph": {
        "title": "Pricing - Example",
        "type": "website",
        "image": "https://example.com/og/pricing.png"
      },
      "twitter": { "card": "summary_large_image" },
      "jsonLd": [],
      "statusCode": 200,
      "sourceUrl": "https://example.com/pricing"
    },
    "cached": false
  },
  "credits": 1
}

curl -X POST https://api.wayfern.com/api/v1/crawl \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.example.com",
    "limit": 200,
    "maxDepth": 3,
    "includePaths": ["^/docs/"],
    "excludePaths": ["^/docs/changelog/"],
    "delay": 250,
    "concurrency": 3,
    "webhook": {
      "url": "https://api.example.com/hooks/wayfern",
      "events": ["page", "completed", "failed"],
      "metadata": { "runId": "nightly-42" }
    },
    "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true }
  }'

# Poll the job (free), then read a page of results.
curl -G "https://api.wayfern.com/api/v1/crawl/4f1c9b2a-6d3e-4a17-9c88-0b5e2f7a1d34" \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "skip=0" \
  --data-urlencode "limit=25"

{
  "success": true,
  "data": {
    "id": "4f1c9b2a-6d3e-4a17-9c88-0b5e2f7a1d34",
    "status": "queued",
    "completed": 0,
    "failed": 0,
    "limit": 200,
    "creditsUsed": 0,
    "createdAt": "2026-07-20T09:14:11.002Z",
    "updatedAt": "2026-07-20T09:14:11.002Z",
    "error": null,
    "expiresAt": "2026-07-27T09:14:11.002Z"
  },
  "credits": 0
}

{
  "success": true,
  "data": {
    "job": {
      "id": "4f1c9b2a-6d3e-4a17-9c88-0b5e2f7a1d34",
      "status": "scraping",
      "completed": 12,
      "failed": 1,
      "limit": 200,
      "creditsUsed": 12,
      "createdAt": "2026-07-20T09:14:11.002Z",
      "updatedAt": "2026-07-20T09:14:22.481Z",
      "error": null,
      "expiresAt": "2026-07-27T09:14:11.002Z"
    },
    "data": [
      {
        "markdown": "# Quickstart\n\nInstall the SDK and make your first call.",
        "metadata": {
          "title": "Quickstart - Example Docs",
          "statusCode": 200,
          "sourceUrl": "https://docs.example.com/quickstart"
        },
        "cached": false
      }
    ]
  },
  "credits": 12
}

{
  "success": true,
  "data": {
    "errors": [
      {
        "url": "https://docs.example.com/legacy",
        "error": "not_found",
        "message": "not_found: https://docs.example.com/legacy",
        "at": "2026-07-20T09:14:19.774Z"
      }
    ]
  },
  "credits": 0
}

{
  "success": true,
  "data": {
    "id": "4f1c9b2a-6d3e-4a17-9c88-0b5e2f7a1d34",
    "status": "cancelled",
    "completed": 12,
    "failed": 1,
    "limit": 200,
    "creditsUsed": 12,
    "createdAt": "2026-07-20T09:14:11.002Z",
    "updatedAt": "2026-07-20T09:15:02.310Z",
    "error": null,
    "expiresAt": "2026-07-27T09:14:11.002Z"
  },
  "credits": 12
}

{
  "type": "page",
  "crawlId": "4f1c9b2a-6d3e-4a17-9c88-0b5e2f7a1d34",
  "at": "2026-07-20T09:14:22.481Z",
  "completed": 12,
  "failed": 1,
  "data": {
    "markdown": "# Quickstart\n\nInstall the SDK and make your first call.",
    "metadata": {
      "title": "Quickstart - Example Docs",
      "statusCode": 200,
      "sourceUrl": "https://docs.example.com/quickstart"
    },
    "cached": false
  },
  "metadata": { "runId": "nightly-42" }
}

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();

// The signature is computed over the RAW body, so parse it as text/buffer.
// A JSON round-trip re-serializes the bytes and the HMAC stops matching.
app.post("/hooks/wayfern", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  const timestamp = req.get("X-Wayfern-Timestamp") ?? "";
  const provided = req.get("X-Wayfern-Signature") ?? "";

  const digest = createHmac("sha256", process.env.WAYFERN_WEBHOOK_SECRET)
    .update(`${timestamp}.${body}`)
    .digest("hex");
  const expected = Buffer.from(`sha256=${digest}`);
  const actual = Buffer.from(provided);

  // timingSafeEqual throws on a length mismatch, which is itself a mismatch.
  const ok = expected.length === actual.length && timingSafeEqual(expected, actual);
  if (!ok) return res.status(401).end();

  const event = JSON.parse(body);
  console.log(event.type, event.crawlId, event.completed);
  res.status(200).end();
});

curl -X POST https://api.wayfern.com/api/v1/map \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.example.com",
    "search": "pricing",
    "limit": 100,
    "includeSubdomains": false
  }'

{
  "success": true,
  "data": {
    "links": [
      {
        "url": "https://docs.example.com/quickstart",
        "title": "Quickstart",
        "description": "Install the SDK and make your first call.",
        "source": "sitemap",
        "lastModified": "2026-07-02T00:00:00.000Z"
      },
      {
        "url": "https://docs.example.com/pricing",
        "title": "Pricing",
        "description": null,
        "source": "links",
        "lastModified": null
      }
    ]
  },
  "credits": 2
}

curl -X POST https://api.wayfern.com/api/v1/extract \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/docs/*"],
    "prompt": "every pricing tier with its monthly cost and included seats",
    "schema": {
      "type": "object",
      "properties": {
        "tiers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "monthlyUsd": { "type": "number" },
              "seats": { "type": "integer" }
            },
            "required": ["name", "monthlyUsd"]
          }
        }
      },
      "required": ["tiers"]
    },
    "maxPages": 10
  }'

{
  "success": true,
  "data": {
    "data": {
      "tiers": [
        { "name": "Starter", "monthlyUsd": 0, "seats": 1 },
        { "name": "Growth", "monthlyUsd": 49, "seats": 5 }
      ]
    },
    "sources": [
      { "url": "https://example.com/pricing", "status": "fetched", "billed": true },
      { "url": "https://example.com/docs/limits", "status": "cached", "billed": false },
      {
        "url": "https://example.com/docs/legacy",
        "status": "failed",
        "billed": false,
        "error": "not_found"
      }
    ]
  },
  "credits": 1
}

curl -X POST https://api.wayfern.com/api/v1/screenshot \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://stripe.com",
    "width": 1440,
    "height": 900,
    "capture": {
      "fullPage": true,
      "format": "jpeg",
      "quality": 90,
      "blockCookieBanners": true,
      "darkMode": false
    }
  }'

{
  "success": true,
  "data": {
    "screenshot": {
      "url": "https://artifacts.wayfern.com/screenshots/9c1f4d02-7ab8-4e51-9d3f-2c60ba17e8c4.jpg",
      "key": "screenshots/9c1f4d02-7ab8-4e51-9d3f-2c60ba17e8c4.jpg",
      "contentType": "image/jpeg",
      "bytes": 418223,
      "expiresAt": "2026-07-27T09:14:11.002Z"
    },
    "metadata": {
      "title": "Stripe | Financial Infrastructure to Grow Your Revenue",
      "statusCode": 200,
      "sourceUrl": "https://stripe.com"
    }
  },
  "credits": 5
}

curl -X POST https://api.wayfern.com/api/v1/brand \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://stripe.com", "proxy": "auto" }'

{
  "success": true,
  "data": {
    "domain": "stripe.com",
    "url": "https://stripe.com",
    "name": "Stripe",
    "legalName": "Stripe, Inc.",
    "description": "Financial infrastructure to grow your revenue.",
    "slogan": "Payments infrastructure for the internet",
    "industry": "Financial services",
    "founded": "2010",
    "email": "support@example.com",
    "phone": null,
    "address": "354 Oyster Point Blvd, South San Francisco, CA",
    "colors": {
      "primary": "#635bff",
      "palette": [
        { "hex": "#635bff", "source": "theme-color", "weight": 0 },
        { "hex": "#0a2540", "source": "computed", "weight": 214 }
      ]
    },
    "logos": [
      {
        "url": "https://stripe.com/img/v3/home/social.png",
        "type": "og-image",
        "format": "png",
        "width": 1200,
        "height": 630,
        "variant": null
      }
    ],
    "links": {
      "social": {
        "twitter": "https://twitter.com/stripe",
        "linkedin": "https://www.linkedin.com/company/stripe"
      },
      "site": {
        "pricing": "https://stripe.com/pricing",
        "docs": "https://docs.stripe.com"
      }
    },
    "metadata": {
      "title": "Stripe | Financial Infrastructure to Grow Your Revenue",
      "statusCode": 200,
      "sourceUrl": "https://stripe.com"
    }
  },
  "credits": 10
}

curl -X POST https://api.wayfern.com/api/v1/styleguide \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://stripe.com", "waitFor": 1500 }'

{
  "success": true,
  "data": {
    "url": "https://stripe.com",
    "colors": {
      "palette": [{ "hex": "#635bff", "source": "css-variable", "weight": 0 }],
      "text": ["rgb(10, 37, 64)", "rgb(66, 84, 102)"],
      "background": ["rgb(255, 255, 255)", "rgb(247, 250, 252)"],
      "accent": ["rgb(99, 91, 255)"]
    },
    "typography": {
      "families": [
        {
          "family": "sohne-var",
          "stack": "sohne-var, \"Helvetica Neue\", Arial, sans-serif",
          "count": 412,
          "role": "body"
        }
      ],
      "scale": [
        { "size": "16px", "count": 268, "lineHeight": "28px", "weight": "425" },
        { "size": "48px", "count": 3, "lineHeight": "56px", "weight": "700" }
      ],
      "weights": ["425", "500", "700"],
      "lineHeights": ["20px", "28px", "56px"],
      "letterSpacings": ["normal", "-0.2px"]
    },
    "radii": ["4px", "8px", "16px"],
    "shadows": ["rgba(50, 50, 93, 0.1) 0px 2px 5px 0px"],
    "spacing": ["4px", "8px", "12px", "16px", "24px"],
    "breakpoints": ["600px", "880px", "1080px"],
    "cssVariables": { "--brand": "#635bff", "--radius-md": "8px" },
    "sources": [
      { "url": "https://stripe.com/assets/site.css", "bytes": 184220, "inline": false }
    ]
  },
  "credits": 10
}

curl -X POST https://api.wayfern.com/api/v1/fonts \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://stripe.com" }'

{
  "success": true,
  "data": {
    "url": "https://stripe.com",
    "fonts": [
      {
        "family": "sohne-var",
        "source": "self-hosted",
        "host": "stripe.com",
        "weights": ["400", "500", "700"],
        "styles": ["normal"],
        "formats": ["woff2"],
        "files": [
          {
            "url": "https://stripe.com/fonts/sohne-var.woff2",
            "format": "woff2",
            "bytes": 41284
          }
        ],
        "display": "swap",
        "unicodeRanges": ["U+0000-00FF"],
        "usage": {
          "elementCount": 412,
          "sampleSelector": "main p",
          "heading": true,
          "body": true
        }
      }
    ],
    "totalBytes": 41284
  },
  "credits": 5
}

curl -X POST https://api.wayfern.com/api/captcha/solve \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "type": "RecaptchaV2TaskProxyless",
      "websiteURL": "https://example.com",
      "websiteKey": "6Lc..."
    }
  }'

{
  "solution": {
    "gRecaptchaResponse": "03AGdBq25..."
  }
}