API Endpoint 参考

所有 FourA API endpoint 的参考文档，包含 request 参数和 response 格式。

Base URL

https://eu.api.foura.ai/api

Authentication

每个 request 都需要在 X-API-Key header 中携带您的 API key：

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'

在 Dashboard 中创建和管理 API key。Key 使用 pk_live_ 前缀。

Response Headers

来自 /api/* 的每个 response 都包含一个关联 header：

Header	Value	说明
`X-Foura-Request-Id`	UUID	分配给该 request 的唯一 ID。在每个 response 中返回，包括 4xx 和 5xx。请在您系统侧记录此 ID。

相同的 ID 会作为 Dashboard 中 Activity Log（保留 24 小时，每个 key 最多 200 条）里 request 和 response payload 预览的键，以便您稍后查找确切的 request，并直接从 Activity 重新播放到 Playground。联系支持团队时请提供此 ID，以便在几秒钟内定位到该 request。

$ curl -i -X POST https://eu.api.foura.ai/api/single/ \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"method": "GET", "url": "https://example.com"}'

HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
...

Endpoints

通过 MCP 使用这些 endpoint？ @fouradata/mcp server 将所有三个 endpoint 封装为原生 MCP 工具（foura_single、foura_proxy、foura_browser），具有相同的输入格式，并提供 offload_large 选项，以便对 token 友好地处理大型 response。

FourA 提供三个 request endpoint，每个都针对不同的场景进行了优化：

Endpoint	适用场景
`POST /single/`	快速 HTTP request、静态页面、API
`POST /proxy/`	具有自动 proxy 轮换的受保护网站
`POST /browser/`	JavaScript 渲染的页面、SPA

Target URL Restrictions

在 request 离开 FourA 之前，解析为私有、回环或保留 IP 地址范围（RFC 5735、RFC 6598、IPv6 保留块）的目标将被拒绝并返回 400。仅转发公共主机名和 IP。

{ "error": "Target <ip> resolves to a private/reserved IP" }

Single Request

POST /api/single/

发送具有逼真浏览器特征的 HTTP request，而无需启动真实的浏览器。这是最快的 endpoint。

Request Body

Parameter	Type	Required	Default	说明
`method`	string	是	-	HTTP 方法：GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS
`url`	string	是	-	目标 URL。在 URL 的任何位置使用 `{ts}` 插入当前时间戳以防止缓存。
`headers`	[string, string][]	否	-	自定义 header，格式为 [name, value] 键值对
`unblocker`	boolean	否	false	注入逼真的浏览器 header（User-Agent、Sec-Ch-Ua、Sec-Fetch-*、Accept-Encoding）
`timeout_ms`	number	否	15000	整体超时时间（毫秒，最大值：120000）
`connect_timeout_ms`	number	否	5000	连接超时时间（毫秒）
`accept_timeout_ms`	number	否	5000	接受超时时间（毫秒，等待连接被接受的时间）
`server_response_timeout_ms`	number	否	15000	服务器响应超时时间（毫秒，等待首字节的时间）
`dns_cache_timeout_sec`	number	否	120	DNS 缓存 TTL（秒，最大值：240)
`followRedirects`	number	否	disabled	要跟随的最大重定向次数（0-20）。省略则禁用。
`tryJsonData`	boolean	否	false	如果可能，将 response body 解析为 JSON
`returnBuffer`	boolean	否	false	返回原始 buffer 而不是解码后的字符串
`data`	any	否	-	Request body（字符串或对象，自动序列化为 JSON）
`proxy`	string	否	-	Proxy URL（http、socks4 或 socks5）或先前 response 返回的 proxy ID
`validate`	object	否	-	Response 验证规则（见下文）

Validation Rules

validate 对象允许您定义成功和失败的条件。如果匹配到 fail 条件，则该 request 被视为失败。如果设置了 accept 条件，则只有匹配的 response 才被视为成功。

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}

Field	Type	说明
`validate.status.accept`	number[]	接受的 HTTP 状态码
`validate.status.fail`	number[]	拒绝的 HTTP 状态码
`validate.headers.accept`	object	必须存在的 header 键值对
`validate.headers.fail`	object	触发失败的 header 键值对
`validate.data.accept`	string[]	必须出现在 response body 中的字符串
`validate.data.fail`	string[]	导致失败的 response body 中的字符串

Example

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://example.com/products",
    "unblocker": true,
    "timeout_ms": 10000
  }'

Response：

{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "nginx", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342
}

Field	Type	说明
`status`	number	来自目标的 HTTP 状态码
`headers`	array	每个重定向跳转对应一个对象。每个对象都有一个包含状态行以及所有 response header 的 `result` 字段。多值 header（`Set-Cookie`、`Link`、`WWW-Authenticate`）将作为字符串数组返回。
`data`	string/object	Response body（如果 `tryJsonData` 为 true，则为 JSON）
`total_time`	number	总 request 时间（秒）
`error`	string	request 失败时的错误信息

Proxy Request

POST /api/proxy/

通过轮换 proxy 路由您的 request，并在失败时自动重试。

Request Body

Parameter	Type	Required	Default	说明
`request`	object	是	-	单个 request body（与上述 Single Request 字段相同）
`timeout_ms`	number	否	45000	所有尝试的总超时时间（毫秒，最大值：120000）
`maxTries`	number	否	5	最大 proxy 轮换尝试次数（最大值：90）
`ignoreProxies`	string[]	否	-	要从轮换中排除的 proxy ID（使用先前 response 返回的 ID）

Example

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 3,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'

Response：

{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "a1b2c3",
  "total": 2.341
}

Field	Type	说明
`proxy`	string	所用 proxy 的编码标识符。通过将其作为 `proxy` 字段传递，可在 Single 或 Browser request 中重用它，或者在下一次 Proxy request 中通过 `ignoreProxies` 跳过它。
`total`	number	外部实际持续时间（秒，浮点数）。包括 proxy 选择、重试和成功的尝试。`total_time` 仅指内部 request 时间，`total` 始终 >= `total_time`。
`error`	string	request 失败时的错误信息

所有 Single Request 的 response 字段也包含在内。

Browser Request

POST /api/browser/

在 Chrome 浏览器实例中打开您的 URL。页面加载、JavaScript 执行，您将获得完整渲染的 HTML 以及 cookie 容器。

Request Body

Parameter	Type	Required	Default	说明
`url`	string	是	-	目标 URL
`headers`	object	否	-	自定义 header，格式为键值对
`cookies`	array	否	-	要设置的 cookie：`[{name, value, domain?}]`
`userAgent`	string	否	-	自定义 User-Agent 字符串
`proxy`	string	否	-	Proxy URL 或先前 response 返回的 proxy ID
`timeout_ms`	number	否	30000	页面加载超时时间（毫秒，最大值：120000）
`checkStatus`	number	否	-	期望的 HTTP 状态码（如果不同则 request 失败）
`checkText`	string	否	-	渲染页面中必须出现的文本

Example

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

Response：

{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0..."
}

Field	Type	说明
`status`	number	来自目标的 HTTP 状态码
`headers`	object	Response header
`body`	string or object	完整渲染的页面内容。当 content-type 为 HTML 时为字符串形式的 HTML；当页面返回 JSON 且被自动解析时为对象。
`cookies`	array	来自页面的完整 cookie 对象。每个 cookie 都包含 `name`、`value`、`domain`、`path`、`expires`、`httpOnly`、`secure`、`sameSite` 以及其他 cookie 属性。
`userAgent`	string	所使用的浏览器 User-Agent
`error`	string	request 失败时的错误信息

HTTP Status Codes

Code	说明
200	Request 已完成（检查内部 `status` 以获取目标 response）
400	无效的 request body、参数，或目标 IP 处于私有/保留范围内
401	缺失或无效的 API key
429	超出 rate limit
500	服务器内部错误
503	服务暂时禁用或容量已满

Next Steps

Authentication：管理您的 API key
Error Handling：优雅地处理错误
Rate Limits：了解 request 限制
Quick Start：在 30 秒内完成您的首次 request

更新于： 2026年7月1日