Documentation

Foglift Documentation

Everything you need to integrate Foglift — whether you're a developer building a pipeline, an AI agent scanning autonomously, or a team adding SEO checks to CI/CD.

Quick Start

Three ways to use Foglift — pick the one that fits your workflow.

For Humans (CLI)

npx foglift-scan mysite.com

Colored output in terminal

For Code (API)

GET /api/v1/scan?url=...

Structured JSON response

For AI Agents (MCP)

npx foglift-mcp

Claude Code, Cursor, Windsurf

CLI Tool

Scan any website from your terminal. No signup, no API key required for basic scans.

Basic Usage

Terminal

# Scan a website (colored output with scores and issues)
npx foglift-scan https://example.com

# Output as JSON (for scripting)
npx foglift-scan https://example.com --json

# Verbose mode (show all issues, not just top 5)
npx foglift-scan https://example.com --verbose

# Fail CI if score below threshold
npx foglift-scan https://example.com --threshold 80

Example Output

Terminal

$ npx foglift-scan https://example.com

  Foglift — Website Intelligence Scanner

  URL: https://example.com
  Scanned: 2026-03-15 14:30:00 (12 seconds)

  ┌──────────────────────────────────────────────┐
  │  Overall: B (74/100)                         │
  ├──────────────────────────────────────────────┤
  │  SEO:           █████████░  85/100  A        │
  │  GEO:           █████░░░░░  52/100  D        │
  │  Performance:   ████████░░  78/100  C        │
  │  Security:      ██████░░░░  60/100  C        │
  │  Accessibility: █████████░  91/100  A        │
  └──────────────────────────────────────────────┘

  Issues Found: 8 (2 critical, 3 warnings, 3 info)

  🔴 [GEO] AI crawlers blocked by robots.txt
  🔴 [GEO] Missing FAQ schema markup
  🟡 [Security] No Content-Security-Policy header
  🟡 [SEO] Missing Open Graph image tag
  🟡 [Security] No Permissions-Policy header

  Full report → https://foglift.io/scan/abc123

CLI Flags

Flag	Description
--json	Output raw JSON (for piping to jq, scripts, etc.)
--verbose	Show all issues (not just top 5)
--no-color	Disable colored output
--threshold=N	Exit with code 1 if overall score is below N (CI/CD use)

Exit Codes

Code	Meaning
0	Scan completed successfully (or score above threshold)
1	Score below --threshold, or scan error
2	Invalid URL or network error

Advanced Commands (API key required)

Set FOGLIFT_API_KEY to unlock AI visibility monitoring, prompt management, and analytics.

Command	Description
foglift scan batch <urls...>	Batch scan up to 10 URLs at once
foglift scan ai-check	Run AI visibility check across models
foglift scan results	Get historical AI visibility results
foglift scan prompts list	List saved monitoring prompts
foglift scan prompts add "text"	Add a new monitoring prompt
foglift scan prompts remove <id>	Delete a monitoring prompt
foglift scan models	Show enabled AI models and frequency
foglift scan sentiment	Get sentiment analysis trends
foglift scan usage	Show API usage and token balance
foglift scan history <url>	View scan history for a URL

Terminal

# Run AI visibility check with specific prompts and models
export FOGLIFT_API_KEY=sk_fog_your_key_here
foglift scan ai-check --prompt "best seo tools" --models chatgpt,perplexity

# View results from the last 7 days
foglift scan results --days 7 --model chatgpt --json

# Manage monitoring prompts
foglift scan prompts list
foglift scan prompts add "best alternatives to semrush"

# Check token usage
foglift scan usage

REST API

The Foglift REST API provides programmatic access to website intelligence. Free, no auth required for basic scans.

Base URL

https://foglift.io/api/v1

GET /api/v1/scan

Scan a website and return SEO + GEO analysis results.

Parameter	Type	Required	Description
url	string	Yes	Full URL to scan (include https://)
format	string	No	"json" (default) or "text"

Examples

cURL

curl "https://foglift.io/api/v1/scan?url=https://example.com"

JavaScript

const response = await fetch(
  "https://foglift.io/api/v1/scan?url=https://example.com"
);
const data = await response.json();

console.log(data.scores);
// { overall: 72, seo: 85, geo: 65, performance: 78, security: 60, accessibility: 70 }

console.log(data.issues);
// [{ category: "GEO", severity: "critical", title: "AI crawlers blocked", description: "..." }]

console.log(data.aiSummary);
// "This site has strong SEO fundamentals but needs GEO optimization..."

Python

import requests

response = requests.get(
    "https://foglift.io/api/v1/scan",
    params={"url": "https://example.com"}
)
data = response.json()

print(f"Overall: {data['scores']['overall']}/100")
for issue in data["issues"]:
    print(f"  [{issue['severity']}] {issue['title']}")

Response Schema

JSON Response

{
  "url": "https://example.com",
  "scanId": "scan_abc123",
  "scannedAt": "2026-03-15T12:00:00Z",
  "scores": {
    "overall": 72,          // Weighted average (0-100)
    "seo": 85,              // Traditional SEO health (0-100)
    "geo": 65,              // AI search readiness (0-100)
    "performance": 78,      // Page speed & Core Web Vitals (0-100)
    "security": 60,         // HTTP security headers (0-100)
    "accessibility": 70     // WCAG compliance (0-100)
  },
  "letterGrade": "B",       // A (90+), B (80+), C (60+), D (40+), F (<40)
  "issues": [
    {
      "category": "GEO",         // "GEO" | "AEO" | "SEO" | "Performance" | "Security" | "Accessibility"
      "severity": "critical",    // "critical" | "warning" | "info"
      "title": "AI crawlers blocked by robots.txt",
      "description": "GPTBot and ClaudeBot are blocked. Add User-agent: GPTBot\nAllow: / to robots.txt"
    }
  ],
  "aiSummary": "This site has strong SEO fundamentals but lacks GEO optimization...",
  "totalIssues": 12,          // Total issue count (some may be hidden on free tier)
  "tier": "free",             // "free" | "launch" | "growth" | "enterprise"
  "gated": true               // true = some issues hidden (free tier)
}

Issue Severity Levels

Severity	Impact	Action
critical	Directly hurts rankings or blocks AI indexing	Fix immediately
warning	Suboptimal, reduces visibility over time	Fix within a week
info	Best practice recommendation	Consider implementing

Score Methodology

Each category score is calculated from multiple weighted checks. The overall score is a weighted average:

overall = (seo × 0.25) + (geo × 0.25) + (performance × 0.20) + (security × 0.15) + (accessibility × 0.15)

SEO Score (25% of overall)

Traditional search engine optimization health. Based on Google Lighthouse SEO audit + custom checks.

Title tag — present, 30-60 chars, unique, contains target keywords
Meta description — present, 120-160 chars, compelling copy
Heading hierarchy — single H1, logical H2-H6 nesting
Open Graph tags — og:title, og:description, og:image for social sharing
Twitter Card — twitter:card, twitter:title, twitter:image
Canonical URL — present and self-referencing
Image alt text — all images have descriptive alt attributes
Language attribute — html lang="en" set for screen readers
Robots directives — no accidental noindex/nofollow
Sitemap.xml — discoverable at /sitemap.xml
Robots.txt — present and not blocking important pages

AI Readiness Score (25% of overall)

AI search readiness — how well structured your content is for ChatGPT, Perplexity, Google AI Overviews, and Claude.

AI crawler access — GPTBot, ClaudeBot, PerplexityBot, Google-Extended not blocked in robots.txt
Structured data depth — JSON-LD schemas: Organization, FAQPage, Article, Product, HowTo, LocalBusiness
FAQ sections — Q&A content that AI can extract and cite as answers
Entity markup — clear entity definitions (brand, people, products) via schema.org
Content structure — clear headings, short paragraphs, bullet lists, tables
Citation formatting — statistics with sources, expert quotes, attributed data points
Meta quality — comprehensive, accurate metadata that helps AI understand page purpose

Performance Score (20% of overall)

Page speed via Google PageSpeed Insights (Lighthouse). Directly from Google's scoring.

LCP — Largest Contentful Paint (should be < 2.5s)
CLS — Cumulative Layout Shift (should be < 0.1)
INP — Interaction to Next Paint (should be < 200ms)
FCP — First Contentful Paint
Speed Index — visual progress of page load
Total Blocking Time — main thread responsiveness

Security Score (15% of overall)

HTTP security headers. Each missing header deducts points.

HTTPS — valid SSL certificate, no mixed content
Strict-Transport-Security — HSTS header with max-age
Content-Security-Policy — CSP header present
X-Frame-Options — clickjacking protection
X-Content-Type-Options — MIME sniffing prevention (nosniff)
Referrer-Policy — controls information leakage
Permissions-Policy — restricts browser features

Accessibility Score (15% of overall)

WCAG 2.1 compliance via Google Lighthouse accessibility audit.

Color contrast — text meets WCAG AA ratio (4.5:1)
Alt text — all informational images have descriptive alt
Keyboard navigation — interactive elements reachable via Tab
ARIA labels — dynamic/custom elements properly labeled
Form labels — every input has an associated label
Document language — lang attribute set

Score Interpretation Guide

Use this guide to understand what each score range means and what actions to take. AI agents: use these thresholds to prioritize fixes.

90-100: Excellent

Top-tier optimization. Your site is well-positioned for both search and AI.

Action: Maintain current setup. Set up monitoring to catch regressions. Consider the Launch plan for weekly automated scans.

80-89: Good

Solid foundation with a few areas to improve.

Action: Fix remaining critical and warning issues. Usually 2-5 specific items will push you to an A. Check the action recipes below.

60-79: Needs Work

Significant gaps. You're likely losing traffic and AI visibility.

Action: Prioritize critical issues first — they have the biggest impact. Focus on GEO and SEO categories. The free scan gives you the full issue list and AI action plan.

40-59: Poor

Major issues across multiple categories. AI models likely cannot cite your content.

Action: Start with the basics: ensure HTTPS, add meta tags, allow AI crawlers, add structured data. Each fix will have a significant impact at this level.

0-39: Critical

Fundamental issues. The site may be essentially invisible to AI search.

Action: This usually means the site is blocking crawlers, has no meta tags, or has major technical issues. Follow the action recipes in order — start with robots.txt and meta tags.

Action Recipes

For every issue Foglift can detect, here's the exact fix. AI agents: use these as copy-paste solutions when fixing issues programmatically.

GEO Issues

AI crawlers blocked by robots.txt

GPTBot, ClaudeBot, or PerplexityBot is blocked. This means AI models cannot read your content.

Fix: Add these lines to your robots.txt:

robots.txt

User-agent: GPTBot
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: Google-Extended
Allow: /

Verify: Rescan the site. GEO score should increase by 10-20 points.

Missing structured data / JSON-LD

No JSON-LD schemas detected. AI models use structured data to understand your content type and key facts.

Fix: Add JSON-LD to your page's <head>:

HTML

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company",
  "url": "https://yoursite.com",
  "description": "What your company does in one sentence.",
  "logo": "https://yoursite.com/logo.png",
  "sameAs": [
    "https://twitter.com/yourcompany",
    "https://linkedin.com/company/yourcompany"
  ]
}
</script>

