PHP SDK

composer require vermin/vermin-php guzzlehttp/guzzle

use Vermin\Vermin;
use Vermin\Enum\Format;

$vermin = new Vermin(); // reads VERMIN_API_KEY (and optionally VERMIN_API_URL)

$page = $vermin->scrape('https://example.com', ['formats' => [Format::Markdown, Format::Metadata]]);
echo $page->data->markdown, $page->data->metadata?->title, "\n";
echo "cost: {$page->creditsUsed} credits (request {$page->requestId})\n";

$vermin = new Vermin(
    apiKey: 'vmn_live_…',                // default: VERMIN_API_KEY
    baseUrl: 'https://api.vermin.dev',   // default: VERMIN_API_URL, then https://api.vermin.dev
    timeout: 60.0,                       // per-attempt HTTP timeout, seconds
    maxRetries: 2,                       // retries on 429 / 5xx / network errors
    headers: ['X-Team' => 'growth'],     // extra headers on every request
    httpClient: $psr18Client,            // bring your own PSR-18 client
    requestFactory: $psr17Factory,       // optional PSR-17 factories (discovered by default)
    streamFactory: $psr17Factory,
);

use Vermin\RequestOptions;

$vermin->scrape('https://example.com', options: new RequestOptions(
    timeout: 120.0,
    maxRetries: 0,
    idempotencyKey: 'order-42-scrape',
    headers: ['X-Trace' => 'abc'],
));

use Vermin\Enum\{ActionType, Format, QualityIssue, Tier};

$res = $vermin->scrape('https://news.ycombinator.com', [
    'formats' => [Format::Markdown, Format::Links, Format::Chunks],
    'onlyMainContent' => true,
    'tier' => Tier::Auto,             // fetch → render → premium (if allowPremium)
    'chunkSize' => 1200,
    'actions' => [
        ['type' => ActionType::Click, 'selector' => '#more'],
        ['type' => ActionType::Wait, 'ms' => 1000],
    ],
]);
foreach ($res->data->chunks ?? [] as $chunk) {
    echo implode(' › ', $chunk->headingPath ?? []), " ({$chunk->tokens} tokens)\n";
}
$res->data->quality?->hasIssue(QualityIssue::JsRequired);

use Vermin\Enum\CrawlEventType;

$job = $vermin->crawl('https://docs.example.com', [
    'limit' => 200,
    'maxDepth' => 3,
    'scrapeOptions' => ['formats' => ['markdown']],
    'webhook' => ['url' => 'https://you.dev/hooks/vermin', 'events' => ['page', 'completed']],
]);

// Poll until finished and collect every page (follows `next` cursors):
$result = $vermin->waitForCrawl($job->id, pollInterval: 2.0, timeout: 600,
    onStatus: fn ($s) => print("{$s->completed} / {$s->total}\n"));
echo $result->status->value, ' ', count($result->data), ' ', $result->creditsUsed, "\n";

// …or stream pages as they arrive (server-sent events):
foreach ($vermin->streamCrawl($job->id) as $event) {
    match ($event->type) {
        CrawlEventType::Page => print($event->document()->url . "\n"),
        CrawlEventType::Done => print('finished: ' . $event->status()->status->value . "\n"),
        default => null,
    };
}

// Lower level:
$status = $vermin->getCrawl($job->id, limit: 50);
$page2 = $status->next ? $vermin->getCrawl($job->id, cursor: $status->next) : null;
foreach ($vermin->crawlDocuments($job->id) as $doc) {  // every document, across pages
    echo $doc->url, "\n";
}
foreach ($vermin->crawlPages($job->id) as $page) {     // one CrawlStatus per page
    echo count($page->data), "\n";
}
$vermin->cancelCrawl($job->id);

$res = $vermin->map('https://example.com', ['search' => 'pricing', 'limit' => 500]);
$urls = $res->urls(); // or array_map(fn ($l) => $l->url, $res->links)

// Only some paths (globs)
$vermin->map('https://example.com', ['includePaths' => ['/blog/*'], 'excludePaths' => ['/blog/tag/*']]);

use Vermin\Enum\TimeRange;

$res = $vermin->search('best vector databases 2026', [
    'limit' => 5,
    'timeRange' => TimeRange::Month,
    'scrapeOptions' => ['formats' => ['markdown']], // optional: scrape each result
]);
foreach ($res->results as $hit) {
    echo $hit->position, ' ', $hit->title, ' ', strlen($hit->document?->markdown ?? ''), "\n";
    // $hit->date and $hit->source are set when the provider reports them (e.g. news results)
}

$res = $vermin->extract('https://shop.example.com/p/123', schema: [
    'type' => 'object',
    'properties' => [
        'name' => ['type' => 'string'],
        'price' => ['type' => 'number'],
        'in_stock' => ['type' => 'boolean'],
    ],
    'required' => ['name', 'price'],
], prompt: 'Extract the product');

$res->data['price'];
foreach ($res->sources ?? [] as $source) {
    echo $source->url, "\n";
}

use Vermin\Enum\{ColorRole, ImageBackground, ImageType};

$res = $vermin->brand('stripe.com');
$brand = $res->data;
$brand->logo?->url;          // Vermin-hosted copy; ->sourceUrl is where it was found
$brand->color(ColorRole::Primary)?->hex;
$brand->color(ColorRole::Primary)?->contrast; // WCAG ratio of ->textColor on it

// Every image found, tagged with its type and the background it suits
$forDarkUi = array_filter($brand->logos ?? [], fn ($l) => $l->background === ImageBackground::Dark && $l->type !== ImageType::Icon);

$res->cached; // served from cache
$res->stale;  // cached result older than maxAge, served because a fresh lookup failed

$vermin->brand('stripe.com', maxAge: 0); // force a fresh extraction

use Vermin\Exception\{InsufficientCreditsException, RateLimitException, VerminException};

try {
    $vermin->scrape('https://example.com');
} catch (RateLimitException $e) {
    sleep((int) ceil($e->retryAfter() ?? 1));
} catch (InsufficientCreditsException $e) {
    // top up at https://vermin.dev/dashboard/billing
} catch (VerminException $e) {
    $e->errorCode;     // ErrorCode::BlockedBySite, … (or the raw string for new codes)
    $e->status;        // HTTP status (0 if no response)
    $e->requestId;     // quote this to support
    $e->retryAfterMs;  // server hint, when present
    $e->creditsUsed;   // credits charged, when the API reports it
    $e->isRetryable(); // whether retrying could help
}

use Vermin\Webhook;
use Vermin\Exception\WebhookSignatureException;

$payload = file_get_contents('php://input');
$header = $_SERVER['HTTP_VERMIN_SIGNATURE'] ?? '';

try {
    $event = Webhook::verify($payload, $header, getenv('VERMIN_WEBHOOK_SECRET'), tolerance: 300);
} catch (WebhookSignatureException $e) {
    http_response_code(400);
    exit;
}

// $event is the decoded JSON payload (array<string, mixed>)