Foglift Developer Docs: API, CLI, MCP, and Webhooks

# 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 Site Technical Health is 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: C (79/100)                         │
  ├──────────────────────────────────────────────┤
  │  SEO:           █████████░  85/100  A        │
  │  GEO:           ███████░░░  65/100  C        │
  │  AEO:           ███████░░░  71/100  C        │
  │  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

# Reuse an eligible capture from the previous hour
curl "https://foglift.io/api/v1/scan?url=https://example.com"

# Require a fresh crawl (force=true is an equivalent alias)
curl "https://foglift.io/api/v1/scan?url=https://example.com&refresh=true"

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

console.log(data.cached, data.scannedAt);
// true, "2026-09-17T18:30:00.000Z"

const issues = data.issues ?? data.topIssues;
console.log(data.scores, issues);

import requests

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

print(f"Site Technical Health: {data['scores']['overall']}/100")
print(f"AI Readiness: {data['scores']['aiReadiness']}/100")
print(f"Cached: {data['cached']} · captured {data['scannedAt']}")
for issue in data.get("issues", data.get("topIssues", [])):
    print(f"  [{issue['severity']}] {issue['title']}")

{
  "url": "https://example.com",
  "scores": {
    "overall": 73,
    "seo": 85,
    "aiReadiness": 71,
    "aiVisibility": 65,
    "geo": 65,
    "aeo": 71,
    "performance": 78,
    "security": 60,
    "accessibility": 70
  },
  "issues": [
    {
      "category": "AI Visibility",
      "severity": "critical",
      "title": "AI crawlers blocked by robots.txt",
      "description": "GPTBot and ClaudeBot are blocked. Add User-agent: GPTBot\nAllow: / to robots.txt"
    }
  ],
  "totalIssues": 12,
  "cached": true,
  "scannedAt": "2026-09-17T18:30:00.000Z",
  "scoreContractVersion": "technical-audit-v3",
  "scanId": "scan_abc123",
  "fullReport": "https://foglift.io/scan/scan_abc123",
  "_meta": {
    "tool": "Foglift",
    "version": "1.0",
    "docs": "https://foglift.io/developers"
  }
}

{
  "topIssues": [
    {
      "category": "AI Visibility",
      "severity": "critical",
      "title": "AI crawlers blocked by robots.txt",
      "description": "..."
    }
  ],
  "totalIssues": 12,
  "upgrade": "https://foglift.io/pricing",
  "_meta": {
    "tool": "Foglift",
    "version": "1.0",
    "docs": "https://foglift.io/developers",
    "note": "Found 12 issues. Get the full report with all issues and AI action plan at the fullReport URL."
  }
}

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": 79, "seo": 85, "aiReadiness": 71, "performance": 78, "security": 60, "accessibility": 91 },
  "topIssues": [
    { "category": "AI Visibility", "severity": "critical", "title": "AI crawlers blocked by robots.txt", "description": "..." },
    { "category": "AI Visibility", "severity": "critical", "title": "No FAQ schema markup", "description": "..." },
    { "category": "Security", "severity": "warning", "title": "Missing CSP header", "description": "..." }
  ],
  "totalIssues": 9,
  "cached": true,
  "scannedAt": "2026-09-17T18:30:00.000Z",
  "scoreContractVersion": "technical-audit-v3",
  "scanId": "scan_abc123",
  "fullReport": "https://foglift.io/scan/scan_abc123",
  "upgrade": "https://foglift.io/pricing",
  "_meta": { "tool": "Foglift", "version": "1.0", "docs": "https://foglift.io/developers" }
}

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,
  "outcome": "complete",
  "code": "scan_complete",
  "summary": {
    "visibility_pct": 60,
    "total_queries": 6,
    "successful": 6,
    "errors": 0,
    "brand_mentions": 4,
    "models_queried": ["chatgpt", "perplexity", "claude"],
    "prompts_checked": 2,
    "persisted_results": 6,
    "unmatched_prompts": 0,
    "dry_run": false,
    "total_cost_usd": 0.038,
    "brand_used": "Your Brand",
    "domain_used": "yoursite.com",
    "aliases_used": []
  },
  "results": [
    {
      "model": "ChatGPT",
      "prompt": "best project management tools",
      "brand_mentioned": true,
      "position": 3,
      "sentiment": "positive",
      "sentiment_score": 0.82,
      "response_text": "Here are the top project management...",
      "citations": ["https://yoursite.com/features"],
      "competitor_mentions": ["Asana", "Monday.com"],
      "error": null
    }
  ]
}

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

curl -H "X-API-Key: sk_fog_YOUR_KEY" \
  "https://foglift.io/api/v1/results/RESULT_UUID/trace?brand_id=WS_UUID"

# 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/sensor/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 { senseAITraffic } from "@foglift/sensor/nextjs";

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

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

import express from "express";
import { senseAITraffic } from "@foglift/sensor/express";

const app = express();
app.use(senseAITraffic({ 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 Site Technical Health < 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 "Site Technical Health: $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 "Site Technical Health 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')
READINESS=$(echo $RESULT | jq -r '.scores.aiReadiness')

curl -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "{
    \"text\": \"Foglift Site Technical Health: $SCORE/100 for yoursite.com\",
    \"blocks\": [{
      \"type\": \"section\",
      \"text\": { \"type\": \"mrkdwn\", \"text\": \"*Site Technical Health:* $SCORE/100\\nSEO: $(echo $RESULT | jq '.scores.seo') | AI Readiness: $READINESS | 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.aiReadiness,
    data.scores.performance,
    data.scores.security,
    data.scores.accessibility
  ]);
}