Missing FAQ schema

No FAQPage schema detected. FAQ schemas are one of the highest-impact GEO optimizations — they give AI direct Q&A content to cite.

Fix:

HTML

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What does your product do?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Our product does X, Y, and Z for [target audience]."
      }
    },
    {
      "@type": "Question",
      "name": "How much does it cost?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Free to start. Paid plans from $X/month."
      }
    }
  ]
}
</script>

SEO Issues

Missing or poor meta description

No meta description, or it's too short/long. This is the snippet shown in Google search results.

Fix: Add to <head>:

HTML

<meta name="description" content="120-160 characters describing what this page offers. Include your primary keyword naturally. Make it compelling — this is your ad copy in search results.">

Missing Open Graph tags

No og:title, og:description, or og:image. Links shared on social media will look blank.

Fix:

HTML

<meta property="og:title" content="Page Title — Brand Name">
<meta property="og:description" content="Compelling description for social sharing.">
<meta property="og:image" content="https://yoursite.com/og-image.png">
<meta property="og:url" content="https://yoursite.com/this-page">
<meta property="og:type" content="website">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Page Title — Brand Name">
<meta name="twitter:description" content="Compelling description for Twitter.">
<meta name="twitter:image" content="https://yoursite.com/og-image.png">

Security Issues

Missing security headers

Missing HSTS, CSP, X-Frame-Options, or other security headers. Affects both security and SEO ranking.

Fix (Next.js next.config.js):

next.config.js

const securityHeaders = [
  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
  { key: 'X-Content-Type-Options', value: 'nosniff' },
  { key: 'X-Frame-Options', value: 'DENY' },
  { key: 'X-XSS-Protection', value: '1; mode=block' },
  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
];

module.exports = {
  async headers() {
    return [{ source: '/(.*)', headers: securityHeaders }];
  },
};

Fix (Vercel vercel.json):

vercel.json

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains; preload" },
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" },
        { "key": "Permissions-Policy", "value": "camera=(), microphone=(), geolocation=()" }
      ]
    }
  ]
}

MCP Server (AI Agents)

Foglift is available as an MCP (Model Context Protocol) server. AI coding assistants like Claude Code, Cursor, and Windsurf can scan websites and fix issues directly from your IDE.

Connecting from Claude.ai (web)

Use the dedicated mcp.foglift.io endpoint when adding Foglift as a custom connector at claude.ai/customize:

Click Add custom connector
URL: https://mcp.foglift.io/api/mcp
Open Advanced → add header Authorization with value Bearer sk_fog_… (paste a key from Settings)
Click Connect — the connector card goes green and tools become available in new conversations

Why a separate hostname? Claude.ai web has a known OAuth-proxy bug affecting custom MCP servers. The mcp.foglift.io endpoint avoids the bug by accepting an API key directly via the connector's header configuration. The original foglift.io/api/mcp endpoint continues to work for Claude Code CLI (OAuth) and any other MCP client.

Installation (Claude Code CLI / IDEs)

Terminal

npm install -g foglift-mcp

Claude Code Setup

Add to ~/.claude/mcp.json:

~/.claude/mcp.json

{
  "mcpServers": {
    "foglift": {
      "command": "npx",
      "args": ["foglift-mcp"]
    }
  }
}

Cursor Setup

Add to .cursor/mcp.json in your project root:

.cursor/mcp.json

{
  "mcpServers": {
    "foglift": {
      "command": "npx",
      "args": ["foglift-mcp"]
    }
  }
}

Windsurf Setup

Add to ~/.windsurf/mcp.json:

~/.windsurf/mcp.json

{
  "mcpServers": {
    "foglift": {
      "command": "npx",
      "args": ["foglift-mcp"]
    }
  }
}

Available MCP Tools

Tool	Description	Parameters
scan_website	Run full SEO + GEO analysis	`url` (required)
batch_scan	Scan multiple URLs at once	`urls` (required, array)
run_ai_visibility	Check AI visibility across engines	`url`, `prompts`
get_ai_results	Retrieve AI visibility results	`workspace_id`
get_prompts	List workspace GEO prompts	`workspace_id`
add_prompt	Add a prompt to monitor	`workspace_id`, `prompt`
delete_prompt	Remove a prompt	`workspace_id`, `prompt_id`
get_models	Get AI model preferences	`workspace_id`
set_models	Configure which AI models to track	`workspace_id`, `models`
get_sentiment	Get AI sentiment analysis	`workspace_id`
get_usage	Check API usage and limits	none
get_scan_history	View past scan results	`url` (optional)
get_geo_monitor	Get GEO monitoring status	`workspace_id`

Example MCP Tool Response

scan_website response

