# SAF-SiteScan-Agent — Full Agent Integration Guide

> Scan any website and get 12 marketing, SEO, and security reports with AI insights. This file is the complete, self-contained guide for AI agents. Base URL: https://sitescan.pedroganco.ai

## Authentication

All API and MCP requests require an API key. Create one at https://sitescan.pedroganco.ai/account/keys (sign in first). The raw key (`sk_live_...`) is shown once — store it safely.

Pass it as a bearer token:
```
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
```

Rate limit: per-key, default 20 requests/minute on scan-creating operations. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; over-limit returns HTTP 429 with `Retry-After`.

## Concepts

- A scan analyzes one URL across 12 reports. Scans are asynchronous and take ~30-90 seconds.
- Scan status: `running` → `completed`. Per-report status: `pending` → `running` → `completed` (or `failed`).
- All REST responses use the envelope `{ "success": true, "data": ... }` or `{ "success": false, "error": { "code", "message" } }`.

## The 12 report types

geo — AI search engine readiness (robots.txt, llms.txt, sitemap, structured data, AI bot access)
seo — Meta tags, headings, redirect chain, canonicals, sitemap/robots
brand — Web presence, brand mentions, positioning (AI)
tag — Third-party scripts, tracking pixels, analytics tags
wcag — WCAG 2.1 accessibility violations and passes (axe-core)
keywords — Keyword density, title/H1/meta alignment, content gaps, readability
cookies — GDPR/ePrivacy compliance, consent mechanism, pre-consent tracking
business — Competitors, market positioning, target audience (AI)
lighthouse — Core Web Vitals: performance, accessibility, best practices, SEO
tech — SSL/TLS, DNS records (SPF, DMARC, DKIM), server, detected libraries
runtime — JS console errors, failed requests, deprecated APIs, JS heap
martech — Detected marketing software versions and known CVE vulnerabilities

## Option A — MCP server (recommended for agents)

Endpoint: https://sitescan.pedroganco.ai/mcp (Streamable HTTP, stateless).

Tools:
- sitescan_scan({ url, scanPath? }) — start a scan, returns { id, domain, status }
- sitescan_get_scan({ scan_id }) — status + each report's score/grade/summary
- sitescan_get_report({ scan_id, report_type }) — one report's full data
- sitescan_wait({ url? , scan_id?, timeout_sec? }) — start (or resume) and wait until completed (one-shot)
- sitescan_list_scans({ domain?, limit? }) — list all scans you've run with this key ("show me my scans")
- sitescan_list_reports() — the 12 report types

Cursor (~/.cursor/mcp.json) — key in URL:
{
  "mcpServers": {
    "sitescan": { "url": "https://sitescan.pedroganco.ai/mcp/sk_live_YOUR_KEY" }
  }
}

Cursor — header auth:
{
  "mcpServers": {
    "sitescan": {
      "url": "https://sitescan.pedroganco.ai/mcp",
      "headers": { "Authorization": "Bearer sk_live_YOUR_KEY" }
    }
  }
}

Claude Desktop (via mcp-remote bridge):
{
  "mcpServers": {
    "sitescan": {
      "command": "npx",
      "args": ["mcp-remote", "https://sitescan.pedroganco.ai/mcp", "--header", "Authorization: Bearer sk_live_YOUR_KEY"]
    }
  }
}

## Option B — REST API

Start a scan:
  POST /api/v1/scan
  Body: { "url": "example.com", "scanPath": false }
  → 202 { "success": true, "data": { "id": "abc123", "domain": "example.com", "status": "running", "links": {...} } }

Poll status + scores:
  GET /api/v1/scan/{id}
  → 200 { "success": true, "data": { "id", "domain", "status", "progress": { "completed", "total" }, "reports": [ { "type", "status", "score", "grade", "summary" } ] } }

One report's full data:
  GET /api/v1/scan/{id}/report/{type}     (type = geo|seo|brand|tag|wcag|keywords|cookies|business|lighthouse|tech|runtime|martech)

AI executive summary + action items:
  GET /api/v1/scan/{id}/summary
  → 200 when ready, or 202 { ..., "generating": true } until the AI insights are cached (shortly after completion)

Scan and wait (capped long-poll, no polling loop needed):
  POST /api/v1/scan/sync
  Body: { "url": "example.com", "wait": 20 }   (wait: seconds, default 20, max 55)
  → 200 with full status if it finished, else 202 with current status + id

List the scans you've run (newest first; "show me my scans"):
  GET /api/v1/scans            (optional ?domain=acme&limit=100)
  → { "success": true, "data": { "scope": "key|account", "count": n, "scans": [ { "id","domain","status","created_at","avg_score","links" } ] } }
  Note: a normal key lists only the scans it created; an "organization" key (created with account scope in the dashboard) lists EVERY scan in the account.

List report types:
  GET /api/v1/reports

Example:
  curl -X POST https://sitescan.pedroganco.ai/api/v1/scan \
    -H "Authorization: Bearer sk_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url":"example.com"}'

## Option C — ChatGPT Actions / Custom GPT

Add the OpenAPI spec as an Action: https://sitescan.pedroganco.ai/api/openapi.json
Authentication: API Key, type Bearer. Operations: startScan, scanAndWait, getScan, getReport, getScanSummary, listReportTypes.

## Errors

- 400 invalid_body / missing_url / invalid_url / invalid_report_type
- 401 invalid_api_key — missing or invalid bearer key
- 404 scan_not_found / report_not_found
- 429 rate_limited — includes Retry-After

## About

Built by Spider AF (https://spideraf.com), an ad fraud prevention company. AI-generated insights are probabilistic and should be verified. Scans require a publicly accessible URL and reflect a point-in-time snapshot.