Trigger a Visibility Scan Preview

POST /api/visibility/scan-preview

Authentication: Required. An account in read-only mode gets a 403 with code: "READ_ONLY" — triggering a preview scan is a write + spend, so it's refused before the scan is enqueued.

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 — including the brand-tuned narrative copy (per-slide headlines and subtitles) that the report UI renders — 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"
}

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. The scores themselves arrive later, on GET /api/visibility/scan-preview: an overall visibility score plus two direct-brand readings — knowledgeScore (how much AI knows about the brand) and sentimentScore (how favourably it talks about it). See the score explained for how to read all three.
3. Once the scan completes, the reportUrl renders the finished white-label report directly — embed it in outreach drafts immediately and it resolves by the time the recipient clicks.
4. For local-business scans (a Yelp or Google Business Profile seed), the completed scan also builds a ready-to-launch site. Poll GET /api/visibility/scan-preview and read agentSiteUrl — share the prospect's site instead of (or alongside) the report. It's null for non-local-business scans and absent until the scan completes.
5. The report itself adapts to local businesses whichever URL you send. The scan judges from the business model (does a customer have to be nearby to buy?) rather than from the seed URL alone, so a plumber or clinic scanned by its own website gets the local framing, not just one scanned from a directory listing.

This endpoint is partner-only (callers without a partner team get PARTNER_SCREENNAME_REQUIRED), and partner scans are always private — isPublic is forced to false. Passing isPublic: true does not fail; the field is ignored, coerced to false, and the response carries a non-fatal warning (plus Deprecation, Warning, and X-Pendium-Warning headers, all plain ASCII) so existing integrations keep working. So reportUrl is always white-labeled: the team's verified custom domain (https://reports.youragency.com/visibility-scan-preview/<uuid>) when one is set, otherwise https://pendium.ai/partner/<slug>/visibility-scan-preview/<uuid> under the agency's branding.

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": false,
  "reportUrl": "https://pendium.ai/partner/youragency/visibility-scan-preview/775ba0fc-c67a-4ff2-aa0a-e1c15a638d4a",
  "previewUrl": "https://pendium.ai/partner/youragency/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.