{
  "url": "https://example.com",
  "scores": { "overall": 72, "seo": 85, "geo": 52, "performance": 78, "security": 60, "accessibility": 91 },
  "issues": [
    { "category": "GEO", "severity": "critical", "title": "AI crawlers blocked by robots.txt", "description": "..." },
    { "category": "GEO", "severity": "critical", "title": "No FAQ schema markup", "description": "..." },
    { "category": "Security", "severity": "warning", "title": "Missing CSP header", "description": "..." }
  ],
  "aiSummary": "Strong SEO but weak GEO. AI crawlers are blocked and no structured data is present..."
}

Agent Workflows

Complete workflows for AI agents using Foglift. Copy these patterns to build autonomous SEO/GEO fix pipelines.

Workflow: Scan and Fix All Issues

The most common agent workflow — scan a site, then fix every issue found.

Scan the site — Call scan_website with the URL. Read the full response.
Prioritize by severity — Fix critical issues first, then warnings, then info.
For each issue, look up the action recipe — Match the issue title to the recipes in this docs page.
Apply the fix — Edit the relevant file (robots.txt, HTML head, config, etc.).
Rescan to verify — Run scan_website again. Score should improve.
Commit and deploy — Push changes and redeploy the site.

Workflow: CI/CD Quality Gate

Block deploys when SEO/GEO scores drop below a threshold.

After deploy to staging — Scan the staging URL.
Check overall score — If below threshold (e.g., 70), fail the build.
Check for new critical issues — Compare with previous scan. Any new critical = fail.
Report results — Post scores as a PR comment or CI artifact.

Workflow: New Site Setup

You just deployed a new Next.js/React site. Use Foglift to get it optimized from day one.

Scan the deployed URL — Get baseline scores.
Fix robots.txt — Allow all search engines and AI crawlers.
Add meta tags — title, description, OG tags, Twitter card to every page.
Add JSON-LD structured data — Organization + FAQPage at minimum.
Add security headers — HSTS, CSP, X-Frame-Options, etc.
Generate sitemap.xml — List all public pages.
Submit to Google Search Console — Verify domain, submit sitemap.
Rescan — Verify all scores are 80+.

Public API Reference

The full programmatic surface: scan websites, run AI visibility checks, manage monitoring prompts, pull sentiment and history, verify crawler-tracker installs. Everything the CLI can do, your code and AI agents can do too.

Authentication

Authenticated endpoints require an API key in the X-API-Key header (or Authorization: Bearer <key> for batch endpoints). Keys look like sk_fog_…. Generate and rotate keys at Settings → Developer. Keys are hashed with SHA-256 server-side and shown only once at creation.

One API key is scoped to one account; if you have multiple workspaces (brands) under that account, pass workspace_id where the endpoint supports it — otherwise Foglift auto-resolves to your single workspace.

Endpoint Index

Every API-key-authenticated v1 endpoint currently live in production. Tier column lists the minimum paid tier required; Public means no auth needed.

Method	Endpoint	Tier	Description
GET	/api/v1/scan	Public	Run a website audit. Free for 10 scans/day per IP; higher per-plan limits with an API key.
POST	/api/v1/scan/batch	Launch+	Scan up to 10 URLs in one request.
POST	/api/v1/scan/sitemap	Growth+	Fetch `sitemap.xml` and scan up to 25 of its URLs.
POST	/api/v1/ai-visibility	Launch+	Query ChatGPT, Perplexity, Claude, Gemini, and Google AI Overview for saved or custom prompts. Debits tokens per model.
GET	/api/v1/ai-visibility/results	Launch+	Historical AI visibility results with filters and pagination.
GET	/api/v1/prompts	Launch+	List tracked monitoring prompts for the workspace.
POST	/api/v1/prompts	Launch+	Add one or more monitoring prompts.
DELETE	/api/v1/prompts	Launch+	Remove a monitoring prompt by id.
GET	/api/v1/models	Launch+	Get enabled AI models and monitoring frequency.
POST	/api/v1/models	Launch+	Update enabled models and monitoring frequency.
GET	/api/v1/sentiment	Launch+	Net Sentiment Score, daily trend, and per-engine breakdown.
GET	/api/v1/history	Launch+	Paginated GEO monitoring result rows for a workspace.
GET	/api/v1/monitor	Launch+	Visibility scores, citations, and prompts over a 7/14/30-day window.
GET	/api/v1/tracker/verify	Launch+	Validate an API key and report how many AI crawler visits have been logged in the last 30 days (used by the `@foglift/tracker` install wizard).
POST	/api/v1/crawler-analytics	Launch+	Log a single AI crawler visit. Called by the `@foglift/tracker` middleware; 60 req/min per IP rate limit.

Tier naming: Launch+ means Launch ($49/mo), Growth ($129/mo), or Enterprise ($299/mo). Growth+ means Growth or Enterprise. See pricing.

POST /api/v1/ai-visibility

Run an AI visibility check across specified AI models. Debits tokens per model queried.

cURL

curl -X POST https://foglift.io/api/v1/ai-visibility \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["best project management tools", "top CRM software 2026"],
    "models": ["chatgpt", "perplexity", "claude"]
  }'

Both prompts and models are optional. Omit prompts to use your saved monitoring prompts. Omit models to use your enabled models from preferences.

Response

{
  "success": true,
  "summary": {
    "visibility_pct": 60,
    "total_queries": 6,
    "successful": 6,
    "brand_mentions": 4,
    "models_queried": ["chatgpt", "perplexity", "claude"],
    "prompts_checked": 2
  },
  "results": [
    {
      "model": "ChatGPT",
      "prompt": "best project management tools",
      "brand_mentioned": true,
      "position": 3,
      "sentiment": "positive",
      "response_text": "Here are the top project management...",
      "citations": ["https://yoursite.com/features"],
      "competitor_mentions": ["Asana", "Monday.com"]
    }
  ]
}

GET /api/v1/ai-visibility/results

Retrieve historical AI visibility results with filtering and pagination.

cURL

# Last 7 days, all models
curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/ai-visibility/results?days=7"

# Filter by model and prompt
curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/ai-visibility/results?days=30&model=chatgpt&limit=100"

GET/POST /api/v1/models

Read or update which AI models are enabled and the monitoring frequency.

cURL

# Get current settings
curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/models"

# Enable only ChatGPT and Perplexity, set weekly frequency
curl -X POST https://foglift.io/api/v1/models \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled_models": { "chatgpt": true, "perplexity": true, "claude": false, "gemini": false, "ai-overview": false },
    "monitoring_frequency": "weekly"
  }'

GET /api/v1/sentiment

Aggregated sentiment analysis. Returns a Net Sentiment Score (NSS, -100 to +100), daily trend, per-engine breakdown, and alerts. Accepts days (1-90, default 30).

cURL

curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/sentiment?days=30"

GET/POST/DELETE /api/v1/prompts

Manage saved monitoring prompts. If your account has a single workspace, workspace_id is auto-resolved; if you have multiple, pass it explicitly.

cURL

# List prompts
curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/prompts"

# Add prompts (one POST can add multiple)
curl -X POST "https://foglift.io/api/v1/prompts" \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompts": ["best AI search optimization tool", "tools to rank in ChatGPT"]}'

# Remove a prompt by id
curl -X DELETE "https://foglift.io/api/v1/prompts" \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt_id": "prompt_abc123"}'

GET /api/v1/history

Paginated historical GEO result rows. Required: workspace_id. Optional: limit (1-100, default 20), offset, prompt_id, model.

cURL

curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/history?workspace_id=WS_UUID&limit=50&model=chatgpt"

GET /api/v1/monitor

Rolled-up monitoring snapshot: visibility scores, recent citations, and active prompts over a period of 7d (default), 14d, or 30d. Requires workspace_id.

cURL

curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/monitor?workspace_id=WS_UUID&period=30d"

POST /api/v1/scan/batch

Scan up to 10 URLs in one request. Launch+ tier. Counts against your plan's daily scan limit.

cURL

curl -X POST "https://foglift.io/api/v1/scan/batch" \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://site-a.com", "https://site-b.com", "https://site-c.com"]}'

POST /api/v1/scan/sitemap

Fetch the target site's sitemap.xml and scan up to 25 URLs from it. Growth+ tier. Auth via Authorization: Bearer sk_fog_… header.

