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 de l'API FourA avec les paramètres de requête et les formats de réponse.

URL de base

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

Authentification

Chaque requête nécessite votre clé API dans l'en-tête 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 Tableau de bord. Les clés utilisent le préfixe pk_live_.

En-têtes de réponse

Chaque réponse de /api/* contient deux en-têtes de corrélation :

En-tête Valeur Description
X-FourA-Request-Id UUID ID unique attribué à la requête. Renvoyé sur chaque réponse, y compris 4xx et 5xx. Consignez-le de votre côté.
X-FourA-Credits entier Crédits dépensés pour cette requête. Renvoyé en cas de succès comme en cas d'échec (le travail a été effectué dans les deux cas). Consultez la section Résultats des requêtes pour savoir quels résultats sont facturables.

Ce même ID de requête sert de clé pour l'aperçu du payload de la requête et de la réponse dans le Journal d'activité du Tableau de bord (conservé 24 heures, limité aux 200 dernières par clé), afin que vous puissiez rechercher la requête exacte ultérieurement et la rejouer depuis l'Activité directement dans le Playground. Incluez-le lorsque vous contactez l'assistance, il permet de localiser la requête 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
x-foura-credits: 2
...

Consultez Response Headers pour la liste complète et des conseils d'utilisation.

Endpoints

Vous utilisez ces endpoints via MCP ? Le @fouradata/mcp server enveloppe les quatre endpoints comme des outils MCP natifs (foura_auto, foura_single, foura_proxy, foura_browser) avec les mêmes formats d'entrée, plus une option offload_large pour une gestion des réponses volumineuses adaptée aux tokens.

FourA fournit quatre endpoints de request, chacun optimisé pour un scénario différent :

Endpoint Idéal pour
POST /auto/ Smart fetch. Vous passez une URL, FourA choisit le chemin le moins cher qui fonctionne (direct, proxy avec rotation, ou navigateur) et mémorise ce qui fonctionne par hôte.
POST /single/ Requests HTTP rapides, pages statiques, APIs
POST /proxy/ Sites protégés avec rotation automatique de proxy, ciblage géographique optionnel visible par la cible
POST /browser/ Pages rendues en JavaScript, SPAs
GET /profiles Le catalogue de profils de navigateur pour single et proxy. Public, sans clé API.

Pour une présentation détaillée sur le choix à effectuer, consultez Choosing the Right Endpoint et le Smart Fetch guide.

Restrictions sur les URL cibles

Les cibles qui se résolvent vers des plages d'adresses IP privées, de bouclage 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ôtes et adresses IP publics sont transférés.

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

Smart Fetch (Auto)

POST /api/auto/

Vous passez une URL et des règles validate facultatives. FourA parcourt une échelle tenant compte des coûts (sondage direct peu coûteux, proxy rotatif, navigateur complet) et s'arrête au premier échelon qui renvoie une réponse que vos règles acceptent. Lors d'appels répétés vers le même hôte, une session chaude est rejouée à la place, de sorte que le deuxième essai est peu coûteux.

Vous ne configurez pas les tentatives, les tailles de pool ou le nombre de proxy. FourA les apprend par hôte.

Corps de la requête

Paramètre Type Requis Par défaut Description
url string Oui - URL cible
method string Non "GET" Méthode HTTP
headers [string, string][] Non - En-têtes personnalisés sous forme de paires [nom, valeur]
data any Non - Corps de la requête pour les requêtes non-GET
validate object Non - Critères de réussite, même structure que validate de Single Request (voir ci-dessous). Indiquez à auto à quoi ressemble une page réelle afin qu'il puisse distinguer le contenu d'une page de défi.
returnSession boolean Non true Incluez la session gagnante (proxy, cookies, userAgent) dans la réponse afin de pouvoir la rejouer via /api/single/ ou /api/browser/.
forceProxy boolean Non true Acheminez toujours via un proxy rotatif. Définissez false pour autoriser le chemin direct moins coûteux lorsque la cible le permet (certaines défenses sont plus strictes sur le trafic proxy).
timeout_ms integer Non 120000 Budget temps total pour l'appel complet, en millisecondes. Toutes les sous-tentatives s'exécutent dans ce budget. Min 5000, max 180000.
ignoreProxies string[] Non - ID de proxy à éviter à chaque sous-tentative. Utilisez les ID renvoyés par les réponses /api/auto/ ou /api/proxy/ précédentes.
followRedirects integer Non 5 Nombre maximum de redirections à suivre sur les échelons peu coûteux. 0 pour désactiver. Max 20.

Réponse

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}
Champ Type Description
status number Statut HTTP de la cible.
data string ou object Corps de la réponse.
headers array ou object En-têtes de la réponse cible. Les échelons (rungs) single et proxy retournent un tableau d'objets d'en-tête par saut, les échelons browser retournent un objet plat.
meta.rung string Quel échelon de l'échelle a fourni la réponse. L'un des choix suivants : probe (requête directe peu coûteuse), proxy (proxy rotatif), browser (rendu complet par navigateur), cache (session chaude rejouée), ou fail (aucun échelon n'a produit de réponse acceptée).
meta.solved boolean Indique si un défi de bot a été résolu pendant cet appel.
meta.attempts number Sous-tentatives effectuées avant le succès.
meta.credits number Crédits totaux dépensés pour cet appel. Correspond à X-FourA-Credits.
session.proxy string ID encodé du proxy qui a fourni la réponse. Réutilisez-le sur une requête Single ou Browser. Présent lorsque returnSession est true.
session.cookies array Cookies de la tentative gagnante. Présent lorsque returnSession est true.
session.userAgent string User-Agent utilisé lors de la tentative gagnante. Présent lorsque returnSession est true.
error string Message d'erreur si l'appel a échoué.

Exemple

curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'

Notes

  • Auto est un coordinateur. Il appelle Single, Proxy ou Browser en interne et transmet votre clé API à chaque sous-appel. Chaque sous-appel apparaît dans votre journal d'activité; l'appel externe /api/auto/ n'ajoute pas de ligne facturable distincte.
  • Transmettez validate.data.accept avec une sous-chaîne que seule la page réelle contient. Sans cela, auto ne peut pas distinguer un véritable 200 d'un interstitiel de challenge renvoyé avec le statut 200.
  • timeout_ms limite l'appel complet. Un premier accès à froid vers un site protégé peut prendre des dizaines de secondes, tandis que les sessions chaudes réutilisées se terminent généralement en moins d'une seconde.

Requête Unique

POST /api/single/

Envoie une requête HTTP avec des caractéristiques réseau réalistes similaires à celles d'un navigateur, sans démarrer de vrai navigateur. Il s'agit de l'endpoint le plus rapide.

Corps de la requête

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 l'horodatage actuel afin de contourner le cache.
headers [string, string][] Non - Headers personnalisés sous forme de paires [nom, valeur]
unblocker boolean Non true Envoyez des headers de navigateur réalistes (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Activé par défaut. Définissez false pour envoyer une simple signature client.
timeout_ms number Non 15000 Délai d'attente global en ms (max : 120000)
connect_timeout_ms number Non 5000 Délai d'attente de connexion en ms
accept_timeout_ms number Non 5000 Délai d'attente d'acceptation en ms (temps d'attente pour l'acceptation de la connexion)
server_response_timeout_ms number Non 15000 Délai d'attente de la 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 désactivé Nombre maximum de redirections à suivre (0-20). Omettez pour désactiver.
tryJsonData boolean Non false Analysez le corps de la response en JSON si possible
returnBuffer boolean Non false Retournez le buffer brut au lieu de la chaîne décodée
data any Non - Corps de la request (chaîne ou objet, auto-sérialisé en JSON)
proxy string Non - ID du proxy issu d'une response précédente, pour conserver la même sortie. Renvoyez la chaîne opaque telle quelle. Une adresse proxy brute est rejetée avec 400 Invalid proxy format.
browser string Non Chrome Navigateur à présenter : Chrome, Edge, Safari, Firefox ou Tor. Voir Profils de navigateur.
os string Non - Système d'exploitation à présenter : Windows, macOS, Android ou iOS. Un nom de famille accepte toutes ses versions.
version string Non newest Version du navigateur à présenter, telle que listée dans le catalogue. La correspondance la plus récente l'emporte lorsque plusieurs conviennent.
profile string Non - ID exact du profil depuis GET /api/profiles, au lieu des trois champs ci-dessus.
validate object Non - Règles de validation de la response (voir ci-dessous)

Profils de navigateur

Par défaut, une request présente le dernier Google Chrome. Certaines cibles acceptent un navigateur et en refusent un autre, donc browser, os et version restreignent un catalogue de profils mesurés, et profile en sélectionne un par ID.

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

Règles :

  • La sélection nécessite unblocker (activé par défaut). Si le débloqueur est désactivé, aucun en-tête de navigateur n'est envoyé, la requête est donc refusée plutôt qu'à moitié appliquée.
  • Lorsque plusieurs profils correspondent, la version la plus récente l'emporte.
  • Une combinaison que le catalogue ne peut pas présenter renvoie une erreur indiquant ce qui est disponible. La requête n'est jamais envoyée en tant que navigateur différent.
  • Les quatre mêmes champs sont disponibles dans l'objet request de POST /proxy/.

GET /api/profiles renvoie le catalogue complet et ne nécessite aucune clé API :

{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}

osFamily est la valeur sur laquelle filtrer lors de la construction d'un sélecteur ; os conserve le nom de la version pour l'affichage.

Règles de validation

L'objet validate vous permet de définir des conditions de succès et d'échec. Si une condition fail correspond, la request est traitée comme un échec. Si des conditions accept sont définies, seules les responses correspondantes sont traitées comme des succès.

{
  "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",
    "timeout_ms": 10000
  }'

Réponse :

{
  "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,
  "proxy": "A1B2C3"
}

Lorsque la cible exécute une vérification de bot en chemin vers le body, la response contient également un objet defense indiquant le fournisseur et si la vérification a été réussie :

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}
Champ Type Description
status number Code de statut HTTP de la cible
headers array Un objet par saut de redirection. Chacun a un champ result avec la ligne de statut plus chaque header de la réponse. Les headers à valeurs multiples (Set-Cookie, Link, WWW-Authenticate) sont retournés comme des tableaux de chaînes.
data string/object Corps de la réponse (JSON si tryJsonData est true)
total_time number Temps total de la requête en secondes
proxy string ID encodé du proxy par lequel la requête est passée (uniquement si un proxy a été fourni sur la requête). Réutilisez-le sur un appel de suivi pour épingler la même sortie.
defense object Présent uniquement lorsque la cible a exécuté une vérification bot sur cette requête. defense.solved indique si la vérification a été passée. Voir Anti-Bot Defenses pour chaque champ et la liste complète des fournisseurs.
error string Message d'erreur si la requête a échoué

Proxy Request

POST /api/proxy/

Achemine votre requête via des proxys rotatifs avec réessai automatique en cas d'échec. La sélection de portée peut éventuellement être définie sur un ensemble de pays de sortie visibles par la cible.

Corps de la requête

Paramètre Type Requis Défaut Description
request object Oui - Un seul corps de requête (les mêmes champs que Single Request ci-dessus)
timeout_ms number Non 45000 Délai global pour toutes les tentatives en ms (max: 120000)
maxTries number Non 5 Nombre maximum de tentatives de rotation du proxy (max: 90)
ignoreProxies string[] Non - ID de proxy à exclure de la rotation (utilisez les ID renvoyés par les réponses précédentes)
exitCountries string[] Non - Liste d'autorisation stricte des codes pays de sortie visibles par la cible à deux lettres (ex. ["CZ", "GB"]). Les valeurs sont tronquées, mises en majuscules et dédupliquées. Les proxys avec des sorties inconnues sont exclus et la requête ne se rabat jamais sur un pays non demandé.

Portée exitCountries

La sélection utilise les dernières métadonnées de pays visibles par la cible disponibles, normalement actualisées en une dizaine de minutes. Ce n'est pas une recherche de géolocalisation en direct pendant la requête. Ne déduisez pas le pays de service de l'adresse de l'hôte du proxy.

Si le pool actuel n'a pas de correspondance pour les pays demandés, la réponse renvoie HTTP 200 avec une enveloppe d'erreur :

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

Conservez le scope demandé et réessayez plus tard. Ne le modifiez ou ne l'élargissez que lorsque les exigences de pays de votre workflow changent explicitement.

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,
    "exitCountries": ["CZ", "GB"],
    "request": {
      "method": "GET",
      "url": "https://example.com/prices"
    }
  }'

Réponse :

{
  "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",
  "exitCountry": "CZ",
  "total": 2.341
}
Champ Type Description
proxy string Identifiant encodé du proxy utilisé. Réutilisez-le sur une requête Single ou Browser en le passant comme champ proxy, ou ignorez-le lors de la prochaine requête Proxy via ignoreProxies.
exitCountry string Code pays à deux lettres du proxy ayant traité la requête, visible par la cible. Présent uniquement lorsque la requête définit exitCountries. Vérifiez toujours qu'il s'agit d'un des codes demandés avant de faire confiance à la réponse.
total number Durée totale externe en secondes (float). Inclut la sélection du proxy, les tentatives et la tentative réussie. total_time correspond à la requête interne uniquement; total est toujours >= total_time.
error string Message d'erreur si la requête a échoué. En cas d'absence de portée, code est no_eligible_proxy et details.exitCountries renvoie la portée normalisée.

Tous les champs de réponse de Single Request sont également inclus, defense y compris: une tentative de proxy ayant rencontré une vérification de bot le signale de la même manière que Single.

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 le HTML entièrement rendu ainsi que le cookie jar.

Request Body

Paramètre Type Requis Défaut Description
url string Oui - URL cible
headers object Non - En-têtes 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
unblocker boolean Non true Résolution automatique des défis de bot courants (Cloudflare clearance, portails similaires) pendant le chargement de la page. Activé par défaut. Définissez false pour rendre tout ce que la page renvoie, y compris une page de défi, sans la résoudre.
proxy string Non - ID de proxy d'une réponse précédente, pour conserver la même sortie. Renvoyez la chaîne opaque telle quelle. Une adresse de proxy brute est rejetée avec 400 Invalid proxy format.
timeout_ms number Non 30000 Délai de chargement de la page en ms (max: 120000)
checkStatus number Non - Statut HTTP attendu (la requête échoue s'il est différent)
checkText string Non - Texte qui doit apparaître dans la page rendue

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

Réponse :

{
  "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...",
  "defenseSolved": true,
  "defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]},
  "proxy": "A1B2C3"
}
Champ Type Description
status number Code de statut HTTP de la cible
headers object En-têtes de réponse
body string or object Contenu de la page entièrement rendu. Chaîne HTML lorsque le content-type est HTML, objet lorsque la page a retourné du JSON et a été automatiquement analysée.
cookies array Objets cookies complets de la page. Chaque cookie inclut name, value, domain, path, expires, httpOnly, secure, sameSite, et d'autres propriétés de cookie.
userAgent string User-Agent du navigateur utilisé
defenseSolved boolean true si une défense anti-bot a été rencontrée et véritablement résolue lors de cet appel. Absent sinon. Détermine le coût de 15 contre 30 crédits.
defenses object present liste tous les fournisseurs reconnus pendant le chargement de la page, cleared liste ceux dont la page finale détient l'autorisation. Un fournisseur peut apparaître dans present et jamais dans cleared. Voir Défenses Anti-Bot.
proxy string ID encodé du proxy par lequel la requête est passée (uniquement lorsqu'un proxy a été fourni sur la requête). Réutilisez-le sur les appels suivants pour conserver la même sortie.
error string Message d'erreur si la requête a échoué

Codes de statut HTTP

Code Signification
200 Requête terminée (vérifiez le status interne pour la réponse de la cible)
400 Corps de la requête invalide, paramètres ou IP cible dans une plage privée/réservée
401 Clé API manquante ou invalide
429 Rate limit dépassé
500 Erreur interne du serveur
502 Upstream unavailable. FourA a atteint son moteur mais la réponse était inutilisable. Réessayez.
503 Service temporairement désactivé ou à pleine capacité, ou Backend service unavailable pendant qu'un moteur redémarre
504 Upstream timeout. Le moteur n'a pas terminé dans le budget de temps imparti pour cette requête. Augmentez timeout_ms ou réessayez.

Étapes suivantes

Mis à jour : 12 août 2026
Erreurs API →