Docs › API Reference › API Endpoints Reference

API Endpoints Reference

A reference for all FourA API endpoints with request parameters and response formats.

Base URL

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

Authentication

Every request requires your API key in the X-API-Key header:

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

Create and manage API keys in the Dashboard. Keys use the pk_live_ prefix.

Endpoints

Using these endpoints via MCP? The @fouradata/mcp server wraps all three endpoints as native MCP tools (foura_single, foura_proxy, foura_browser) with the same input shapes plus an offload_large opt-in for token-friendly large-response handling.

FourA provides three request endpoints, each optimized for different scenarios:

Endpoint Best for
POST /single/ Fast HTTP requests, static pages, APIs
POST /proxy/ Protected sites with automatic proxy rotation
POST /browser/ JavaScript-rendered pages, SPAs

Target URL Restrictions

Targets that resolve to private, loopback, or reserved IP ranges (RFC 5735, RFC 6598, IPv6 reserved blocks) are refused with a 400 before the request leaves FourA. Only public hostnames and IPs are forwarded.

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

Single Request

POST /api/single/

Sends an HTTP request with realistic browser-like wire characteristics, without spinning up a real browser. This is the fastest endpoint.

Request Body

Parameter Type Required Default Description
method string Yes - HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Yes - Target URL. Use {ts} anywhere in the URL to insert the current timestamp for cache-busting.
headers [string, string][] No - Custom headers as [name, value] pairs
unblocker boolean No false Inject realistic browser headers (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)
timeout_ms number No 15000 Overall timeout in ms (max: 120000)
connect_timeout_ms number No 5000 Connection timeout in ms
accept_timeout_ms number No 5000 Accept timeout in ms (time to wait for connection acceptance)
server_response_timeout_ms number No 15000 Server response timeout in ms (time to wait for first byte)
dns_cache_timeout_sec number No 120 DNS cache TTL in seconds (max: 240)
followRedirects number No disabled Max redirects to follow (0-20). Omit to disable.
tryJsonData boolean No false Parse response body as JSON if possible
returnBuffer boolean No false Return raw buffer instead of decoded string
data any No - Request body (string or object, auto-serialized to JSON)
proxy string No - Proxy URL (http, socks4, or socks5) or a proxy ID returned by a previous response
validate object No - Response validation rules (see below)

Validation Rules

The validate object lets you define conditions for success and failure. If a fail condition matches, the request is treated as failed. If accept conditions are set, only matching responses are treated as successful.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Field Type Description
validate.status.accept number[] HTTP status codes to accept
validate.status.fail number[] HTTP status codes to reject
validate.headers.accept object Header key-value pairs that must be present
validate.headers.fail object Header key-value pairs that trigger failure
validate.data.accept string[] Strings that must appear in the response body
validate.data.fail string[] Strings in the response body that trigger failure

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 Description
status number HTTP status code from the target
headers array One object per redirect hop. Each has a result field with the status line plus every response header. Multi-value headers (Set-Cookie, Link, WWW-Authenticate) come back as arrays of strings.
data string/object Response body (JSON if tryJsonData is true)
total_time number Total request time in seconds
error string Error message if the request failed

Proxy Request

POST /api/proxy/

Routes your request through rotating proxies with automatic retry on failure.

Request Body

Parameter Type Required Default Description
request object Yes - A single request body (same fields as Single Request above)
timeout_ms number No 45000 Overall timeout for all attempts in ms (max: 120000)
maxTries number No 5 Maximum proxy rotation attempts (max: 90)
ignoreProxies string[] No - Proxy IDs to exclude from rotation (use IDs returned by previous responses)

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 Description
proxy string Encoded identifier of the proxy used. Reuse it on a Single or Browser request by passing it as the proxy field, or skip it on the next Proxy request via ignoreProxies.
total number Outer wall-clock duration in seconds (float). Includes proxy selection, retries, and the successful attempt. total_time is the inner request only; total is always >= total_time.
error string Error message if the request failed

All Single Request response fields are also included.

Browser Request

POST /api/browser/

Opens your URL in a Chrome browser instance. The page loads, JavaScript executes, and you get the fully rendered HTML plus the cookie jar.

Request Body

Parameter Type Required Default Description
url string Yes - Target URL
headers object No - Custom headers as key-value pairs
cookies array No - Cookies to set: [{name, value, domain?}]
userAgent string No - Custom User-Agent string
proxy string No - Proxy URL or a proxy ID returned by a previous response
timeout_ms number No 30000 Page load timeout in ms (max: 120000)
checkStatus number No - Expected HTTP status (request fails if different)
checkText string No - Text that must appear in the rendered page

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 Description
status number HTTP status code from the target
headers object Response headers
body string or object Fully rendered page content. String HTML when content-type is HTML; object when the page returned JSON and was auto-parsed.
cookies array Full cookie objects from the page. Each cookie includes name, value, domain, path, expires, httpOnly, secure, sameSite, and other cookie properties.
userAgent string Browser User-Agent used
error string Error message if the request failed

HTTP Status Codes

Code Meaning
200 Request completed (check inner status for target response)
400 Invalid request body, parameters, or target IP in a private/reserved range
401 Missing or invalid API key
429 Rate limit exceeded
500 Internal server error
503 Service temporarily disabled or at capacity

Next Steps

Last updated: May 20, 2026
API Errors →