cURL

curl -X POST "https://foglift.io/api/v1/scan/sitemap" \
  -H "Authorization: Bearer sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "limit": 25}'

GET /api/v1/tracker/verify

Validate an API key and return setup status for the @foglift/tracker package — returns valid, tier, and crawlers_tracked (30-day count).

cURL

curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/tracker/verify"

POST /api/v1/crawler-analytics

Log a single AI crawler hit (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, etc.). Used by the @foglift/tracker middleware to record visits from bots. Rate-limited to 60 requests/minute per IP. Body: { path, userAgent, hostname, timestamp }.

cURL

curl -X POST "https://foglift.io/api/v1/crawler-analytics" \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/pricing",
    "userAgent": "Mozilla/5.0 (compatible; GPTBot/1.0)",
    "hostname": "example.com"
  }'

Dashboard-Internal Endpoints

Foglift also exposes ~30 additional v1 endpoints that authenticate via the dashboard session cookie rather than an API key. These back the web dashboard and aren't meant for scripted use — from a server or automation, prefer the API-key endpoints above.

You can still call them from an authenticated browser context (e.g. a logged-in Foglift tab's DevTools console, or a Chrome extension running with the user's cookies). They are documented here for completeness and because AI agents sometimes need to reference them.

Area	Endpoints
Scans & timeline	`GET /api/v1/scan-history`, `GET /api/v1/scan-diff`, `GET /api/v1/scan-timeline`, `GET/POST /api/v1/scheduled-scans`
AEO scoring	`GET /api/v1/aeo-score`, `GET /api/v1/aeo-history`, `GET /api/v1/workspace-aeo`
Content briefs & recommendations	`GET /api/v1/content-brief`, `GET /api/v1/content-recommendations`, `GET /api/v1/workspace-briefs`
Competitive intel	`GET /api/v1/competitor-suggestions`, `GET /api/v1/competitor-trends`, `GET /api/v1/competitors/per-engine`
Crawler analytics (dashboard read)	`GET /api/v1/crawler-analytics`
Account & workspace	`GET/POST /api/v1/brands`, `GET/POST/PATCH/DELETE /api/v1/team`, `GET/POST/DELETE /api/v1/keys`, `GET/PATCH /api/v1/preferences`, `GET/POST/PATCH/DELETE /api/v1/client-portal`
Tokens & usage	`GET /api/v1/tokens/balance`, `GET /api/v1/tokens/usage`, `GET /api/v1/usage`
Notifications & webhooks	`GET/PATCH /api/v1/notifications`, `GET/POST /api/v1/webhooks`, `GET /api/v1/webhook-logs`
Integrations	`GET/POST/DELETE /api/v1/integrations/slack`, `…/discord`, `…/teams`
Search Console & export	`GET /api/v1/search-console`, `GET /api/v1/search-console/sites`, `GET /api/v1/export`, `POST /api/v1/export/pdf`
Misc	`GET /api/v1/geo-monitor`, `GET/POST /api/v1/email-templates`, `POST/GET /api/v1/onboarding-analytics`

If you need one of these programmatically, open a support request: we can promote it to API-key auth or surface the same data through an existing public endpoint.

Rate Limits & Authentication

Tier	Auth	Scans/Day	Response
Free	None	5 (web) / 10 (API)	All issues + AI action plan + PDF
Launch ($49/mo)	API Key	50 scans/day, 1,000/mo	Daily GEO monitoring, 4,000 tokens/mo, all 5 AI engines, 3 brands, batch scans
Growth ($129/mo)	API Key	200 scans/day, 5,000/mo	Twice-daily monitoring, 11,500 tokens/mo, 10 brands, batch + sitemap scans
Enterprise ($299/mo)	API Key	1,000 scans/day, 25,000/mo	Hourly monitoring, 27,000 tokens/mo, unlimited brands

For authenticated GEO Monitor API requests, include: X-API-Key: sk_fog_YOUR_KEY

Error Handling

HTTP	Error	Meaning	Action
400	invalid_url	URL missing or malformed	Include full URL with https://
429	rate_limited	Daily limit exceeded	Wait 24 hours or upgrade plan
500	scan_failed	Target unreachable	Verify URL is accessible
503	service_unavailable	Foglift temporarily down	Retry in a few minutes

Error Response Format

{
  "error": "rate_limited",
  "message": "Daily scan limit exceeded. Upgrade to Pro for unlimited scans.",
  "limitReached": true
}

CI/CD Integration

Add Foglift scans to your deployment pipeline to catch SEO and GEO regressions before they ship.

GitHub Actions (Official Action)

Use the official Foglift GitHub Action for the simplest setup. Generates a Job Summary with scores and a link to the full report.

.github/workflows/foglift.yml

name: Website Health Check
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 9 * * 1' # Weekly on Monday

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: banant2/Foglift@main
        id: foglift
        with:
          url: 'https://yoursite.com'
          threshold: '70' # Fail if overall score < 70

      # Optional: Use outputs in subsequent steps
      - run: echo "Score: ${{ steps.foglift.outputs.overall }}/100 (${{ steps.foglift.outputs.grade }})"

Input	Required	Description
url	Yes	URL to scan
threshold	No	Minimum score (action fails if below)
categories	No	Categories to check (seo,geo,performance,security,accessibility)

Outputs: overall, seo, geo, performance, security, accessibility, issues, grade, report_url — use in subsequent steps.

GitLab CI

.gitlab-ci.yml

foglift-scan:
  stage: test
  script:
    - RESULT=$(curl -s "https://foglift.io/api/v1/scan?url=$SITE_URL")
    - SCORE=$(echo $RESULT | jq '.scores.overall')
    - echo "Foglift Score: $SCORE/100"
    - '[ "$SCORE" -ge 60 ] || (echo "Score below threshold" && exit 1)'

Shell Script

check-seo.sh

#!/bin/bash
URL=${1:-"https://yoursite.com"}
THRESHOLD=${2:-70}

RESULT=$(curl -s "https://foglift.io/api/v1/scan?url=$URL")
SCORE=$(echo $RESULT | jq '.scores.overall')

echo "Foglift score for $URL: $SCORE/100"

if [ "$SCORE" -lt "$THRESHOLD" ]; then
  echo "FAIL: Score $SCORE is below threshold $THRESHOLD"
  echo $RESULT | jq '.issues[] | select(.severity == "critical") | .title'
  exit 1
fi

echo "PASS: Score meets threshold"
exit 0

Integrations

Connect Foglift to your existing tools and workflows. Use the REST API as the foundation for any integration.

GitHub Actions

Available

Official action: uses: banant2/Foglift@main. See CI/CD section above.

Slack Notifications

Via Webhook

Send scan results to a Slack channel using incoming webhooks. Trigger from CI/CD or a cron job.

Zapier / Make

Via Webhook

Use Foglift's API as a webhook trigger in Zapier or Make to automate scan-report-act workflows.

Google Sheets

Via API

Use Apps Script + Foglift API to log scan results to a spreadsheet. Great for client reports.

BI Tools (Looker, Tableau)

Via REST API

Connect the REST API as a data source. Build dashboards with SEO + GEO trend data over time.

Webhooks

Available

Get notified when scores change. Subscribe to events for automated workflows and alerting.

Slack Integration Example

slack-notify.sh

#!/bin/bash
# Scan and send results to Slack
RESULT=$(curl -s "https://foglift.io/api/v1/scan?url=https://yoursite.com")
SCORE=$(echo $RESULT | jq -r '.scores.overall')
GRADE=$(echo $RESULT | jq -r '.grade')

curl -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "{
    \"text\": \"Foglift Scan: $GRADE ($SCORE/100) for yoursite.com\",
    \"blocks\": [{
      \"type\": \"section\",
      \"text\": { \"type\": \"mrkdwn\", \"text\": \"*Foglift Score:* $GRADE ($SCORE/100)\\nSEO: $(echo $RESULT | jq '.scores.seo') | GEO: $(echo $RESULT | jq '.scores.geo') | Perf: $(echo $RESULT | jq '.scores.performance')\\n<https://foglift.io|View full report>\" }
    }]
  }"

