API 参考

CrawlForge MCP API 参考

全部 31 个 CrawlForge MCP 工具的完整参考。使用我们以开发者为先的 API 构建强大的网页抓取应用。

API 概览

基础 URL

Bash

https://crawlforge.dev/api/v1

身份验证

所有 API 请求都需要在 X-API-Key 请求头中传入 API 密钥：

Bash

curl -H "X-API-Key: cf_test_YOUR_KEY" \
     https://crawlforge.dev/api/v1/tools/fetch_url

从控制台获取你的 API 密钥。

请求格式

所有工具端点都在请求体中接收 JSON：

Json

{
  "url": "https://example.com",
  "timeout": 10000,
  "follow_redirects": true
}

响应格式

所有响应都遵循统一格式：

Json

{
  "success": true,
  "data": {
    // Tool-specific response data
  },
  "credits_used": 1,
  "credits_remaining": 999,
  "processing_time": 245
}

响应还可能包含一个可选的顶层 warnings 字符串数组，它与 data、credits_used 并列，而不在 data 内部。只有当请求产生了警告时它才会出现：你用 respect_robots: false 关闭了 robots.txt 检查（这同时会记录到你的 API 密钥上），或者某个多 URL 工具跳过了某个 URL、未能抓取某个来源。如果你从不关闭该检查，且请求的每个 URL 都被允许，那么任何响应都不会带上该字段；它的缺失是正常情况，而不是缺少数据。

HTTP 状态码

状态码	说明
200	OK — 请求成功
400	Bad Request — 参数无效
401	Unauthorized — API 密钥无效或缺失
402	Payment Required — credits 不足
403	Forbidden — robots.txt 禁止 `CrawlForge` 访问该 URL（可用 `respect_robots: false` 覆盖）、该主机列入 CrawlForge 永久排除名单（不可覆盖），或该 URL 解析到私有或内网地址。不会抓取任何内容，也不扣除 credits
429	Too Many Requests — 你所在计划的速率限制（放慢请求或升级计划），或目标站点通过自身 429、503 响应中的 `Retry-After` 要求 CrawlForge 等待，这与计划无关，`respect_robots` 也无法覆盖。两者均不计费
500	Internal Server Error

速率限制

速率限制按 API 密钥计算，并因计划而异。超出限制将返回 429 Too Many Requests 响应。

Free 计划

每秒 1 次请求

Hobby 计划

每秒 2 次请求

Professional 计划

每秒 4 次请求

Business 计划

每秒 10 次请求

全部工具

基础工具 1-2 credits

list_ollama_models

列出本地安装的 Ollama 模型（发现辅助工具）

1 credit

get_batch_results

分页获取 batch_scrape 任务的结果

1 credit

read_result

按句柄读取已存储的结果：slice、search、lines 或 json_path

1 credit

1 credit

1 credit

1 credit

提取页面元数据、OpenGraph 和 Twitter Card 标签

1 credit

1 credit

2 credits

一次抓取完成的统一提取——markdown、HTML、纯文本、链接、元数据等

2 credits

2 credits

2 credits

2 credits

2 credits

通过社区存档搜索 Reddit 帖子/评论或读取完整讨论串

2 credits

高级工具 3-5 credits

3 credits

3 credits

extract_embedded_state

读取页面已写进自身 HTML 的 JSON 状态——不经过 LLM，无从编造

2 credits

extract_structured

由 LLM 驱动的 schema 提取，并支持 CSS 选择器回退

3 credits

extract_with_llm

由 LLM 驱动的提取，默认使用本地 Ollama（可选 OpenAI/Anthropic）

3 credits

4 credits

4 credits

5 credits

5 credits

跨调用保留一个浏览器页面：看它、操作它、读取它

1-3 credits

batch_scrape

通过异步作业管理同时处理多个 URL

5 credits

search_web

搜索实时网络，以 JSON 获取排序后的结果

5 credits

serp_rank

查看某域名针对某个关键词的 Google 自然 SERP 排名位置

5 credits

generate_llms_txt

生成符合标准的 llms.txt 和 llms-full.txt 文件

5 credits

高阶工具 8-10 credits

agent

从自然语言提示词出发的自主研究——无需提供 URL

8 credits

deep_research

多阶段研究，结合 AI 综合分析与来源验证

10 credits

托管监控

监控 API

按 cron 计划每个监控最多 20 个页面，由 CrawlForge 在无需自有进程的情况下对比它们，并接收已签名的 webhook 或邮件——没有按监控收取的费用，每次检查按每个已对比目标收取 track_changes 的价格。

创建 0 credits

官方 SDK

官方 SDK——npm 上的 crawlforge-sdk 和 PyPI 上的 crawlforge——为每个工具提供一个类型化方法，参数与 REST 端点完全一致。每个工具页面的 TypeScript 和 Python 标签页都使用它们。

Typescript

// npm install crawlforge-sdk
import { CrawlForge } from 'crawlforge-sdk';

const client = new CrawlForge({ apiKey: process.env.CRAWLFORGE_API_KEY });

const result = await client.fetchUrl({ url: 'https://example.com' });
console.log('Credits remaining:', result.creditsRemaining);

OpenAPI 规范

整个 REST API 由一份 OpenAPI 3.1 文档描述，地址为 https://www.crawlforge.dev/openapi.json。该文档由验证每个请求的同一套 schema 生成，因此可以直接将代码生成器或 API 客户端指向它。

Bash

curl -s https://www.crawlforge.dev/openapi.json | jq '.paths | keys'

错误处理

所有错误都遵循统一格式，包含 error.code 和 error.message 字段。

Json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": [
      {
        "field": "url",
        "message": "Invalid URL format"
      }
    ]
  }
}

完整的错误代码列表和解决方案请参阅常见问题。

准备好开始构建了吗？

选择一个工具并浏览其文档

查看工具文档返回快速开始