문서 › API 레퍼런스 › API Endpoint 레퍼런스

API Endpoint 레퍼런스

요청 parameter와 response 형식을 포함한 모든 FourA API endpoint에 대한 레퍼런스입니다.

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입니다. 4xx 및 5xx를 포함한 모든 response에서 반환됩니다. 귀사 시스템에 로그로 기록해 두세요.

동일한 ID가 Dashboard의 Activity Log(24시간 동안 보관, key당 최근 200개)에 있는 request 및 response payload 미리보기의 key 역할을 하므로, 나중에 정확한 request를 찾아 Activity에서 Playground로 바로 재전송(replay)할 수 있습니다. 고객 지원에 문의할 때 이 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 서버는 동일한 입력 형태와 token 친화적인 대용량 response 처리를 위한 offload_large 옵트인을 지원하며, 세 가지 endpoint를 모두 네이티브 MCP 도구(foura_single, foura_proxy, foura_browser)로 래핑합니다.

FourA는 각각 다른 시나리오에 최적화된 세 가지 request endpoint를 제공합니다:

Endpoint 최적의 용도
POST /single/ 빠른 HTTP request, 정적 페이지, API
POST /proxy/ 자동 proxy 회전(rotation)이 적용된 보호된 사이트
POST /browser/ JavaScript로 렌더링되는 페이지, SPA

Target URL Restrictions

사설, 루프백 또는 예약된 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

Parameter Type Required Default 설명
method string Yes - HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Yes - 대상 URL. 캐시 우회(cache-busting)를 위해 URL의 아무 곳에나 {ts}를 사용하여 현재 타임스탬프를 삽입할 수 있습니다.
headers [string, string][] No - [name, value] 쌍 형태의 커스텀 header
unblocker boolean No false 실제 브라우저와 유사한 header 주입 (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)
timeout_ms number No 15000 전체 timeout (밀리초 단위, 최대: 120000)
connect_timeout_ms number No 5000 연결 timeout (밀리초 단위)
accept_timeout_ms number No 5000 수락 timeout (밀리초 단위, 연결 수락을 대기하는 시간)
server_response_timeout_ms number No 15000 서버 response timeout (밀리초 단위, 첫 바이트를 대기하는 시간)
dns_cache_timeout_sec number No 120 DNS 캐시 TTL (초 단위, 최대: 240)
followRedirects number No disabled 추적할 최대 redirect 횟수 (0-20). 비활성화하려면 생략하십시오.
tryJsonData boolean No false 가능한 경우 response body를 JSON으로 파싱
returnBuffer boolean No false 디코딩된 문자열 대신 원시 버퍼 반환
data any No - Request body (문자열 또는 객체, JSON으로 자동 직렬화됨)
proxy string No - Proxy URL (http, socks4 또는 socks5) 또는 이전 response에서 반환된 proxy ID
validate object No - 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 status 코드
validate.status.fail number[] 거부할 HTTP status 코드
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 status 코드
headers array redirect 홉당 하나의 객체입니다. 각 객체는 status 라인과 모든 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/

실패 시 자동 재시도를 지원하며, 회전(rotating) proxy를 통해 request를 라우팅합니다.

Request Body

Parameter Type Required Default 설명
request object Yes - 단일 request body (위의 Single Request와 동일한 필드)
timeout_ms number No 45000 모든 시도에 대한 전체 timeout (밀리초 단위, 최대: 120000)
maxTries number No 5 최대 proxy 회전 시도 횟수 (최대: 90)
ignoreProxies string[] No - 회전에서 제외할 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 jar를 받게 됩니다.

Request Body

Parameter Type Required Default 설명
url string Yes - 대상 URL
headers object No - 키-값 쌍 형태의 커스텀 header
cookies array No - 설정할 cookie 목록: [{name, value, domain?}]
userAgent string No - 커스텀 User-Agent 문자열
proxy string No - Proxy URL 또는 이전 response에서 반환된 proxy ID
timeout_ms number No 30000 페이지 로드 timeout (밀리초 단위, 최대: 120000)
checkStatus number No - 예상되는 HTTP status (다를 경우 request 실패 처리)
checkText string No - 렌더링된 페이지에 반드시 포함되어야 하는 텍스트

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 status 코드
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 완료 (대상 response는 내부 status 확인)
400 잘못된 request body, parameter 또는 사설/예약된 대역의 대상 IP
401 API key가 누락되었거나 유효하지 않음
429 Rate limit 초과
500 내부 서버 에러
503 서비스가 일시적으로 비활성화되었거나 용량 초과

Next Steps

최근 업데이트: 2026년 7월 1일
API 오류 →