Google Sheets Integration

Apps Script

function scanWithFoglift() {
  const url = "https://yoursite.com";
  const response = UrlFetchApp.fetch(
    "https://foglift.io/api/v1/scan?url=" + encodeURIComponent(url)
  );
  const data = JSON.parse(response.getContentText());

  const sheet = SpreadsheetApp.getActiveSheet();
  sheet.appendRow([
    new Date(),
    url,
    data.scores.overall,
    data.scores.seo,
    data.scores.geo,
    data.scores.performance,
    data.scores.security,
    data.grade
  ]);
}

Ready to integrate?

Start scanning — no API key required for basic scans.

Try a Free Scan For AI Agents View Pricing

Documentation

Foglift Documentation

Everything you need to integrate Foglift — whether you're a developer building a pipeline, an AI agent scanning autonomously, or a team adding SEO checks to CI/CD.

Quick Start

Three ways to use Foglift — pick the one that fits your workflow.

For Humans (CLI)

npx foglift-scan mysite.com

Colored output in terminal

For Code (API)

GET /api/v1/scan?url=...

Structured JSON response

For AI Agents (MCP)

npx foglift-mcp

Claude Code, Cursor, Windsurf

CLI Tool

Scan any website from your terminal. No signup, no API key required for basic scans.

Basic Usage

Terminal

# Scan a website (colored output with scores and issues)
npx foglift-scan https://example.com

# Output as JSON (for scripting)
npx foglift-scan https://example.com --json

# Verbose mode (show all issues, not just top 5)
npx foglift-scan https://example.com --verbose

# Fail CI if score below threshold
npx foglift-scan https://example.com --threshold 80

Example Output

Terminal

$ npx foglift-scan https://example.com

  Foglift — Website Intelligence Scanner

  URL: https://example.com
  Scanned: 2026-03-15 14:30:00 (12 seconds)

  ┌──────────────────────────────────────────────┐
  │  Overall: B (74/100)                         │
  ├──────────────────────────────────────────────┤
  │  SEO:           █████████░  85/100  A        │
  │  GEO:           █████░░░░░  52/100  D        │
  │  Performance:   ████████░░  78/100  C        │
  │  Security:      ██████░░░░  60/100  C        │
  │  Accessibility: █████████░  91/100  A        │
  └──────────────────────────────────────────────┘

  Issues Found: 8 (2 critical, 3 warnings, 3 info)

  🔴 [GEO] AI crawlers blocked by robots.txt
  🔴 [GEO] Missing FAQ schema markup
  🟡 [Security] No Content-Security-Policy header
  🟡 [SEO] Missing Open Graph image tag
  🟡 [Security] No Permissions-Policy header

  Full report → https://foglift.io/scan/abc123

CLI Flags

Flag	Description
--json	Output raw JSON (for piping to jq, scripts, etc.)
--verbose	Show all issues (not just top 5)
--no-color	Disable colored output
--threshold=N	Exit with code 1 if overall score is below N (CI/CD use)

Exit Codes

Code	Meaning
0	Scan completed successfully (or score above threshold)
1	Score below --threshold, or scan error
2	Invalid URL or network error

Advanced Commands (API key required)

Set FOGLIFT_API_KEY to unlock AI visibility monitoring, prompt management, and analytics.

Command	Description
foglift scan batch <urls...>	Batch scan up to 10 URLs at once
foglift scan ai-check	Run AI visibility check across models
foglift scan results	Get historical AI visibility results
foglift scan prompts list	List saved monitoring prompts
foglift scan prompts add "text"	Add a new monitoring prompt
foglift scan prompts remove <id>	Delete a monitoring prompt
foglift scan models	Show enabled AI models and frequency
foglift scan sentiment	Get sentiment analysis trends
foglift scan usage	Show API usage and token balance
foglift scan history <url>	View scan history for a URL

Terminal

# Run AI visibility check with specific prompts and models
export FOGLIFT_API_KEY=sk_fog_your_key_here
foglift scan ai-check --prompt "best seo tools" --models chatgpt,perplexity

# View results from the last 7 days
foglift scan results --days 7 --model chatgpt --json

# Manage monitoring prompts
foglift scan prompts list
foglift scan prompts add "best alternatives to semrush"

# Check token usage
foglift scan usage

REST API

The Foglift REST API provides programmatic access to website intelligence. Free, no auth required for basic scans.

Base URL

https://foglift.io/api/v1

GET /api/v1/scan

Scan a website and return SEO + GEO analysis results.

