AI Search Monitoring API: Track Citations, Alerts, and BI Metrics

curl "https://foglift.io/api/v1/scan?url=https://example.com" \
        -H "X-API-Key: sk_fog_your_api_key" \
        -H "Content-Type: application/json"

# Public scan, no key required within the free per-IP allowance
      curl "https://foglift.io/api/v1/scan?url=https://example.com"

      # Authenticated scan, higher plan allowance
      curl "https://foglift.io/api/v1/scan?url=https://example.com" \
        -H "X-API-Key: sk_fog_your_api_key"

      # Batch scan, Launch+ plan
      curl -X POST "https://foglift.io/api/v1/scan/batch" \
        -H "X-API-Key: sk_fog_your_api_key" \
        -H "Content-Type: application/json" \
        -d '{"urls": ["https://example.com", "https://example.com/pricing"]}'

# Run one AI Visibility check
      curl -X POST https://foglift.io/api/v1/ai-visibility \
        -H "X-API-Key: sk_fog_your_api_key" \
        -H "Content-Type: application/json" \
        -d '{
          "brand_id": "WS_UUID",
          "prompt": "Best website optimization tools for SaaS companies",
          "domain": "yourbrand.com",
          "models": ["chatgpt", "perplexity", "claude", "gemini"],
          "dry_run": false
        }'

      # Pull recent results for dashboards or warehouse sync
      curl -H "X-API-Key: sk_fog_your_api_key" \
        "https://foglift.io/api/v1/ai-visibility/results?brand_id=WS_UUID&days=30&model=chatgpt&limit=100"

curl -X POST https://foglift.io/api/v1/prompts \
        -H "X-API-Key: sk_fog_your_api_key" \
        -H "Content-Type: application/json" \
        -d '{
          "brand_id": "WS_UUID",
          "prompts": [
            { "text": "Best CRM for startups", "category": "comparison" },
            { "text": "Top project management tools 2026", "category": "industry" },
            { "text": "YourBrand vs CompetitorX", "category": "comparison" }
          ]
        }'

# Dashboard configuration
      Endpoint URL: https://your-server.com/webhooks/foglift
      Events: scan.completed, score.changed, score.dropped, visibility.changed, alert.triggered

      # The receiver below is plain HTTP, so it works with Express, Next.js,
      # Cloudflare Workers, Fastify, or any framework that can parse JSON.

import express from "express";

      const app = express();
      app.use(express.json());

      const SLACK_WEBHOOK = process.env.SLACK_WEBHOOK_URL;

      app.post("/webhooks/foglift", async (req, res) => {
        const { event, data } = req.body;

        // Optional: verify a shared secret if your receiver requires one.
        // const isValid = verifySharedSecret(req);

        let message = "";

        if (event === "score.dropped") {
          message = [
            ":chart_with_downwards_trend: *AI Visibility Drop Detected*",
            `Brand: ${data.brand}`,
            `Page or prompt: ${data.target}`,
            `Previous score: ${data.previous_score}`,
            `Current score: ${data.current_score}`,
            `<https://foglift.io/dashboard|View details>`,
          ].join("\n");
        }

        if (event === "visibility.changed") {
          message = [
            ":warning: *AI Visibility Changed*",
            `Prompt: "${data.prompt}"`,
            `Engine: ${data.engine}`,
            `Mentioned: ${data.mentioned ? "yes" : "no"}`,
            `Citation count: ${data.citations?.length ?? 0}`,
          ].join("\n");
        }

        if (message) {
          await fetch(SLACK_WEBHOOK, {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ text: message }),
          });
        }

        res.status(200).json({ received: true });
      });

      app.listen(3001);

// Fetch 30-day visibility history for Looker ingestion
      const response = await fetch(
        "https://foglift.io/api/v1/ai-visibility/results?" +
          new URLSearchParams({
            brand_id: "WS_UUID",
            days: "30",
            model: "chatgpt",
            limit: "100",
          }),
        {
          headers: {
            "X-API-Key": "sk_fog_your_api_key",
          },
        }
      );

      const data = await response.json();
      // Flatten the JSON into rows before loading your warehouse or BI source.

