Trigger a Visibility Scan Preview

POST /api/visibility/scan-preview

Authentication: Required

Trigger a lightweight Visibility Scan Preview — the single-shot megaprompt scan that powers the public /visibility-scan-preview/{slug} brand-page report. Designed for outbound prospecting: the GTM partner companion to Generate a Cold-Email Pitch, used to produce a polished, shareable report you can put in front of a prospect in 30–90 seconds.

This is not the right endpoint for paying customers' ongoing visibility monitoring. The Scan Preview runs once, returns a single megaprompt-derived snapshot, and lives at a public URL — purpose-built for outreach. Pendium customers measuring their own brand over time use Trigger a Scan + Get a Report (managed agents, scheduled scans, full raw LLM responses, score history).

Typical use cases for the Scan Preview:

• Cold-email outreach. Embed the returned reportUrl in an email — by the time the recipient clicks, the URL resolves to a polished /visibility-scan-preview/{brand-slug} page.
• Lead generation. Run a report on each new lead so the GTM team has scores + analysis ready in seconds.
• Agency / consultant prospecting. GTM partners and agencies running outbound on their own Pendium account use this endpoint to qualify and warm up a pipeline before the conversation starts.
• In-app lead magnets. Power "scan your brand" flows that don't need to create a managed agent.

Reports complete in 30–90 seconds. Poll Get a Visibility Scan Preview for results.

Request body

{
  "url": "https://acme.com",
  "isPublic": true
}

How it works

1. The endpoint enqueues a single-shot megaprompt LLM call against ChatGPT, Claude, Gemini, and AI Overviews to estimate visibility.
2. It returns immediately with a uuid and reportUrl pointing at the per-UUID preview URL.
3. Once the scan completes (and isPublic=true), that preview URL automatically 308-redirects to the canonical brand-slug URL — so you can embed the preview URL in outreach drafts immediately and it'll resolve to the slug page by the time the recipient clicks.

Free-plan users are blocked at this endpoint with a PLAN_UPGRADE_REQUIRED error. No credits are deducted — Visibility Scan Previews are inexpensive.

Example

curl -X POST https://pendium.ai/api/visibility/scan-preview \
  -H "Content-Type: application/json" \
  -H "x-api-key: pendium_xxxxxxxxxxxx" \
  -d '{"url": "https://acme.com"}'

Response

{
  "success": true,
  "uuid": "775ba0fc-c67a-4ff2-aa0a-e1c15a638d4a",
  "status": "pending",
  "isPublic": true,
  "reportUrl": "https://pendium.ai/visibility-scan-preview/775ba0fc-c67a-4ff2-aa0a-e1c15a638d4a",
  "previewUrl": "https://pendium.ai/visibility-scan-preview/775ba0fc-c67a-4ff2-aa0a-e1c15a638d4a",
  "message": "Visibility Scan Preview triggered. Poll GET /api/visibility/scan-preview?uuid=… every 5-15 seconds until status='complete'."
}

If you're on the free plan:

{
  "error": "API-triggered Visibility Scan Previews require a Starter or Pro plan",
  "code": "PLAN_UPGRADE_REQUIRED",
  "currentPlan": "free",
  "upgradeUrl": "https://pendium.ai/pricing"
}

Outreach link shortcut

For email/SMS outreach where you don't want to pre-pay for compute on people who never click, you can skip this endpoint entirely and link recipients to:

https://pendium.ai/?report=https://acme.com

The homepage reads the ?report= param and triggers the Visibility Scan Preview on click — anonymous recipients sign in via Privy first, then land at the live in-progress report. Already-authenticated recipients are routed straight through.