Parameter	Type	Required	Description
url	string	Yes	Full URL to scan (include https://)
format	string	No	"json" (default) or "text"

Examples

cURL

curl "https://foglift.io/api/v1/scan?url=https://example.com"

JavaScript

const response = await fetch(
  "https://foglift.io/api/v1/scan?url=https://example.com"
);
const data = await response.json();

console.log(data.scores);
// { overall: 72, seo: 85, geo: 65, performance: 78, security: 60, accessibility: 70 }

console.log(data.issues);
// [{ category: "GEO", severity: "critical", title: "AI crawlers blocked", description: "..." }]

console.log(data.aiSummary);
// "This site has strong SEO fundamentals but needs GEO optimization..."

Python

import requests

response = requests.get(
    "https://foglift.io/api/v1/scan",
    params={"url": "https://example.com"}
)
data = response.json()

print(f"Overall: {data['scores']['overall']}/100")
for issue in data["issues"]:
    print(f"  [{issue['severity']}] {issue['title']}")

Response Schema

JSON Response

{
  "url": "https://example.com",
  "scanId": "scan_abc123",
  "scannedAt": "2026-03-15T12:00:00Z",
  "scores": {
    "overall": 72,          // Weighted average (0-100)
    "seo": 85,              // Traditional SEO health (0-100)
    "geo": 65,              // AI search readiness (0-100)
    "performance": 78,      // Page speed & Core Web Vitals (0-100)
    "security": 60,         // HTTP security headers (0-100)
    "accessibility": 70     // WCAG compliance (0-100)
  },
  "letterGrade": "B",       // A (90+), B (80+), C (60+), D (40+), F (<40)
  "issues": [
    {
      "category": "GEO",         // "GEO" | "AEO" | "SEO" | "Performance" | "Security" | "Accessibility"
      "severity": "critical",    // "critical" | "warning" | "info"
      "title": "AI crawlers blocked by robots.txt",
      "description": "GPTBot and ClaudeBot are blocked. Add User-agent: GPTBot\nAllow: / to robots.txt"
    }
  ],
  "aiSummary": "This site has strong SEO fundamentals but lacks GEO optimization...",
  "totalIssues": 12,          // Total issue count (some may be hidden on free tier)
  "tier": "free",             // "free" | "launch" | "growth" | "enterprise"
  "gated": true               // true = some issues hidden (free tier)
}

Issue Severity Levels

Severity	Impact	Action
critical	Directly hurts rankings or blocks AI indexing	Fix immediately
warning	Suboptimal, reduces visibility over time	Fix within a week
info	Best practice recommendation	Consider implementing

Score Methodology

Each category score is calculated from multiple weighted checks. The overall score is a weighted average:

overall = (seo × 0.25) + (geo × 0.25) + (performance × 0.20) + (security × 0.15) + (accessibility × 0.15)

SEO Score (25% of overall)

Traditional search engine optimization health. Based on Google Lighthouse SEO audit + custom checks.

Title tag — present, 30-60 chars, unique, contains target keywords
Meta description — present, 120-160 chars, compelling copy
Heading hierarchy — single H1, logical H2-H6 nesting
Open Graph tags — og:title, og:description, og:image for social sharing
Twitter Card — twitter:card, twitter:title, twitter:image
Canonical URL — present and self-referencing
Image alt text — all images have descriptive alt attributes
Language attribute — html lang="en" set for screen readers
Robots directives — no accidental noindex/nofollow
Sitemap.xml — discoverable at /sitemap.xml
Robots.txt — present and not blocking important pages

AI Readiness Score (25% of overall)

AI search readiness — how well structured your content is for ChatGPT, Perplexity, Google AI Overviews, and Claude.

AI crawler access — GPTBot, ClaudeBot, PerplexityBot, Google-Extended not blocked in robots.txt
Structured data depth — JSON-LD schemas: Organization, FAQPage, Article, Product, HowTo, LocalBusiness
FAQ sections — Q&A content that AI can extract and cite as answers
Entity markup — clear entity definitions (brand, people, products) via schema.org
Content structure — clear headings, short paragraphs, bullet lists, tables
Citation formatting — statistics with sources, expert quotes, attributed data points
Meta quality — comprehensive, accurate metadata that helps AI understand page purpose

Performance Score (20% of overall)

Page speed via Google PageSpeed Insights (Lighthouse). Directly from Google's scoring.

LCP — Largest Contentful Paint (should be < 2.5s)
CLS — Cumulative Layout Shift (should be < 0.1)
INP — Interaction to Next Paint (should be < 200ms)
FCP — First Contentful Paint
Speed Index — visual progress of page load
Total Blocking Time — main thread responsiveness

Security Score (15% of overall)

HTTP security headers. Each missing header deducts points.

HTTPS — valid SSL certificate, no mixed content
Strict-Transport-Security — HSTS header with max-age
Content-Security-Policy — CSP header present
X-Frame-Options — clickjacking protection
X-Content-Type-Options — MIME sniffing prevention (nosniff)
Referrer-Policy — controls information leakage
Permissions-Policy — restricts browser features

Accessibility Score (15% of overall)

WCAG 2.1 compliance via Google Lighthouse accessibility audit.

Color contrast — text meets WCAG AA ratio (4.5:1)
Alt text — all informational images have descriptive alt
Keyboard navigation — interactive elements reachable via Tab
ARIA labels — dynamic/custom elements properly labeled
Form labels — every input has an associated label
Document language — lang attribute set

Score Interpretation Guide

Use this guide to understand what each score range means and what actions to take. AI agents: use these thresholds to prioritize fixes.

90-100: Excellent

Top-tier optimization. Your site is well-positioned for both search and AI.

Action: Maintain current setup. Set up monitoring to catch regressions. Consider the Launch plan for weekly automated scans.

80-89: Good

Solid foundation with a few areas to improve.

Action: Fix remaining critical and warning issues. Usually 2-5 specific items will push you to an A. Check the action recipes below.

60-79: Needs Work

Significant gaps. You're likely losing traffic and AI visibility.

Action: Prioritize critical issues first — they have the biggest impact. Focus on GEO and SEO categories. The free scan gives you the full issue list and AI action plan.

40-59: Poor

Major issues across multiple categories. AI models likely cannot cite your content.

Action: Start with the basics: ensure HTTPS, add meta tags, allow AI crawlers, add structured data. Each fix will have a significant impact at this level.

0-39: Critical

Fundamental issues. The site may be essentially invisible to AI search.

Action: This usually means the site is blocking crawlers, has no meta tags, or has major technical issues. Follow the action recipes in order — start with robots.txt and meta tags.

Action Recipes

For every issue Foglift can detect, here's the exact fix. AI agents: use these as copy-paste solutions when fixing issues programmatically.

GEO Issues

AI crawlers blocked by robots.txt

GPTBot, ClaudeBot, or PerplexityBot is blocked. This means AI models cannot read your content.

Fix: Add these lines to your robots.txt:

robots.txt

User-agent: GPTBot
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: Google-Extended
Allow: /

Verify: Rescan the site. GEO score should increase by 10-20 points.

Missing structured data / JSON-LD

No JSON-LD schemas detected. AI models use structured data to understand your content type and key facts.

Fix: Add JSON-LD to your page's <head>:

HTML

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company",
  "url": "https://yoursite.com",
  "description": "What your company does in one sentence.",
  "logo": "https://yoursite.com/logo.png",
  "sameAs": [
    "https://twitter.com/yourcompany",
    "https://linkedin.com/company/yourcompany"
  ]
}
</script>

Missing FAQ schema

No FAQPage schema detected. FAQ schemas are one of the highest-impact GEO optimizations — they give AI direct Q&A content to cite.

Fix:

HTML

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What does your product do?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Our product does X, Y, and Z for [target audience]."
      }
    },
    {
      "@type": "Question",
      "name": "How much does it cost?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Free to start. Paid plans from $X/month."
      }
    }
  ]
}
</script>

SEO Issues

Missing or poor meta description

No meta description, or it's too short/long. This is the snippet shown in Google search results.

Fix: Add to <head>:

HTML

<meta name="description" content="120-160 characters describing what this page offers. Include your primary keyword naturally. Make it compelling — this is your ad copy in search results.">

Missing Open Graph tags

No og:title, og:description, or og:image. Links shared on social media will look blank.

Fix:

HTML

<meta property="og:title" content="Page Title — Brand Name">
<meta property="og:description" content="Compelling description for social sharing.">
<meta property="og:image" content="https://yoursite.com/og-image.png">
<meta property="og:url" content="https://yoursite.com/this-page">
<meta property="og:type" content="website">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Page Title — Brand Name">
<meta name="twitter:description" content="Compelling description for Twitter.">
<meta name="twitter:image" content="https://yoursite.com/og-image.png">

Security Issues

Missing security headers

Missing HSTS, CSP, X-Frame-Options, or other security headers. Affects both security and SEO ranking.

Fix (Next.js next.config.js):

next.config.js

const securityHeaders = [
  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
  { key: 'X-Content-Type-Options', value: 'nosniff' },
  { key: 'X-Frame-Options', value: 'DENY' },
  { key: 'X-XSS-Protection', value: '1; mode=block' },
  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
];

module.exports = {
  async headers() {
    return [{ source: '/(.*)', headers: securityHeaders }];
  },
};

Fix (Vercel vercel.json):

vercel.json

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains; preload" },
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" },
        { "key": "Permissions-Policy", "value": "camera=(), microphone=(), geolocation=()" }
      ]
    }
  ]
}

MCP Server (AI Agents)

Foglift is available as an MCP (Model Context Protocol) server. AI coding assistants like Claude Code, Cursor, and Windsurf can scan websites and fix issues directly from your IDE.

Connecting from Claude.ai (web)

Use the dedicated mcp.foglift.io endpoint when adding Foglift as a custom connector at claude.ai/customize:

Click Add custom connector
URL: https://mcp.foglift.io/api/mcp
Open Advanced → add header Authorization with value Bearer sk_fog_… (paste a key from Settings)
Click Connect — the connector card goes green and tools become available in new conversations

Installation (Claude Code CLI / IDEs)

Terminal

npm install -g foglift-mcp

Claude Code Setup

Add to ~/.claude/mcp.json:

~/.claude/mcp.json

{
  "mcpServers": {
    "foglift": {
      "command": "npx",
      "args": ["foglift-mcp"]
    }
  }
}

Cursor Setup

Add to .cursor/mcp.json in your project root:

.cursor/mcp.json

{
  "mcpServers": {
    "foglift": {
      "command": "npx",
      "args": ["foglift-mcp"]
    }
  }
}

Windsurf Setup

Add to ~/.windsurf/mcp.json:

~/.windsurf/mcp.json

{
  "mcpServers": {
    "foglift": {
      "command": "npx",
      "args": ["foglift-mcp"]
    }
  }
}

Available MCP Tools

Tool	Description	Parameters
scan_website	Run full SEO + GEO analysis	`url` (required)
batch_scan	Scan multiple URLs at once	`urls` (required, array)
run_ai_visibility	Check AI visibility across engines	`url`, `prompts`
get_ai_results	Retrieve AI visibility results	`workspace_id`
get_prompts	List workspace GEO prompts	`workspace_id`
add_prompt	Add a prompt to monitor	`workspace_id`, `prompt`
delete_prompt	Remove a prompt	`workspace_id`, `prompt_id`
get_models	Get AI model preferences	`workspace_id`
set_models	Configure which AI models to track	`workspace_id`, `models`
get_sentiment	Get AI sentiment analysis	`workspace_id`
get_usage	Check API usage and limits	none
get_scan_history	View past scan results	`url` (optional)
get_geo_monitor	Get GEO monitoring status	`workspace_id`