// Webhook handler: auto-create Linear ticket on visibility drop
      app.post("/webhooks/foglift", async (req, res) => {
        const { event, data } = req.body;

        if (event === "score.dropped" && data.score_change <= -15) {
          await fetch("https://api.linear.app/graphql", {
            method: "POST",
            headers: {
              Authorization: `Bearer ${process.env.LINEAR_API_KEY}`,
              "Content-Type": "application/json",
            },
            body: JSON.stringify({
              query: `mutation {
                issueCreate(input: {
                  teamId: "${process.env.LINEAR_TEAM_ID}",
                  title: "AI visibility drop: ${data.target}",
                  description: "Score dropped ${data.score_change} points.\n\nTarget: ${data.target}\nPrevious score: ${data.previous_score}\nCurrent score: ${data.current_score}\n\n[View in Foglift](https://foglift.io/dashboard)",
                  priority: 2
                }) { issue { id url } }
              }`
            }),
          });
        }

        res.status(200).json({ ok: true });
      });

# Install
      npm install -g foglift-scan

      # Authenticate (env var; generate a key at foglift.io/dashboard/settings)
      export FOGLIFT_API_KEY=sk_fog_your_api_key

      # Scan a single URL (no API key required for the basic scan)
      foglift scan https://example.com
      foglift scan https://example.com --json --threshold=80

      # Run an AI visibility check across engines
      foglift scan ai-check --prompt "best project management tools" \
        --models chatgpt,perplexity,claude,gemini \
        --domain yourbrand.com

      # Pull recent visibility results and sentiment
      foglift scan results --days 7 --model chatgpt --json > results.json
      foglift scan sentiment --days 30 --json

      # Manage tracked prompts
      foglift scan prompts list
      foglift scan prompts add "best tools to rank in ChatGPT"

      # Scan history for a URL
      foglift scan history https://example.com --json

# GitHub Actions example
      - name: AI Readiness scan post-deploy
        env:
          FOGLIFT_API_KEY: ${{ secrets.FOGLIFT_API_KEY }}
        run: |
          npm install -g foglift-scan
          # Fail the build if AI Readiness drops below 80
          foglift scan https://example.com --threshold=80

          # Optional: capture structured results for reporting
          foglift scan https://example.com --json > ai-readiness.json
          foglift scan ai-check --prompt "best tools in your category" \
            --models chatgpt,perplexity --domain example.com --json > visibility.json

# Run on demand (no install)
      npx foglift-mcp

      # Or run as a long-lived HTTP server (for Claude.ai remote MCP)
      npx foglift-mcp --transport http --port 3001

      # Example registration in claude_desktop_config.json
      {
        "mcpServers": {
          "foglift": {
            "command": "npx",
            "args": ["foglift-mcp"],
            "env": { "FOGLIFT_API_KEY": "sk_fog_your_api_key" }
          }
        }
      }

X-RateLimit-Limit: 60
      X-RateLimit-Remaining: 47
      X-RateLimit-Reset: 1742662800

// 429 Too Many Requests
      {
        "error": {
          "code": "rate_limit_exceeded",
          "message": "Rate limit exceeded. Retry after 23 seconds.",
          "retry_after": 23
        }
      }

      // Recommended: exponential backoff with jitter
      async function apiCallWithRetry(url, options, maxRetries = 3) {
        for (let i = 0; i < maxRetries; i++) {
          const res = await fetch(url, options);
          if (res.status === 429) {
            const retryAfter = res.headers.get("Retry-After") || 2 ** i;
            const jitter = Math.random() * 1000;
            await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
            continue;
          }
          return res;
        }
        throw new Error("Max retries exceeded");
      }

# Recent visibility results, scoped to one brand and model
      curl "https://foglift.io/api/v1/ai-visibility/results?brand_id=WS_UUID&days=30&model=chatgpt&limit=100" \
        -H "X-API-Key: sk_fog_your_api_key"

      # Monitoring summary for a 30-day dashboard window
      curl "https://foglift.io/api/v1/monitor?brand_id=WS_UUID&period=30d" \
        -H "X-API-Key: sk_fog_your_api_key"