Docs › API-Referenz › API-Endpunkt-Referenz

API-Endpunkt-Referenz

Eine Referenz für alle FourA-API-Endpunkte mit Request-Parametern und Response-Formaten.

Basis-URL

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

Authentifizierung

Jeder Request erfordert deinen API-Key im 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"}'

Erstelle und verwalte API-Keys im Dashboard. Keys nutzen das Präfix pk_live_.

Response-Header

Jede Response von /api/* enthält einen Korrelations-Header:

Header Wert Beschreibung
X-Foura-Request-Id UUID Eindeutige ID, die dem Request zugewiesen wird. Wird bei jeder Response zurückgegeben, einschließlich 4xx und 5xx. Logge sie auf deiner Seite.

Dieselbe ID dient als Schlüssel für die Vorschau der Request- und Response-Payload im Activity Log des Dashboards (24 Stunden aufbewahrt, die letzten 200 pro Key). So kannst du den genauen Request später nachschlagen und direkt aus der Activity im Playground erneut abspielen. Gib sie an, wenn du den Support kontaktierst, um den Request sekundenschnell zu finden.

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

Endpunkte

Nutzt du diese Endpunkte über MCP? Der @fouradata/mcp-Server kapselt alle drei Endpunkte als native MCP-Tools (foura_single, foura_proxy, foura_browser) mit denselben Eingabeformaten sowie einem offload_large-Opt-In für tokenfreundliche Verarbeitung großer Responses.

FourA bietet drei Request-Endpunkte, die jeweils für unterschiedliche Szenarien optimiert sind:

Endpunkt Bestens geeignet für
POST /single/ Schnelle HTTP-Requests, statische Seiten, APIs
POST /proxy/ Geschützte Websites mit automatischer Proxy-Rotation
POST /browser/ JavaScript-gerenderte Seiten, SPAs

Ziel-URL-Einschränkungen

Ziele, die auf private, Loopback- oder reservierte IP-Bereiche (RFC 5735, RFC 6598, reservierte IPv6-Blöcke) verweisen, werden mit einem 400-Fehler abgelehnt, bevor der Request FourA verlässt. Nur öffentliche Hostnamen und IPs werden weitergeleitet.

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

Single-Request

POST /api/single/

Sendet einen HTTP-Request mit realistischen, browserähnlichen Übertragungseigenschaften, ohne einen echten Browser zu starten. Dies ist der schnellste Endpunkt.

Request-Body

Parameter Typ Erforderlich Standard Beschreibung
method string Ja - HTTP-Methode: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Ja - Ziel-URL. Verwende {ts} an beliebiger Stelle in der URL, um den aktuellen Zeitstempel für Cache-Busting einzufügen.
headers [string, string][] Nein - Benutzerdefinierte Header als [Name, Wert]-Paare
unblocker boolean Nein false Realistische Browser-Header injizieren (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)
timeout_ms number Nein 15000 Gesamtes Timeout in ms (max. 120000)
connect_timeout_ms number Nein 5000 Verbindungs-Timeout in ms
accept_timeout_ms number Nein 5000 Accept-Timeout in ms (Wartezeit auf Verbindungsannahme)
server_response_timeout_ms number Nein 15000 Server-Response-Timeout in ms (Wartezeit auf das erste Byte)
dns_cache_timeout_sec number Nein 120 DNS-Cache-TTL in Sekunden (max. 240)
followRedirects number Nein deaktiviert Maximale Anzahl zu folgender Weiterleitungen (0-20). Weglassen zum Deaktivieren.
tryJsonData boolean Nein false Response-Body wenn möglich als JSON parsen
returnBuffer boolean Nein false Rohen Buffer statt decodierten String zurückgeben
data any Nein - Request-Body (String oder Objekt, automatisch als JSON serialisiert)
proxy string Nein - Proxy-URL (http, socks4 oder socks5) oder eine von einer vorherigen Response zurückgegebene Proxy-ID
validate object Nein - Validierungsregeln für die Response (siehe unten)

Validierungsregeln

Mit dem validate-Objekt kannst du Bedingungen für Erfolg und Fehlschlag definieren. Wenn eine fail-Bedingung zutrifft, wird der Request als fehlgeschlagen gewertet. Wenn accept-Bedingungen definiert sind, werden nur übereinstimmende Responses als erfolgreich gewertet.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Feld Typ Beschreibung
validate.status.accept number[] Zu akzeptierende HTTP-Statuscodes
validate.status.fail number[] Abzulehnende HTTP-Statuscodes
validate.headers.accept object Header-Key-Value-Paare, die vorhanden sein müssen
validate.headers.fail object Header-Key-Value-Paare, die einen Fehlschlag auslösen
validate.data.accept string[] Strings, die im Response-Body enthalten sein müssen
validate.data.fail string[] Strings im Response-Body, die einen Fehlschlag auslösen

Beispiel

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
}
Feld Typ Beschreibung
status number HTTP-Statuscode des Ziels
headers array Ein Objekt pro Redirect-Hop. Jedes enthält ein result-Feld mit der Statuszeile sowie allen Response-Headern. Header mit mehreren Werten (Set-Cookie, Link, WWW-Authenticate) werden als String-Arrays zurückgegeben.
data string/object Response-Body (JSON, wenn tryJsonData true ist)
total_time number Gesamte Request-Dauer in Sekunden
error string Fehlermeldung, falls der Request fehlgeschlagen ist

Proxy-Request

POST /api/proxy/

Leitet deinen Request über rotierende Proxys mit automatischer Wiederholung bei Fehlschlag weiter.

Request-Body

Parameter Typ Erforderlich Standard Beschreibung
request object Ja - Ein einzelner Request-Body (gleiche Felder wie beim Single-Request oben)
timeout_ms number Nein 45000 Gesamtes Timeout für alle Versuche in ms (max. 120000)
maxTries number Nein 5 Maximale Anzahl an Proxy-Rotationsversuchen (max. 90)
ignoreProxies string[] Nein - Aus der Rotation auszuschließende Proxy-IDs (verwende von vorherigen Responses zurückgegebene IDs)

Beispiel

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
}
Feld Typ Beschreibung
proxy string Codierter Identifikator des verwendeten Proxys. Verwende ihn bei einem Single- oder Browser-Request wieder, indem du ihn im Feld proxy übergibst, oder überspringe ihn beim nächsten Proxy-Request via ignoreProxies.
total number Äußere Gesamtdauer in Sekunden (Float). Umfasst Proxy-Auswahl, Wiederholungsversuche und den erfolgreichen Versuch. total_time betrifft nur den inneren Request; total ist immer >= total_time.
error string Fehlermeldung, falls der Request fehlgeschlagen ist

Alle Response-Felder des Single-Requests sind ebenfalls enthalten.

Browser-Request

POST /api/browser/

Öffnet deine URL in einer Chrome-Browser-Instanz. Die Seite lädt, JavaScript wird ausgeführt und du erhältst das vollständig gerenderte HTML sowie die Cookies (Cookie-Jar).

Request-Body

Parameter Typ Erforderlich Standard Beschreibung
url string Ja - Ziel-URL
headers object Nein - Benutzerdefinierte Header als Key-Value-Paare
cookies array Nein - Zu setzende Cookies: [{name, value, domain?}]
userAgent string Nein - Benutzerdefinierter User-Agent-String
proxy string Nein - Proxy-URL oder eine von einer vorherigen Response zurückgegebene Proxy-ID
timeout_ms number Nein 30000 Timeout für das Laden der Seite in ms (max. 120000)
checkStatus number Nein - Erwarteter HTTP-Status (Request schlägt bei Abweichung fehl)
checkText string Nein - Text, der auf der gerenderten Seite erscheinen muss

Beispiel

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..."
}
Feld Typ Beschreibung
status number HTTP-Statuscode des Ziels
headers object Response-Header
body string or object Vollständig gerenderter Seiteninhalt. HTML-String, wenn der Content-Type HTML ist; Objekt, wenn die Seite JSON zurückgegeben hat und automatisch geparst wurde.
cookies array Vollständige Cookie-Objekte der Seite. Jedes Cookie enthält name, value, domain, path, expires, httpOnly, secure, sameSite und weitere Cookie-Eigenschaften.
userAgent string Verwendeter Browser-User-Agent
error string Fehlermeldung, falls der Request fehlgeschlagen ist

HTTP-Statuscodes

Code Bedeutung
200 Request abgeschlossen (prüfe den inneren status für die Ziel-Response)
400 Ungültiger Request-Body, ungültige Parameter oder Ziel-IP in einem privaten/reservierten Bereich
401 Fehlender oder ungültiger API-Key
429 Rate-Limit überschritten
500 Interner Serverfehler
503 Dienst vorübergehend deaktiviert oder ausgelastet

Nächste Schritte

Aktualisiert: 1. Juli 2026
API-Fehler →