Example MCP Tool Response

scan_website response

{
  "url": "https://example.com",
  "scores": { "overall": 72, "seo": 85, "geo": 52, "performance": 78, "security": 60, "accessibility": 91 },
  "issues": [
    { "category": "GEO", "severity": "critical", "title": "AI crawlers blocked by robots.txt", "description": "..." },
    { "category": "GEO", "severity": "critical", "title": "No FAQ schema markup", "description": "..." },
    { "category": "Security", "severity": "warning", "title": "Missing CSP header", "description": "..." }
  ],
  "aiSummary": "Strong SEO but weak GEO. AI crawlers are blocked and no structured data is present..."
}

Agent Workflows

Complete workflows for AI agents using Foglift. Copy these patterns to build autonomous SEO/GEO fix pipelines.

Workflow: Scan and Fix All Issues

The most common agent workflow — scan a site, then fix every issue found.

Scan the site — Call scan_website with the URL. Read the full response.
Prioritize by severity — Fix critical issues first, then warnings, then info.
For each issue, look up the action recipe — Match the issue title to the recipes in this docs page.
Apply the fix — Edit the relevant file (robots.txt, HTML head, config, etc.).
Rescan to verify — Run scan_website again. Score should improve.
Commit and deploy — Push changes and redeploy the site.

Workflow: CI/CD Quality Gate

Block deploys when SEO/GEO scores drop below a threshold.

After deploy to staging — Scan the staging URL.
Check overall score — If below threshold (e.g., 70), fail the build.
Check for new critical issues — Compare with previous scan. Any new critical = fail.
Report results — Post scores as a PR comment or CI artifact.

Workflow: New Site Setup

You just deployed a new Next.js/React site. Use Foglift to get it optimized from day one.

Scan the deployed URL — Get baseline scores.
Fix robots.txt — Allow all search engines and AI crawlers.
Add meta tags — title, description, OG tags, Twitter card to every page.
Add JSON-LD structured data — Organization + FAQPage at minimum.
Add security headers — HSTS, CSP, X-Frame-Options, etc.
Generate sitemap.xml — List all public pages.
Submit to Google Search Console — Verify domain, submit sitemap.
Rescan — Verify all scores are 80+.

Public API Reference

Authentication

Endpoint Index

Every API-key-authenticated v1 endpoint currently live in production. Tier column lists the minimum paid tier required; Public means no auth needed.

Method	Endpoint	Tier	Description
GET	/api/v1/scan	Public	Run a website audit. Free for 10 scans/day per IP; higher per-plan limits with an API key.
POST	/api/v1/scan/batch	Launch+	Scan up to 10 URLs in one request.
POST	/api/v1/scan/sitemap	Growth+	Fetch `sitemap.xml` and scan up to 25 of its URLs.
POST	/api/v1/ai-visibility	Launch+	Query ChatGPT, Perplexity, Claude, Gemini, and Google AI Overview for saved or custom prompts. Debits tokens per model.
GET	/api/v1/ai-visibility/results	Launch+	Historical AI visibility results with filters and pagination.
GET	/api/v1/prompts	Launch+	List tracked monitoring prompts for the workspace.
POST	/api/v1/prompts	Launch+	Add one or more monitoring prompts.
DELETE	/api/v1/prompts	Launch+	Remove a monitoring prompt by id.
GET	/api/v1/models	Launch+	Get enabled AI models and monitoring frequency.
POST	/api/v1/models	Launch+	Update enabled models and monitoring frequency.
GET	/api/v1/sentiment	Launch+	Net Sentiment Score, daily trend, and per-engine breakdown.
GET	/api/v1/history	Launch+	Paginated GEO monitoring result rows for a workspace.
GET	/api/v1/monitor	Launch+	Visibility scores, citations, and prompts over a 7/14/30-day window.
GET	/api/v1/tracker/verify	Launch+	Validate an API key and report how many AI crawler visits have been logged in the last 30 days (used by the `@foglift/tracker` install wizard).
POST	/api/v1/crawler-analytics	Launch+	Log a single AI crawler visit. Called by the `@foglift/tracker` middleware; 60 req/min per IP rate limit.

Tier naming: Launch+ means Launch ($49/mo), Growth ($129/mo), or Enterprise ($299/mo). Growth+ means Growth or Enterprise. See pricing.

POST /api/v1/ai-visibility

Run an AI visibility check across specified AI models. Debits tokens per model queried.

cURL

curl -X POST https://foglift.io/api/v1/ai-visibility \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["best project management tools", "top CRM software 2026"],
    "models": ["chatgpt", "perplexity", "claude"]
  }'

Both prompts and models are optional. Omit prompts to use your saved monitoring prompts. Omit models to use your enabled models from preferences.

Response

{
  "success": true,
  "summary": {
    "visibility_pct": 60,
    "total_queries": 6,
    "successful": 6,
    "brand_mentions": 4,
    "models_queried": ["chatgpt", "perplexity", "claude"],
    "prompts_checked": 2
  },
  "results": [
    {
      "model": "ChatGPT",
      "prompt": "best project management tools",
      "brand_mentioned": true,
      "position": 3,
      "sentiment": "positive",
      "response_text": "Here are the top project management...",
      "citations": ["https://yoursite.com/features"],
      "competitor_mentions": ["Asana", "Monday.com"]
    }
  ]
}

GET /api/v1/ai-visibility/results

Retrieve historical AI visibility results with filtering and pagination.

cURL

# Last 7 days, all models
curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/ai-visibility/results?days=7"

# Filter by model and prompt
curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/ai-visibility/results?days=30&model=chatgpt&limit=100"

GET/POST /api/v1/models

Read or update which AI models are enabled and the monitoring frequency.

cURL

# Get current settings
curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/models"

# Enable only ChatGPT and Perplexity, set weekly frequency
curl -X POST https://foglift.io/api/v1/models \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled_models": { "chatgpt": true, "perplexity": true, "claude": false, "gemini": false, "ai-overview": false },
    "monitoring_frequency": "weekly"
  }'

GET /api/v1/sentiment

Aggregated sentiment analysis. Returns a Net Sentiment Score (NSS, -100 to +100), daily trend, per-engine breakdown, and alerts. Accepts days (1-90, default 30).

cURL

curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/sentiment?days=30"

GET/POST/DELETE /api/v1/prompts

Manage saved monitoring prompts. If your account has a single workspace, workspace_id is auto-resolved; if you have multiple, pass it explicitly.

cURL

# List prompts
curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/prompts"

# Add prompts (one POST can add multiple)
curl -X POST "https://foglift.io/api/v1/prompts" \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompts": ["best AI search optimization tool", "tools to rank in ChatGPT"]}'

# Remove a prompt by id
curl -X DELETE "https://foglift.io/api/v1/prompts" \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt_id": "prompt_abc123"}'

GET /api/v1/history

Paginated historical GEO result rows. Required: workspace_id. Optional: limit (1-100, default 20), offset, prompt_id, model.

cURL

curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/history?workspace_id=WS_UUID&limit=50&model=chatgpt"

GET /api/v1/monitor

Rolled-up monitoring snapshot: visibility scores, recent citations, and active prompts over a period of 7d (default), 14d, or 30d. Requires workspace_id.

cURL

curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/monitor?workspace_id=WS_UUID&period=30d"

POST /api/v1/scan/batch

Scan up to 10 URLs in one request. Launch+ tier. Counts against your plan's daily scan limit.

cURL

curl -X POST "https://foglift.io/api/v1/scan/batch" \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://site-a.com", "https://site-b.com", "https://site-c.com"]}'

POST /api/v1/scan/sitemap

Fetch the target site's sitemap.xml and scan up to 25 URLs from it. Growth+ tier. Auth via Authorization: Bearer sk_fog_… header.

cURL

curl -X POST "https://foglift.io/api/v1/scan/sitemap" \
  -H "Authorization: Bearer sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "limit": 25}'

