Foglift Documentation

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

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

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

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

$ foglift scan https://example.com

  Foglift Technical Audit

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

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

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

  [AI Readiness] AI crawlers blocked by robots.txt
  [AI Readiness] 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

# 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

# Show AI-engine referrals by engine, path, and day
foglift scan referrers --days 30 --domain example.com

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

# Check token usage
foglift scan usage

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

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 AI Readiness improvements..."

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']}")

{
  "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 Readiness score, legacy field name (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"; legacy label for AI Readiness issues
      "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 needs AI Readiness improvements...",
  "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)
}

npm install -g foglift-mcp

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

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

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

{
  "error": "Account has multiple brands. Pass brand_id to disambiguate.",
  "code": "multi_brand_disambiguation_required",
  "docs_url": "https://foglift.io/docs/api-errors#multi_brand_disambiguation_required",
  "request_id": "req_m3k7x9...",
  "details": {
    "brands": [
      { "id": "8f4c2a10-6c2f-4b2e-b2a1-4c5e7f8a9b10", "name": "Brand A", "domain": "branda.com" },
      { "id": "1f2e3d4c-5b6a-4789-8abc-0def12345678", "name": "Brand B", "domain": "brandb.com" }
    ]
  }
}

{
  "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 AI Readiness. AI crawlers are blocked and no structured data is present..."
}

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

{
  "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"]
    }
  ]
}

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

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

# 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"
  }'

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

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

# Add prompts (one POST can add multiple). Response shape:
#   { "created": N, "inserted": N, "deduped": M, "prompts": [...] }
# Include Idempotency-Key for safe retry loops. Replays return the cached
# first response verbatim within a 24-hour window.
curl -X POST "https://foglift.io/api/v1/prompts" \
  -H "X-API-Key: sk_fog_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-2026-05-11-001" \
  -d '{"brand_id": "WS_UUID", "prompts": [{"text": "best AI search optimization tool"}, {"text": "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 '{"brand_id": "WS_UUID", "prompt_id": "prompt_abc123"}'

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

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

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"]}'

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}'

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

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",
    "brand_id": "WS_UUID"
  }'

curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/referrer-analytics?brand_id=WS_UUID&days=30"

import { trackAITraffic } from "@foglift/tracker/nextjs";

export const middleware = trackAITraffic({
  apiKey: process.env.FOGLIFT_API_KEY!,
});

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

import express from "express";
import { trackAITraffic } from "@foglift/tracker/express";

const app = express();
app.use(trackAITraffic({ apiKey: process.env.FOGLIFT_API_KEY! }));

{
  "error": "Too many requests. Please retry after the rate limit window resets.",
  "code": "rate_limited",
  "docs_url": "https://foglift.io/docs/api-errors#rate_limited",
  "request_id": "req_m3k7x9..."
}

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 }})"

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)'

#!/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

#!/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') | AI Readiness: $(echo $RESULT | jq '.scores.geo') | Perf: $(echo $RESULT | jq '.scores.performance')\\n<https://foglift.io|View full report>\" }
    }]
  }"

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
  ]);
}