Dokumentacja › Referencja API › Dokumentacja endpointów API

Dokumentacja endpointów API

Dokumentacja wszystkich endpointów API FourA wraz z parametrami żądań i formatami odpowiedzi.

Base URL

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

Uwierzytelnianie

Każde żądanie wymaga podania klucza API w nagłówku 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"}'

Twórz klucze API i zarządzaj nimi w Dashboardzie. Klucze używają prefiksu pk_live_.

Nagłówki odpowiedzi

Każda odpowiedź z /api/* zawiera jeden nagłówek korelacyjny:

Nagłówek Wartość Opis
X-Foura-Request-Id UUID Unikalny identyfikator przypisany do żądania. Zwracany w każdej odpowiedzi, w tym 4xx i 5xx. Zapisuj go w logach po swojej stronie.

Ten sam identyfikator służy do wyszukiwania podglądu żądania i odpowiedzi w sekcji Activity Log w Dashboardzie (przechowywane przez 24 godziny, do 200 ostatnich na klucz). Dzięki temu możesz później sprawdzić dokładne żądanie i odtworzyć je bezpośrednio z poziomu Activity w Playgroundzie. Podaj go przy kontakcie ze wsparciem technicznym, a pozwoli to zlokalizować żądanie w kilka sekund.

$ 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
...

Endpointy

Korzystasz z tych endpointów przez MCP? Serwer @fouradata/mcp opakowuje wszystkie trzy endpointy jako natywne narzędzia MCP (foura_single, foura_proxy, foura_browser) z tymi samymi strukturami wejściowymi oraz opcjonalnym parametrem offload_large do obsługi dużych odpowiedzi w sposób przyjazny dla tokenów.

FourA udostępnia trzy endpointy dla żądań, z których każdy jest zoptymalizowany pod kątem innych scenariuszy:

Endpoint Najlepszy do
POST /single/ Szybkie żądania HTTP, strony statyczne, interfejsy API
POST /proxy/ Zabezpieczone strony z automatyczną rotacją proxy
POST /browser/ Strony renderowane przez JavaScript, aplikacje SPA

Ograniczenia docelowych adresów URL

Żądania do adresów docelowych, które wskazują na prywatne, pętli zwrotnej (loopback) lub zarezerwowane zakresy IP (RFC 5735, RFC 6598, bloki zarezerwowane IPv6), są odrzucane z błędem 400, zanim żądanie opuści FourA. Przekazywane są wyłącznie publiczne nazwy hostów i adresy IP.

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

Single Request

POST /api/single/

Wysyła żądanie HTTP o charakterystyce sieciowej przypominającej prawdziwą przeglądarkę, bez uruchamiania rzeczywistego środowiska przeglądarki. To najszybszy endpoint.

Request Body

Parametr Typ Wymagany Domyślnie Opis
method string Tak - Metoda HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Tak - Docelowy URL. Użyj {ts} w dowolnym miejscu adresu URL, aby wstawić aktualny znacznik czasu w celu ominięcia pamięci podręcznej (cache-busting).
headers [string, string][] Nie - Niestandardowe nagłówki jako pary [nazwa, wartość]
unblocker boolean Nie false Wstrzykiwanie realistycznych nagłówków przeglądarki (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)
timeout_ms number Nie 15000 Całkowity limit czasu w ms (maks.: 120000)
connect_timeout_ms number Nie 5000 Limit czasu połączenia w ms
accept_timeout_ms number Nie 5000 Limit czasu akceptacji połączenia w ms (czas oczekiwania na zaakceptowanie połączenia)
server_response_timeout_ms number Nie 15000 Limit czasu na odpowiedź serwera w ms (czas oczekiwania na pierwszy bajt)
dns_cache_timeout_sec number Nie 120 TTL pamięci podręcznej DNS w sekundach (maks.: 240)
followRedirects number Nie disabled Maksymalna liczba przekierowań do wykonania (0-20). Pomiń, aby wyłączyć.
tryJsonData boolean Nie false Próba sparsowania treści odpowiedzi jako JSON, jeśli to możliwe
returnBuffer boolean Nie false Zwrócenie surowego bufora zamiast zdekodowanego ciągu znaków
data any Nie - Treść żądania (ciąg znaków lub obiekt, automatycznie serializowany do JSON)
proxy string Nie - URL proxy (http, socks4 lub socks5) lub identyfikator proxy zwrócony we wcześniejszej odpowiedzi
validate object Nie - Reguły walidacji odpowiedzi (patrz poniżej)

Reguły walidacji

Obiekt validate pozwala zdefiniować warunki sukcesu i niepowodzenia. Jeśli warunek fail zostanie spełniony, żądanie zostanie uznane za nieudane. Jeśli ustawiono warunki accept, tylko pasujące odpowiedzi zostaną uznane za udane.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Pole Typ Opis
validate.status.accept number[] Kody statusu HTTP do zaakceptowania
validate.status.fail number[] Kody statusu HTTP do odrzucenia
validate.headers.accept object Pary klucz-wartość nagłówków, które muszą być obecne
validate.headers.fail object Pary klucz-wartość nagłówków, które powodują niepowodzenie
validate.data.accept string[] Ciągi znaków, które muszą pojawić się w treści odpowiedzi
validate.data.fail string[] Ciągi znaków w treści odpowiedzi, które powodują niepowodzenie

Przykład

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

Odpowiedź:

{
  "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
}
Pole Typ Opis
status number Kod statusu HTTP z docelowego serwera
headers array Jeden obiekt na każdy krok przekierowania (hop). Każdy zawiera pole result z linią statusu oraz wszystkimi nagłówkami odpowiedzi. Nagłówki o wielu wartościach (Set-Cookie, Link, WWW-Authenticate) są zwracane jako tablice ciągów znaków.
data string/object Treść odpowiedzi (JSON, jeśli tryJsonData ma wartość true)
total_time number Całkowity czas żądania w sekundach
error string Komunikat o błędzie, jeśli żądanie się nie powiodło

Proxy Request

POST /api/proxy/

Kieruje Twoje żądanie przez rotacyjne serwery proxy z automatyczną próbą ponowienia w przypadku niepowodzenia.

Request Body

Parametr Typ Wymagany Domyślnie Opis
request object Tak - Treść pojedynczego żądania (te same pola, co w Single Request powyżej)
timeout_ms number Nie 45000 Całkowity limit czasu dla wszystkich prób w ms (maks.: 120000)
maxTries number Nie 5 Maksymalna liczba prób rotacji proxy (maks.: 90)
ignoreProxies string[] Nie - Identyfikatory proxy do wykluczenia z rotacji (użyj identyfikatorów zwróconych we wcześniejszych odpowiedziach)

Przykład

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

Odpowiedź:

{
  "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
}
Pole Typ Opis
proxy string Zakodowany identyfikator użytego proxy. Możesz go użyć ponownie w żądaniu Single lub Browser, przekazując go w polu proxy, lub pominąć w kolejnym żądaniu Proxy za pomocą ignoreProxies.
total number Całkowity czas trwania mierzony zegarem ściennym w sekundach (liczba zmiennoprzecinkowa). Obejmuje wybór proxy, ponowne próby i udane żądanie. total_time dotyczy wyłącznie wewnętrznego żądania; total jest zawsze >= total_time.
error string Komunikat o błędzie, jeśli żądanie się nie powiodło

Uwzględnione są również wszystkie pola odpowiedzi z Single Request.

Browser Request

POST /api/browser/

Otwiera docelowy URL w instancji przeglądarki Chrome. Strona się ładuje, skrypty JavaScript są wykonywane, a Ty otrzymujesz w pełni wyrenderowany kod HTML oraz pliki cookie.

Request Body

Parametr Typ Wymagany Domyślnie Opis
url string Tak - Docelowy URL
headers object Nie - Niestandardowe nagłówki jako pary klucz-wartość
cookies array Nie - Pliki cookie do ustawienia: [{name, value, domain?}]
userAgent string Nie - Niestandardowy ciąg znaków User-Agent
proxy string Nie - URL proxy lub identyfikator proxy zwrócony we wcześniejszej odpowiedzi
timeout_ms number Nie 30000 Limit czasu ładowania strony w ms (maks.: 120000)
checkStatus number Nie - Oczekiwany status HTTP (żądanie zakończy się niepowodzeniem, jeśli będzie inny)
checkText string Nie - Tekst, który musi pojawić się na wyrenderowanej stronie

Przykład

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

Odpowiedź:

{
  "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..."
}
Pole Typ Opis
status number Kod statusu HTTP z docelowego serwera
headers object Nagłówki odpowiedzi
body string or object W pełni wyrenderowana zawartość strony. Ciąg znaków HTML, gdy content-type to HTML; obiekt, gdy strona zwróciła JSON i został on automatycznie sparsowany.
cookies array Pełne obiekty plików cookie ze strony. Każdy plik cookie zawiera name, value, domain, path, expires, httpOnly, secure, sameSite oraz inne właściwości plików cookie.
userAgent string Użyty User-Agent przeglądarki
error string Komunikat o błędzie, jeśli żądanie się nie powiodło

Kody statusu HTTP

Kod Znaczenie
200 Żądanie zakończone (sprawdź wewnętrzny status dla odpowiedzi z docelowego serwera)
400 Nieprawidłowa treść żądania, parametry lub docelowy adres IP w prywatnym/zarezerwowanym zakresie
401 Brakujący lub nieprawidłowy klucz API
429 Przekroczono rate limit
500 Wewnętrzny błąd serwera
503 Usługa tymczasowo wyłączona lub przeciążona

Kolejne kroki

Aktualizacja: 1 lipca 2026
Błędy API →