Docs › Référence API › Référence des endpoints API

Référence des endpoints API

Une référence pour tous les endpoints API de FourA avec les paramètres de request et les formats de response.

URL de base

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

Authentification

Chaque request nécessite votre clé API dans le 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"}'

Créez et gérez vos clés API dans le Dashboard. Les clés utilisent le préfixe pk_live_.

Headers de response

Chaque response de /api/* contient un header de corrélation :

Header Valeur Description
X-Foura-Request-Id UUID ID unique attribué à la request. Renvoyé sur chaque response, y compris les 4xx et 5xx. Enregistrez-le de votre côté.

Le même ID sert de clé pour la prévisualisation du payload de la request et de la response dans l'Activity Log du Dashboard (conservé 24 heures, les 200 derniers par clé), vous permettant ainsi de retrouver la request exacte plus tard et de la rejouer depuis Activity directement dans le Playground. Incluez-le lorsque vous contactez le support pour identifier la request en quelques secondes.

$ 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

Vous utilisez ces endpoints via MCP ? Le serveur @fouradata/mcp encapsule les trois endpoints sous forme d'outils MCP natifs (foura_single, foura_proxy, foura_browser) avec les mêmes structures d'entrée, plus une option offload_large pour une gestion des grandes responses adaptée aux tokens.

FourA fournit trois endpoints de request, chacun optimisé pour différents scénarios :

Endpoint Idéal pour
POST /single/ Requests HTTP rapides, pages statiques, API
POST /proxy/ Sites protégés avec rotation automatique de proxy
POST /browser/ Pages générées par JavaScript, SPA

Restrictions sur l'URL cible

Les cibles qui mènent à des plages IP privées, de loopback ou réservées (RFC 5735, RFC 6598, blocs réservés IPv6) sont refusées avec une erreur 400 avant que la request ne quitte FourA. Seuls les noms d'hôte et les IP publics sont transmis.

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

Single Request

POST /api/single/

Envoie une request HTTP avec des caractéristiques réseau réalistes semblables à celles d'un navigateur, sans lancer de véritable navigateur. C'est l'endpoint le plus rapide.

Request Body

Paramètre Type Requis Par défaut Description
method string Oui - Méthode HTTP : GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Oui - URL cible. Utilisez {ts} n'importe où dans l'URL pour insérer le timestamp actuel afin d'éviter le cache.
headers [string, string][] Non - Headers personnalisés sous forme de paires [nom, valeur]
unblocker boolean Non false Injecte des headers de navigateur réalistes (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)
timeout_ms number Non 15000 Timeout global en ms (max : 120000)
connect_timeout_ms number Non 5000 Timeout de connexion en ms
accept_timeout_ms number Non 5000 Timeout d'acceptation en ms (temps d'attente pour l'acceptation de la connexion)
server_response_timeout_ms number Non 15000 Timeout de response du serveur en ms (temps d'attente pour le premier octet)
dns_cache_timeout_sec number Non 120 TTL du cache DNS en secondes (max : 240)
followRedirects number Non disabled Nombre maximal de redirections à suivre (0-20). Omettre pour désactiver.
tryJsonData boolean Non false Analyse le corps de la response en tant que JSON si possible
returnBuffer boolean Non false Renvoie le buffer brut au lieu de la chaîne décodée
data any Non - Corps de la request (chaîne ou objet, sérialisé automatiquement en JSON)
proxy string Non - URL du proxy (http, socks4 ou socks5) ou un ID de proxy renvoyé par une response précédente
validate object Non - Règles de validation de la response (voir ci-dessous)

Règles de validation

L'objet validate vous permet de définir des conditions de réussite et d'échec. Si une condition fail correspond, la request est considérée comme ayant échoué. Si des conditions accept sont définies, seules les responses correspondantes sont considérées comme réussies.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Champ Type Description
validate.status.accept number[] Codes d'état HTTP à accepter
validate.status.fail number[] Codes d'état HTTP à rejeter
validate.headers.accept object Paires clé-valeur de header qui doivent être présentes
validate.headers.fail object Paires clé-valeur de header qui déclenchent un échec
validate.data.accept string[] Chaînes de caractères qui doivent apparaître dans le corps de la response
validate.data.fail string[] Chaînes de caractères dans le corps de la response qui déclenchent un échec

Exemple

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
}
Champ Type Description
status number Code d'état HTTP de la cible
headers array Un objet par saut de redirection. Chacun possède un champ result avec la ligne d'état ainsi que chaque header de response. Les headers multi-valeurs (Set-Cookie, Link, WWW-Authenticate) sont renvoyés sous forme de tableaux de chaînes.
data string/object Corps de la response (JSON si tryJsonData est true)
total_time number Temps total de la request en secondes
error string Message d'erreur si la request a échoué

Proxy Request

POST /api/proxy/

Achemine votre request via des proxies tournants avec tentative automatique en cas d'échec.

Request Body

Paramètre Type Requis Par défaut Description
request object Oui - Un corps de request unique (mêmes champs que pour Single Request ci-dessus)
timeout_ms number Non 45000 Timeout global pour toutes les tentatives en ms (max : 120000)
maxTries number Non 5 Nombre maximal de tentatives de rotation de proxy (max : 90)
ignoreProxies string[] Non - ID de proxy à exclure de la rotation (utilisez les ID renvoyés par les responses précédentes)

Exemple

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
}
Champ Type Description
proxy string Identifiant encodé du proxy utilisé. Réutilisez-le sur une request Single ou Browser en le transmettant dans le champ proxy, ou ignorez-le lors de la prochaine request Proxy via ignoreProxies.
total number Durée totale réelle en secondes (float). Comprend la sélection du proxy, les tentatives et l'essai réussi. total_time concerne uniquement la request interne ; total est toujours >= total_time.
error string Message d'erreur si la request a échoué

Tous les champs de response de Single Request sont également inclus.

Browser Request

POST /api/browser/

Ouvre votre URL dans une instance de navigateur Chrome. La page se charge, le JavaScript s'exécute et vous obtenez l'HTML entièrement généré ainsi que le cookie jar.

Request Body

Paramètre Type Requis Par défaut Description
url string Oui - URL cible
headers object Non - Headers personnalisés sous forme de paires clé-valeur
cookies array Non - Cookies à définir : [{name, value, domain?}]
userAgent string Non - Chaîne User-Agent personnalisée
proxy string Non - URL du proxy ou un ID de proxy renvoyé par une response précédente
timeout_ms number Non 30000 Timeout de chargement de la page en ms (max : 120000)
checkStatus number Non - Code d'état HTTP attendu (la request échoue s'il est différent)
checkText string Non - Texte qui doit apparaître dans la page générée

Exemple

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..."
}
Champ Type Description
status number Code d'état HTTP de la cible
headers object Headers de response
body string or object Contenu de la page entièrement généré. Chaîne HTML lorsque le content-type est HTML ; objet lorsque la page a renvoyé du JSON et a été analysée automatiquement.
cookies array Objets cookie complets de la page. Chaque cookie comprend name, value, domain, path, expires, httpOnly, secure, sameSite et d'autres propriétés de cookie.
userAgent string User-Agent du navigateur utilisé
error string Message d'erreur si la request a échoué

Codes d'état HTTP

Code Signification
200 Request terminée (vérifiez le status interne pour la response de la cible)
400 Corps de request, paramètres ou IP cible invalides dans une plage privée/réservée
401 Clé API manquante ou invalide
429 Rate limit dépassée
500 Erreur interne du serveur
503 Service temporairement désactivé ou à pleine capacité

Étapes suivantes

Mis à jour : 1 juillet 2026
Erreurs API →