Agent-readable
Crawl4AI 0.9.2
API v1.0.0

Crawl4AI 串接規格

供 AI Agent 與開發者串接 crawler.neteon.net 的 REST API、MCP Server 與內建 UI。最後更新：2026-08-06 UTC。

機器可讀規格

Base URL：https://crawler.neteon.net

OpenAPI 3.x snapshot：/crawl4ai-openapi.json

MCP tools schema snapshot：/crawl4ai-mcp-schema.json

Live health：/health

Agent 應優先讀取上方 JSON schema。本頁提供連線方式、驗證、安全限制與常用範例。

驗證

除公開健康檢查外，API、UI 與 MCP 皆受 Bearer Token 保護：

Authorization: Bearer <CRAWL4AI_API_TOKEN>

Token 不會寫在本公開文件。伺服器管理者可在主機取得：

grep '^CRAWL4AI_API_TOKEN=' /home/ploi/crawler.neteon.net/.env
Agent 不得把 Token 寫入 Git、log、公開 HTML、query string 或 prompt 輸出。應透過環境變數或 client secret storage 注入。

MCP Server 連線

TransportEndpoint用途
SSEhttps://crawler.neteon.net/mcp/sse相容傳統 MCP SSE client；建議優先使用。
WebSocketwss://crawler.neteon.net/mcp/ws支援 WebSocket 的 MCP client。
Schemahttps://crawler.neteon.net/mcp/schema即時工具 schema，需要 Bearer Token。

Claude Code CLI

export CRAWL4AI_API_TOKEN="your-token"

claude mcp add --transport sse \
  crawl4ai https://crawler.neteon.net/mcp/sse \
  --header "Authorization: Bearer $CRAWL4AI_API_TOKEN"

claude mcp list

通用 MCP client 設定概念

{
  "mcpServers": {
    "crawl4ai": {
      "transport": "sse",
      "url": "https://crawler.neteon.net/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${CRAWL4AI_API_TOKEN}"
      }
    }
  }
}

不同 MCP client 的欄位名稱可能不同；核心要求是 SSE URL 與連線時送出的 Authorization header。若 client 不支援自訂 SSE header，使用支援 header 的 MCP proxy／client，勿把 Token 放進 URL。

可用 MCP tools

Tool主要輸入用途
mdurl, f, q輸出 raw／fit／BM25／LLM Markdown。
htmlurl輸出適合 schema extraction 的處理後 HTML。
screenshoturl, wait options產生全頁 PNG artifact。
pdfurl產生 PDF artifact。
crawlurls[], browser/crawler config完整爬取並回傳 CrawlResult。
execute_jsurl, scripts[]執行頁面 JavaScript；目前伺服器預設停用。
askcontext query options查詢 Crawl4AI library code／docs context。

REST API

最小可用 Crawl

curl -X POST 'https://crawler.neteon.net/crawl' \
  -H "Authorization: Bearer $CRAWL4AI_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"urls":["https://example.com"]}'

Python

import os, requests

base_url = "https://crawler.neteon.net"
headers = {"Authorization": f"Bearer {os.environ['CRAWL4AI_API_TOKEN']}"}
response = requests.post(
    f"{base_url}/crawl",
    headers=headers,
    json={"urls": ["https://example.com"]},
    timeout=300,
)
response.raise_for_status()
data = response.json()
print(data["results"][0]["markdown"]["raw_markdown"])

JavaScript / TypeScript

const response = await fetch("https://crawler.neteon.net/crawl", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CRAWL4AI_API_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ urls: ["https://example.com"] })
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const data = await response.json();

主要資料端點

MethodPathRequest／用途
POST/crawl{urls[], browser_config?, crawler_config?, crawler_configs?, hooks?}；同步批次 crawl。
POST/crawl/stream同 crawl request；串流回傳結果。
POST/crawl/job{urls[], browser_config?, crawler_config?, webhook_config?}；背景工作。
GET/crawl/job/{task_id}查詢背景工作狀態與結果。
POST/md{url, f?: "raw"|"fit"|"bm25"|"llm", q?, provider?, temperature?}。
POST/html{url}；處理後 HTML。
POST/screenshot{url, screenshot_wait_for?, wait_for_images?}。
POST/pdf{url}；產生 PDF。
GET/artifacts/{artifact_id}下載 screenshot／PDF artifact。
POST/llm/job{url, q, schema?, provider?, temperature?, webhook_config?}。
GET/llm/job/{task_id}查詢 LLM 背景工作。
POST/execute_js{url, scripts[]}；安全考量目前預設停用。

管理與觀測端點

/health, /metrics, /monitor/health, /monitor/requests, /monitor/browsers, /monitor/endpoints/stats, /monitor/timeline, /monitor/logs/errors, /monitor/logs/janitor。

會改變狀態的管理端點包括 /monitor/actions/cleanup、/monitor/actions/kill_browser、/monitor/actions/restart_browser、/monitor/stats/reset。Agent 不應在未獲授權下呼叫。

內建 UI

Playground：https://crawler.neteon.net/playground/
互動設定 crawl、測試 API、檢視回傳內容與產生 request。

Dashboard：https://crawler.neteon.net/dashboard/
即時監控 requests、browser pool、記憶體、endpoint statistics 與錯誤。

第一次開啟受保護 UI 時，需要提供 API Token。它不是帳號／多人管理後台，也沒有資料庫型 crawler project 管理介面；核心定位是 crawler API server、測試 Playground 與運行監控 Dashboard。

Agent 實作規則與限制