SiteScan for agents

Point any AI agent at our onboarding skill — it explains how to consult and call SiteScan:

curl -s https://sitescan.pedroganco.ai/agent-onboarding/SKILL.md

Use it whichever way your agent supports:

• Save it as a skill: curl -s https://sitescan.pedroganco.ai/agent-onboarding/SKILL.md -o .claude/skills/sitescan/SKILL.md
• Or just tell your agent: “Read https://sitescan.pedroganco.ai/agent-onboarding/SKILL.md and use it to scan <site>.”
• Or install from GitHub: npx skills add pedroganco-spider/agentic-sitescan

The agent still needs an API key (next step). Full steps below.

Sign in and create a key at /account/keys. The raw key (sk_live_…) is shown once. Pass it as a bearer token on every request:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Rate limit: per-key, default 20 req/min on scan-creating calls. Over-limit returns HTTP 429 with Retry-After.

Tip: tick Organization access when creating a key to let it read all scans in your account (via GET /api/v1/scans / sitescan_list_scans), not just the ones it creates — handy for a central agent or dashboard.

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

• sitescan_scan— Start a scan of a URL — returns a scan id.
• sitescan_get_scan— Get status + each report's score, grade, and summary.
• sitescan_get_report— Get one report's full structured data.
• sitescan_wait— Start (or resume) a scan and wait until it completes.
• sitescan_list_scans— List all scans you've run with your key (“show me my scans”).
• sitescan_list_reports— List the 12 report types.

{
  "mcpServers": {
    "sitescan": { "url": "https://sitescan.pedroganco.ai/mcp/sk_live_YOUR_KEY" }
  }
}

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

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

https://sitescan.pedroganco.ai/mcp/sk_live_YOUR_KEY

Then ask your agent: ”scan example.com with sitescan and summarise the results.”

Start a scan, then poll — or use /sync to wait in one call. All responses use the envelope { success, data }.

# Start a scan
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"}'
# → { "success": true, "data": { "id": "abc123", "status": "running" } }

# Poll status + report scores
curl https://sitescan.pedroganco.ai/api/v1/scan/abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# AI executive summary + action items
curl https://sitescan.pedroganco.ai/api/v1/scan/abc123/summary \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Or: scan and wait in one call (capped long-poll)
curl -X POST https://sitescan.pedroganco.ai/api/v1/scan/sync \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com","wait":20}'

Other endpoints: GET /api/v1/scans (list the scans you've run — supports ?domain= & ?limit=), GET /api/v1/scan/{id}/report/{type} (one report), and GET /api/v1/reports (list types).

Native MCP (recommended — ChatGPT Plus / Pro / Team)

ChatGPT supports remote MCP servers natively. Go to chatgpt.com → Settings → Personalisation → Connected apps → Add (+) and paste the URL from the MCP panel above (https://sitescan.pedroganco.ai/mcp/sk_live_YOUR_KEY). ChatGPT discovers all 6 tools automatically — no config file needed.

ChatGPT Actions / Custom GPT (OpenAPI)

For Custom GPTs or GPT Actions, add the OpenAPI spec: https://sitescan.pedroganco.ai/api/openapi.json. Set Authentication to API Key → Bearer. Operations: startScan, scanAndWait, getScan, getReport, getScanSummary, listReportTypes.

Pending npm publishA zero-dependency CLI, npx saf-sitescan, is built and on the way — not yet published to npm. Once live you'll be able to run:

npx saf-sitescan scan example.com --wait --json

Until then, use the MCP or REST options above (both fully live).

Error responses are { success: false, error: { code, message } }. Codes: invalid_api_key (401), rate_limited (429), scan_not_found (404), missing_url/invalid_url (400).