Docs › Referencia API › Referencia de endpoints de la API

Referencia de endpoints de la API

Una referencia para todos los endpoints de la API de FourA con parámetros de request y formatos de response.

Base URL

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

Autenticación

Cada request requiere su API key en el 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"}'

Cree y gestione API keys en el Dashboard. Las keys utilizan el prefijo pk_live_.

Response Headers

Cada response de /api/* incluye un correlation header:

Header Valor Descripción
X-Foura-Request-Id UUID ID único asignado al request. Se devuelve en cada response, incluyendo 4xx y 5xx. Regístrelo en sus logs.

El mismo ID identifica la vista previa del payload del request y del response en el Activity Log del Dashboard (se conserva durante 24 horas, los últimos 200 por key), lo que le permite buscar el request exacto más tarde y volver a ejecutarlo desde Activity directamente en el Playground. Inclúyalo cuando se ponga en contacto con el soporte técnico para localizar el request en segundos.

$ 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

¿Utiliza estos endpoints a través de MCP? El servidor @fouradata/mcp envuelve los tres endpoints como herramientas MCP nativas (foura_single, foura_proxy, foura_browser) con las mismas estructuras de entrada, además de una opción de inclusión offload_large para un manejo de responses grandes optimizado para tokens.

FourA proporciona tres endpoints de request, cada uno optimizado para diferentes escenarios:

Endpoint Ideal para
POST /single/ Requests HTTP rápidos, páginas estáticas, APIs
POST /proxy/ Sitios protegidos con rotación automática de proxy
POST /browser/ Páginas renderizadas con JavaScript, SPAs

Restricciones de URL de destino

Los destinos que resuelven a rangos de IP privados, de loopback o reservados (RFC 5735, RFC 6598, bloques reservados de IPv6) se rechazan con un error 400 antes de que el request salga de FourA. Solo se reenvían hostnames e IPs públicas.

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

Single Request

POST /api/single/

Envía un request HTTP con características de red realistas similares a las de un navegador, sin necesidad de iniciar un navegador real. Este es el endpoint más rápido.

Request Body

Parámetro Tipo Requerido Por defecto Descripción
method string Sí - Método HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Sí - URL de destino. Utilice {ts} en cualquier parte de la URL para insertar la marca de tiempo actual para evitar el almacenamiento en caché (cache-busting).
headers [string, string][] No - Headers personalizados como pares [nombre, valor]
unblocker boolean No false Inyecta headers de navegador realistas (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)
timeout_ms number No 15000 Tiempo de espera (timeout) general en ms (máx: 120000)
connect_timeout_ms number No 5000 Tiempo de espera de conexión (connect timeout) en ms
accept_timeout_ms number No 5000 Tiempo de espera de aceptación (accept timeout) en ms (tiempo de espera para la aceptación de la conexión)
server_response_timeout_ms number No 15000 Tiempo de espera de response del servidor en ms (tiempo de espera para el primer byte)
dns_cache_timeout_sec number No 120 TTL de la caché DNS en segundos (máx: 240)
followRedirects number No disabled Número máximo de redirecciones a seguir (0-20). Omita para desactivar.
tryJsonData boolean No false Intenta parsear el cuerpo del response como JSON si es posible
returnBuffer boolean No false Devuelve el buffer sin procesar (raw buffer) en lugar de la cadena decodificada
data any No - Cuerpo del request (cadena u objeto, serializado automáticamente a JSON)
proxy string No - URL del proxy (http, socks4 o socks5) o un ID de proxy devuelto por un response anterior
validate object No - Reglas de validación del response (ver más abajo)

Reglas de validación

El objeto validate le permite definir condiciones de éxito y fallo. Si coincide una condición fail, el request se trata como fallido. Si se establecen condiciones accept, solo los responses que coincidan se tratarán como exitosos.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Campo Tipo Descripción
validate.status.accept number[] Códigos de estado HTTP a aceptar
validate.status.fail number[] Códigos de estado HTTP a rechazar
validate.headers.accept object Pares clave-valor de headers que deben estar presentes
validate.headers.fail object Pares clave-valor de headers que provocan un fallo
validate.data.accept string[] Cadenas que deben aparecer en el cuerpo del response
validate.data.fail string[] Cadenas en el cuerpo del response que provocan un fallo

Ejemplo

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
}
Campo Tipo Descripción
status number Código de estado HTTP del destino
headers array Un objeto por cada salto de redirección. Cada uno tiene un campo result con la línea de estado más cada header del response. Los headers con múltiples valores (Set-Cookie, Link, WWW-Authenticate) se devuelven como arrays de cadenas.
data string/object Cuerpo del response (JSON si tryJsonData es true)
total_time number Tiempo total del request en segundos
error string Mensaje de error si el request falló

Proxy Request

POST /api/proxy/

Enruta su request a través de proxies rotativos con reintento automático en caso de fallo.

Request Body

Parámetro Tipo Requerido Por defecto Descripción
request object Sí - El cuerpo de un único request (mismos campos que en Single Request arriba)
timeout_ms number No 45000 Tiempo de espera (timeout) general para todos los intentos en ms (máx: 120000)
maxTries number No 5 Número máximo de intentos de rotación de proxy (máx: 90)
ignoreProxies string[] No - IDs de proxy a excluir de la rotación (utilice los IDs devueltos por responses anteriores)

Ejemplo

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
}
Campo Tipo Descripción
proxy string Identificador codificado del proxy utilizado. Reutilícelo en un Single o Browser request pasándolo como el campo proxy, o descártelo en el siguiente Proxy request a través de ignoreProxies.
total number Duración total transcurrida (wall-clock) en segundos (float). Incluye la selección de proxy, los reintentos y el intento exitoso. total_time corresponde únicamente al request interno; total siempre es >= total_time.
error string Mensaje de error si el request falló

También se incluyen todos los campos de response de Single Request.

Browser Request

POST /api/browser/

Abre su URL en una instancia del navegador Chrome. La página se carga, se ejecuta JavaScript y usted obtiene el HTML completamente renderizado más el cookie jar.

Request Body

Parámetro Tipo Requerido Por defecto Descripción
url string Sí - URL de destino
headers object No - Headers personalizados como pares clave-valor
cookies array No - Cookies a establecer: [{name, value, domain?}]
userAgent string No - Cadena de User-Agent personalizada
proxy string No - URL del proxy o un ID de proxy devuelto por un response anterior
timeout_ms number No 30000 Tiempo de espera de carga de página en ms (máx: 120000)
checkStatus number No - Estado HTTP esperado (el request falla si es diferente)
checkText string No - Texto que debe aparecer en la página renderizada

Ejemplo

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..."
}
Campo Tipo Descripción
status number Código de estado HTTP del destino
headers object Headers del response
body string or object Contenido de la página completamente renderizado. Cadena HTML cuando content-type es HTML; objeto cuando la página devolvió JSON y se parseó automáticamente.
cookies array Objetos de cookie completos de la página. Cada cookie incluye name, value, domain, path, expires, httpOnly, secure, sameSite y otras propiedades de la cookie.
userAgent string User-Agent del navegador utilizado
error string Mensaje de error si el request falló

Códigos de estado HTTP

Código Significado
200 Request completado (verifique el status interno para el response del destino)
400 Cuerpo del request, parámetros o IP de destino no válidos en un rango privado/reservado
401 API key faltante o no válida
429 Rate limit excedido
500 Error interno del servidor
503 Servicio temporalmente desactivado o al límite de su capacidad

Siguientes pasos

Actualizado: 1 de julio de 2026
Errores de la API →