Tài liệu › Tham chiếu API › Tham chiếu API Endpoint

Tham chiếu API Endpoint

Tài liệu tham khảo cho tất cả các API endpoint của FourA cùng với các tham số request và định dạng response.

Base URL

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

Xác thực

Mỗi request đều yêu cầu API key của bạn trong header X-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"}'

Tạo và quản lý các API key trong Dashboard. Các key sử dụng tiền tố pk_live_.

Response Header

Mỗi response từ /api/* đều mang một correlation header:

Header Giá trị Mô tả
X-Foura-Request-Id UUID ID duy nhất được gán cho request. Được trả về trên mọi response, bao gồm cả 4xx và 5xx. Hãy ghi log giá trị này ở phía bạn.

ID này cũng chính là khóa để xem trước payload của request và response trong Activity Log của Dashboard (được lưu trữ trong 24 giờ, tối đa 200 mục gần nhất cho mỗi key), giúp bạn có thể tra cứu chính xác request sau đó và phát lại (replay) trực tiếp từ Activity vào Playground. Hãy cung cấp ID này khi liên hệ hỗ trợ để chúng tôi có thể xác định chính xác request của bạn trong vài giây.

$ 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

Sử dụng các endpoint này qua MCP? @fouradata/mcp server đóng gói cả ba endpoint dưới dạng các công cụ MCP gốc (foura_single, foura_proxy, foura_browser) với cùng cấu trúc đầu vào, đi kèm tùy chọn offload_large để xử lý các response lớn một cách tối ưu cho token.

FourA cung cấp ba request endpoint, mỗi endpoint được tối ưu hóa cho các tình huống khác nhau:

Endpoint Phù hợp nhất cho
POST /single/ Các HTTP request nhanh, trang tĩnh, API
POST /proxy/ Các trang web được bảo vệ với tính năng tự động xoay vòng proxy
POST /browser/ Các trang web kết xuất bằng JavaScript, SPA

Giới hạn URL đích

Các đích đến phân giải ra dải IP riêng tư (private), loopback hoặc dải IP được bảo lưu (RFC 5735, RFC 6598, các khối IPv6 được bảo lưu) sẽ bị từ chối với mã lỗi 400 trước khi request rời khỏi FourA. Chỉ các hostname và IP công khai mới được chuyển tiếp.

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

Single Request

POST /api/single/

Gửi một HTTP request với các đặc tính truyền tải thực tế giống như trình duyệt mà không cần khởi chạy một trình duyệt thực sự. Đây là endpoint nhanh nhất.

Request Body

Tham số Kiểu dữ liệu Bắt buộc Mặc định Mô tả
method string Có - Phương thức HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Có - URL đích. Sử dụng {ts} ở bất kỳ đâu trong URL để chèn timestamp hiện tại nhằm tránh cache (cache-busting).
headers [string, string][] Không - Các header tùy chỉnh dưới dạng các cặp [tên, giá trị]
unblocker boolean Không false Chèn các header trình duyệt thực tế (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)
timeout_ms number Không 15000 Thời gian chờ (timeout) tổng thể tính bằng ms (tối đa: 120000)
connect_timeout_ms number Không 5000 Thời gian chờ kết nối tính bằng ms
accept_timeout_ms number Không 5000 Thời gian chờ chấp nhận kết nối tính bằng ms (thời gian chờ kết nối được chấp nhận)
server_response_timeout_ms number Không 15000 Thời gian chờ phản hồi từ máy chủ tính bằng ms (thời gian chờ byte đầu tiên)
dns_cache_timeout_sec number Không 120 TTL của cache DNS tính bằng giây (tối đa: 240)
followRedirects number Không disabled Số lượng redirect tối đa cần theo dõi (0-20). Bỏ qua để tắt.
tryJsonData boolean Không false Phân tích cú pháp (parse) response body thành JSON nếu có thể
returnBuffer boolean Không false Trả về buffer thô thay vì chuỗi đã được giải mã
data any Không - Request body (chuỗi hoặc đối tượng, tự động tuần tự hóa thành JSON)
proxy string Không - URL proxy (http, socks4, hoặc socks5) hoặc proxy ID được trả về từ một response trước đó
validate object Không - Các quy tắc xác thực response (xem bên dưới)

Quy tắc xác thực

Đối tượng validate cho phép bạn định nghĩa các điều kiện thành công và thất bại. Nếu một điều kiện fail khớp, request sẽ được coi là thất bại. Nếu các điều kiện accept được thiết lập, chỉ các response khớp mới được coi là thành công.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Trường Kiểu dữ liệu Mô tả
validate.status.accept number[] Các mã HTTP status được chấp nhận
validate.status.fail number[] Các mã HTTP status bị từ chối
validate.headers.accept object Các cặp key-value của header bắt buộc phải có
validate.headers.fail object Các cặp key-value của header kích hoạt lỗi thất bại
validate.data.accept string[] Các chuỗi bắt buộc phải xuất hiện trong response body
validate.data.fail string[] Các chuỗi trong response body kích hoạt lỗi thất bại

Ví dụ

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
}
Trường Kiểu dữ liệu Mô tả
status number Mã HTTP status từ đích đến
headers array Một đối tượng cho mỗi bước nhảy (hop) redirect. Mỗi đối tượng có một trường result chứa dòng trạng thái cùng với mọi response header. Các header có nhiều giá trị (Set-Cookie, Link, WWW-Authenticate) sẽ được trả về dưới dạng mảng các chuỗi.
data string/object Response body (JSON nếu tryJsonData là true)
total_time number Tổng thời gian request tính bằng giây
error string Thông báo lỗi nếu request thất bại

Proxy Request

POST /api/proxy/

Định tuyến request của bạn qua các proxy xoay vòng với tính năng tự động thử lại khi thất bại.

Request Body

Tham số Kiểu dữ liệu Bắt buộc Mặc định Mô tả
request object Có - Một request body đơn lẻ (các trường giống như Single Request ở trên)
timeout_ms number Không 45000 Thời gian chờ tổng thể cho tất cả các lần thử tính bằng ms (tối đa: 120000)
maxTries number Không 5 Số lần thử xoay vòng proxy tối đa (tối đa: 90)
ignoreProxies string[] Không - Các proxy ID cần loại trừ khỏi vòng xoay (sử dụng các ID được trả về bởi các response trước đó)

Ví dụ

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
}
Trường Kiểu dữ liệu Mô tả
proxy string Mã định danh đã mã hóa của proxy được sử dụng. Tái sử dụng nó trên một Single hoặc Browser request bằng cách truyền nó vào trường proxy, hoặc bỏ qua nó trong Proxy request tiếp theo thông qua ignoreProxies.
total number Thời gian thực tế bên ngoài tính bằng giây (số thực). Bao gồm việc lựa chọn proxy, các lần thử lại và lần thử thành công. total_time chỉ là thời gian của request nội bộ; total luôn luôn >= total_time.
error string Thông báo lỗi nếu request thất bại

Tất cả các trường response của Single Request cũng được bao gồm.

Browser Request

POST /api/browser/

Mở URL của bạn trong một phiên bản trình duyệt Chrome. Trang sẽ tải, JavaScript được thực thi và bạn sẽ nhận được HTML được kết xuất đầy đủ cùng với danh sách cookie.

Request Body

Tham số Kiểu dữ liệu Bắt buộc Mặc định Mô tả
url string Có - URL đích
headers object Không - Các header tùy chỉnh dưới dạng các cặp key-value
cookies array Không - Các cookie cần thiết lập: [{name, value, domain?}]
userAgent string Không - Chuỗi User-Agent tùy chỉnh
proxy string Không - URL proxy hoặc proxy ID được trả về từ một response trước đó
timeout_ms number Không 30000 Thời gian chờ tải trang tính bằng ms (tối đa: 120000)
checkStatus number Không - Mã HTTP status mong đợi (request sẽ thất bại nếu kết quả khác đi)
checkText string Không - Văn bản bắt buộc phải xuất hiện trong trang đã kết xuất

Ví dụ

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..."
}
Trường Kiểu dữ liệu Mô tả
status number Mã HTTP status từ đích đến
headers object Các response header
body string hoặc object Nội dung trang được kết xuất đầy đủ. Là chuỗi HTML khi content-type là HTML; là đối tượng khi trang trả về JSON và được tự động phân tích cú pháp.
cookies array Các đối tượng cookie đầy đủ từ trang. Mỗi cookie bao gồm name, value, domain, path, expires, httpOnly, secure, sameSite và các thuộc tính cookie khác.
userAgent string User-Agent trình duyệt đã sử dụng
error string Thông báo lỗi nếu request thất bại

Mã HTTP Status

Mã Ý nghĩa
200 Request hoàn thành (kiểm tra status nội bộ để biết phản hồi từ đích đến)
400 Request body, tham số không hợp lệ, hoặc IP đích nằm trong dải riêng tư/bảo lưu
401 Thiếu hoặc API key không hợp lệ
429 Vượt quá giới hạn rate limit
500 Lỗi máy chủ nội bộ
503 Dịch vụ tạm thời bị tắt hoặc quá tải

Các bước tiếp theo

Cập nhật: 1 tháng 7, 2026
Lỗi API →