API Endpoints Reference

リクエストパラメータとresponse形式を含む、すべてのFourAのAPI endpointのリファレンスです。

Base URL

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

認証

すべてのrequestには、X-API-Key headerにAPIキーを含める必要があります。

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キーを作成および管理します。キーにはpk_live_プレフィックスが使用されます。

Response Header

/api/*からのすべてのresponseには、1つの関連付けheaderが含まれます。

Header	値	説明
`X-Foura-Request-Id`	UUID	requestに割り当てられる一意のID。4xxおよび5xxを含むすべてのresponseで返されます。開発者側でログに記録してください。

同じIDが、DashboardのActivity Log（24時間保持、キーごとに最新の200件まで）におけるrequestおよびresponseペイロードのプレビューのキーとなります。これにより、後で正確な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
...

Endpoint

MCP経由でこれらのendpointを使用しますか？ @fouradata/mcp serverは、3つすべてのendpointをネイティブのMCPツール（foura_single、foura_proxy、foura_browser）としてラップします。これらは同じ入力形式を持ち、さらにtokenに配慮した大容量のresponse処理のためのoffload_largeオプトインを備えています。

FourAは、それぞれ異なるシナリオに最適化された3つのrequest endpointを提供します。

Endpoint	最適な用途
`POST /single/`	高速なHTTP request、静的ページ、API
`POST /proxy/`	自動proxyローテーションを備えた保護されたサイト
`POST /browser/`	JavaScriptでレンダリングされるページ、SPA

ターゲットURLの制限

プライベート、ループバック、または保留されたIP範囲（RFC 5735、RFC 6598、IPv6保留ブロック）に解決されるターゲットは、requestがFourAから送信される前に400エラーで拒否されます。パブリックなホスト名とIPのみが転送されます。

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

Single Request

POST /api/single/

実際のブラウザを起動することなく、現実的なブラウザ風の通信特性を持つHTTP requestを送信します。これは最も高速なendpointです。

Request Body

パラメータ	型	必須	デフォルト	説明
`method`	string	はい	-	HTTP method：GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS
`url`	string	はい	-	ターゲットURL。URL内の任意の場所に`{ts}`を使用すると、キャッシュバスター用の現在のタイムスタンプが挿入されます。
`headers`	[string, string][]	いいえ	-	[名前, 値]のペアとしてのカスタムheader
`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	ミリ秒単位のサーバーresponseタイムアウト（最初のバイトの待機時間）
`dns_cache_timeout_sec`	number	いいえ	120	秒単位 of DNSキャッシュTTL（最大：240）
`followRedirects`	number	いいえ	無効	追跡する最大リダイレクト数（0-20）。無効にする場合は省略します。
`tryJsonData`	boolean	いいえ	false	可能であればresponseボディをJSONとして解析します
`returnBuffer`	boolean	いいえ	false	デコードされた文字列の代わりに生のバッファを返します
`data`	any	いいえ	-	requestボディ（文字列またはオブジェクト、自動的にJSONにシリアライズされます）
`proxy`	string	いいえ	-	proxy URL（http、socks4、またはsocks5）、または以前のresponseによって返されたproxy ID
`validate`	object	いいえ	-	response検証ルール（以下を参照）

検証ルール

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"] }
  }
}

フィールド	型	説明
`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ボディに含まれている必要がある文字列
`validate.data.fail`	string[]	失敗をトリガーするresponseボディ内の文字列

例

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
}

フィールド	型	説明
`status`	number	ターゲットからのHTTPステータスコード
`headers`	array	リダイレクトのホップごとに1つのオブジェクト。それぞれにステータス行とすべてのresponse headerを含む`result`フィールドがあります。複数の値を持つheader（`Set-Cookie`、`Link`、`WWW-Authenticate`）は、文字列の配列として返されます。
`data`	string/object	responseボディ（`tryJsonData`がtrueの場合はJSON）
`total_time`	number	秒単位の合計request時間
`error`	string	requestが失敗した場合のエラーメッセージ

Proxy Request

POST /api/proxy/

失敗時の自動再試行を備えた、ローテーションするproxyを経由してrequestをルーティングします。

Request Body

パラメータ	型	必須	デフォルト	説明
`request`	object	はい	-	単一のrequestボディ（上記のSingle Requestと同じフィールド）
`timeout_ms`	number	いいえ	45000	すべての試行におけるミリ秒単位の全体的なタイムアウト（最大：120000）
`maxTries`	number	いいえ	5	最大proxyローテーション試行回数（最大：90)
`ignoreProxies`	string[]	いいえ	-	ローテーションから除外するproxy ID（以前のresponseによって返されたIDを使用）

例

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
}

フィールド	型	説明
`proxy`	string	使用されたproxyのエンコードされた識別子。`proxy`フィールドとして渡すことで、SingleまたはBrowser requestで再利用できます。あるいは、`ignoreProxies`を介して次のProxy requestでスキップすることもできます。
`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

パラメータ	型	必須	デフォルト	説明
`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	いいえ	-	レンダリングされたページに表示される必要があるテキスト

例

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..."
}

フィールド	型	説明
`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ステータスコード

コード	意味
200	request完了（ターゲットのresponseについては内部の`status`を確認してください）
400	無効なrequestボディ、パラメータ、またはプライベート/保留範囲内のターゲットIP
401	APIキーがないか、または無効です
429	rate limitを超過しました
500	内部サーバーエラー
503	サービスが一時的に無効になっているか、容量制限に達しています

次のステップ

認証: APIキーの管理
エラー処理: エラーを適切に処理する
Rate Limits: request制限について理解する
クイックスタート: 30秒で最初のrequestを送信する

最終更新日: 2026年7月1日