GET /api/v1/tracker/verify

Validate an API key and return setup status for the @foglift/tracker package — returns valid, tier, and crawlers_tracked (30-day count).

cURL

curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/tracker/verify"

POST /api/v1/crawler-analytics

cURL

curl -X POST "https://foglift.io/api/v1/crawler-analytics" \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/pricing",
    "userAgent": "Mozilla/5.0 (compatible; GPTBot/1.0)",
    "hostname": "example.com"
  }'

Dashboard-Internal Endpoints

Area	Endpoints
Scans & timeline	`GET /api/v1/scan-history`, `GET /api/v1/scan-diff`, `GET /api/v1/scan-timeline`, `GET/POST /api/v1/scheduled-scans`
AEO scoring	`GET /api/v1/aeo-score`, `GET /api/v1/aeo-history`, `GET /api/v1/workspace-aeo`
Content briefs & recommendations	`GET /api/v1/content-brief`, `GET /api/v1/content-recommendations`, `GET /api/v1/workspace-briefs`
Competitive intel	`GET /api/v1/competitor-suggestions`, `GET /api/v1/competitor-trends`, `GET /api/v1/competitors/per-engine`
Crawler analytics (dashboard read)	`GET /api/v1/crawler-analytics`
Account & workspace	`GET/POST /api/v1/brands`, `GET/POST/PATCH/DELETE /api/v1/team`, `GET/POST/DELETE /api/v1/keys`, `GET/PATCH /api/v1/preferences`, `GET/POST/PATCH/DELETE /api/v1/client-portal`
Tokens & usage	`GET /api/v1/tokens/balance`, `GET /api/v1/tokens/usage`, `GET /api/v1/usage`
Notifications & webhooks	`GET/PATCH /api/v1/notifications`, `GET/POST /api/v1/webhooks`, `GET /api/v1/webhook-logs`
Integrations	`GET/POST/DELETE /api/v1/integrations/slack`, `…/discord`, `…/teams`
Search Console & export	`GET /api/v1/search-console`, `GET /api/v1/search-console/sites`, `GET /api/v1/export`, `POST /api/v1/export/pdf`
Misc	`GET /api/v1/geo-monitor`, `GET/POST /api/v1/email-templates`, `POST/GET /api/v1/onboarding-analytics`

If you need one of these programmatically, open a support request: we can promote it to API-key auth or surface the same data through an existing public endpoint.

Rate Limits & Authentication

Tier	Auth	Scans/Day	Response
Free	None	5 (web) / 10 (API)	All issues + AI action plan + PDF
Launch ($49/mo)	API Key	50 scans/day, 1,000/mo	Daily GEO monitoring, 4,000 tokens/mo, all 5 AI engines, 3 brands, batch scans
Growth ($129/mo)	API Key	200 scans/day, 5,000/mo	Twice-daily monitoring, 11,500 tokens/mo, 10 brands, batch + sitemap scans
Enterprise ($299/mo)	API Key	1,000 scans/day, 25,000/mo	Hourly monitoring, 27,000 tokens/mo, unlimited brands

For authenticated GEO Monitor API requests, include: X-API-Key: sk_fog_YOUR_KEY

Error Handling

HTTP	Error	Meaning	Action
400	invalid_url	URL missing or malformed	Include full URL with https://
429	rate_limited	Daily limit exceeded	Wait 24 hours or upgrade plan
500	scan_failed	Target unreachable	Verify URL is accessible
503	service_unavailable	Foglift temporarily down	Retry in a few minutes

Error Response Format

{
  "error": "rate_limited",
  "message": "Daily scan limit exceeded. Upgrade to Pro for unlimited scans.",
  "limitReached": true
}

CI/CD Integration

Add Foglift scans to your deployment pipeline to catch SEO and GEO regressions before they ship.

GitHub Actions (Official Action)

Use the official Foglift GitHub Action for the simplest setup. Generates a Job Summary with scores and a link to the full report.

.github/workflows/foglift.yml

name: Website Health Check
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 9 * * 1' # Weekly on Monday

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: banant2/Foglift@main
        id: foglift
        with:
          url: 'https://yoursite.com'
          threshold: '70' # Fail if overall score < 70

      # Optional: Use outputs in subsequent steps
      - run: echo "Score: ${{ steps.foglift.outputs.overall }}/100 (${{ steps.foglift.outputs.grade }})"

Input	Required	Description
url	Yes	URL to scan
threshold	No	Minimum score (action fails if below)
categories	No	Categories to check (seo,geo,performance,security,accessibility)

Outputs: overall, seo, geo, performance, security, accessibility, issues, grade, report_url — use in subsequent steps.

GitLab CI

.gitlab-ci.yml

foglift-scan:
  stage: test
  script:
    - RESULT=$(curl -s "https://foglift.io/api/v1/scan?url=$SITE_URL")
    - SCORE=$(echo $RESULT | jq '.scores.overall')
    - echo "Foglift Score: $SCORE/100"
    - '[ "$SCORE" -ge 60 ] || (echo "Score below threshold" && exit 1)'

Shell Script

check-seo.sh

#!/bin/bash
URL=${1:-"https://yoursite.com"}
THRESHOLD=${2:-70}

RESULT=$(curl -s "https://foglift.io/api/v1/scan?url=$URL")
SCORE=$(echo $RESULT | jq '.scores.overall')

echo "Foglift score for $URL: $SCORE/100"

if [ "$SCORE" -lt "$THRESHOLD" ]; then
  echo "FAIL: Score $SCORE is below threshold $THRESHOLD"
  echo $RESULT | jq '.issues[] | select(.severity == "critical") | .title'
  exit 1
fi

echo "PASS: Score meets threshold"
exit 0

Integrations

Connect Foglift to your existing tools and workflows. Use the REST API as the foundation for any integration.

GitHub Actions

Available

Official action: uses: banant2/Foglift@main. See CI/CD section above.

Slack Notifications

Via Webhook

Send scan results to a Slack channel using incoming webhooks. Trigger from CI/CD or a cron job.

Zapier / Make

Via Webhook

Use Foglift's API as a webhook trigger in Zapier or Make to automate scan-report-act workflows.

Google Sheets

Via API

Use Apps Script + Foglift API to log scan results to a spreadsheet. Great for client reports.

BI Tools (Looker, Tableau)

Via REST API

Connect the REST API as a data source. Build dashboards with SEO + GEO trend data over time.

Webhooks

Available

Get notified when scores change. Subscribe to events for automated workflows and alerting.

Slack Integration Example

slack-notify.sh

#!/bin/bash
# Scan and send results to Slack
RESULT=$(curl -s "https://foglift.io/api/v1/scan?url=https://yoursite.com")
SCORE=$(echo $RESULT | jq -r '.scores.overall')
GRADE=$(echo $RESULT | jq -r '.grade')

curl -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "{
    \"text\": \"Foglift Scan: $GRADE ($SCORE/100) for yoursite.com\",
    \"blocks\": [{
      \"type\": \"section\",
      \"text\": { \"type\": \"mrkdwn\", \"text\": \"*Foglift Score:* $GRADE ($SCORE/100)\\nSEO: $(echo $RESULT | jq '.scores.seo') | GEO: $(echo $RESULT | jq '.scores.geo') | Perf: $(echo $RESULT | jq '.scores.performance')\\n<https://foglift.io|View full report>\" }
    }]
  }"

Google Sheets Integration

Apps Script

function scanWithFoglift() {
  const url = "https://yoursite.com";
  const response = UrlFetchApp.fetch(
    "https://foglift.io/api/v1/scan?url=" + encodeURIComponent(url)
  );
  const data = JSON.parse(response.getContentText());

  const sheet = SpreadsheetApp.getActiveSheet();
  sheet.appendRow([
    new Date(),
    url,
    data.scores.overall,
    data.scores.seo,
    data.scores.geo,
    data.scores.performance,
    data.scores.security,
    data.grade
  ]);
}

Ready to integrate?

Start scanning — no API key required for basic scans.

Try a Free Scan For AI Agents View Pricing