Scan automation, API keys, CLI and deploy hooks

PageLens AI includes developer automation so scans can run from your release workflow. This is useful when you want to check a site after a deploy, run launch QA from CI, or let an agency workflow queue scans without manually opening the dashboard.

Developer automation is available on Pro and Agency plans.

What this API is for

The PageLens AI API is a scan automation API. It is designed to trigger and inspect scan runs from trusted workflows.

It is not a broad public data API like a search index, analytics warehouse, or SEO rank-tracking API. The current automation surface is intentionally focused:

• create scan runs from scripts and CI
• inspect scan status and report URLs after a run
• trigger scans after deploys
• connect the CLI or GitHub Action
• manage API keys and deploy hooks from your account
• use plan quotas and rate limits to prevent accidental overuse

Current REST endpoints:

• POST /api/v1/scans queues a plan-covered scan from a trusted workflow
• GET /api/v1/scans/{id} reads scan status, score, owner launch verdict, report URL and regression context
• GET /api/v1/scans/{id}/markdown downloads the agent-ready Markdown repair pack

API keys

API keys let trusted scripts create scans without using your browser session. Create and revoke them from Settings -> Integrations -> Developer access.

Treat API keys like passwords:

• do not paste them into client-side JavaScript
• do not commit them to GitHub
• store them in your CI secret manager
• create separate keys for different workflows where possible
• revoke a key immediately if you think it has leaked

When a key is created, PageLens AI shows the token once. After that, only a prefix and usage metadata are stored for management.

CLI scans

Use the CLI when you want a simple command in a release script or local QA checklist.

npx @pagelensai/cli scan https://example.com

The CLI should use an API key from your environment or CI secrets. It is best for repeatable checks such as:

• scan the production homepage after deploy
• scan a staging URL before launch
• scan a client landing page before handoff
• run PageLens AI as part of a release checklist

For AI-built sites, add launch context so the report stays evidence-led but the fix prompts speak to the workflow you are using:

npx @pagelensai/cli scan https://example.com \
  --wait \
  --depth DEEP_AUDIT \
  --builder codex \
  --moment public_post \
  --markdown pagelens-report.md

--builder can be lovable, bolt, replit, v0, cursor, codex, claude_code, copilot, windsurf, shopify, or other.

--moment can be public_post, customer_data, paid_traffic, or first_users.

These fields do not change the score, crawl coverage or severity. They only frame summaries and fix prompts around the owner's launch moment, so the same report works for a nontechnical owner and for the coding agent or developer applying the fixes.

When --markdown is set, the CLI saves the same repair pack available from the report export menu. Paste that Markdown into Codex, Cursor, Claude Code, GitHub Copilot, Windsurf, Lovable, Bolt, Replit, v0, or your developer workflow.

API launch context

The same context can be sent directly to POST /api/v1/scans:

{
  "url": "https://example.com",
  "analysisDepth": "DEEP_AUDIT",
  "builderPlatform": "codex",
  "launchMoment": "public_post"
}

Use this from CI, release scripts, internal tools and agency dashboards when you want the report to answer a concrete launch question such as "before Reddit sees it", "before customers enter data", "before paid traffic" or "before first users".

GitHub Action

The GitHub Action is for repository workflows. Use it when you want PageLens AI to run around pull requests, deployment previews, release branches, or scheduled QA jobs.

Store the PageLens AI API key as a GitHub secret. Do not hardcode it in the workflow file.

Pin the action to a release tag, such as @v1, for production workflows. Avoid relying on a moving branch in client or agency delivery pipelines.

Good uses include:

• scan a preview URL after deployment
• scan production after a release
• post scan context back into the team's review process
• make launch QA part of the normal engineering workflow

For AI-builder workflows, pass builder-platform, launch-moment and markdown-path to save a repair pack as a workflow artifact or feed it into a later AI-review step.

Deploy hooks

Deploy hooks are URL-based triggers for a specific target URL. They are useful when a hosting provider or deployment system can call a webhook after a successful deployment.

Create deploy hooks from Settings -> Integrations -> Developer access. The hook URL is shown once, so store it securely in your deployment provider.

Deploy hooks are best for:

• Vercel post-deploy checks
• scheduled platform jobs
• agency client launch workflows
• low-friction “scan after publish” automation

Deploy hooks can also store builder and launch context when you create them from Developer access. That lets a post-deploy scan keep the same framing as your launch workflow without every webhook caller needing to send custom JSON.

Quotas and plans

Automated scans use the same plan limits as scans started from the app.

| Plan | Developer automation | Monthly scans | Monthly Deep AI Audits | | --- | --- | --- | --- | | Free | Not included | 3 | 1 | | Pro | Included | 1,500 | 50 | | Agency | Included | 10,000 | 250 |

Use automation thoughtfully. A deploy hook that fires on every small preview build can use allowance quickly. For production release checks, post-deploy scans, and important staging environments, automation is usually the right fit.

Safe usage

Before adding automation, decide:

• which URL should be scanned
• whether the workflow should scan production or staging
• how often the workflow can run
• who can access the API key or hook URL
• where scan results should be reviewed

If a workflow starts creating too many scans, revoke the key or deploy hook from Settings -> Integrations and create a more specific one.

API keys vs MCP

API keys and deploy hooks are for automation that triggers scans.

MCP connections are for AI assistants that inspect completed reports, summarize findings, submit feedback, or record accepted decisions with the scopes you approve. A common repair loop is:

1. CLI, API, GitHub Action or deploy hook creates the scan.
2. PageLens returns the report URL and Markdown URL.
3. Your assistant reads the report through MCP or from the Markdown file.
4. You fix the top findings in your builder or codebase.
5. You re-scan to prove the live site improved.

See MCP, agent feedback, and accepted decisions for that workflow.

Where to configure it

Go to Settings -> Integrations -> Developer access to create API keys, create deploy hooks, review existing credentials, and revoke anything you no longer use.

If you are on Free or Builder, upgrade to Pro or higher from Settings -> Billing to unlock developer automation.