Docs › Referência API › Referência de Endpoints da API

Referência de Endpoints da API

Uma referência para todos os endpoints da API FourA com parâmetros de request e formatos de response.

Base URL

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

Autenticação

Todo request exige a sua chave de API no 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"}'

Crie e gerencie chaves de API no Dashboard. As chaves usam o prefixo pk_live_.

Headers de Response

Cada response de /api/* carrega um header de correlação:

Header Valor Descrição
X-Foura-Request-Id UUID ID exclusivo atribuído ao request. Retornado em cada response, incluindo 4xx e 5xx. Registre-o do seu lado.

O mesmo ID serve de chave para o preview de payload do request e do response no Activity Log do Dashboard (mantido por 24 horas, os últimos 200 por chave), para que você possa buscar o request exato mais tarde e reproduzi-lo do Activity diretamente no Playground. Inclua-o ao entrar em contato com o suporte, e ele localizará o request em 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

Usando estes endpoints via MCP? O @fouradata/mcp server envolve todos os três endpoints como ferramentas MCP nativas (foura_single, foura_proxy, foura_browser) com os mesmos formatos de entrada, além de uma opção de offload_large para manipulação de large-response amigável para tokens.

FourA oferece três endpoints de request, cada um otimizado para diferentes cenários:

Endpoint Ideal para
POST /single/ Requests HTTP rápidos, páginas estáticas, APIs
POST /proxy/ Sites protegidos com rotação automática de proxy
POST /browser/ Páginas renderizadas em JavaScript, SPAs

Restrições de URL de Destino

Destinos que resolvem para faixas de IP privadas, de loopback ou reservadas (RFC 5735, RFC 6598, blocos reservados IPv6) são recusados com um erro 400 antes que o request saia da FourA. Apenas hostnames e IPs públicos são encaminhados.

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

Single Request

POST /api/single/

Envia um request HTTP com características de rede realistas semelhantes às de um navegador, sem iniciar um navegador real. Este é o endpoint mais rápido.

Request Body

Parâmetro Tipo Obrigatório Padrão Descrição
method string Sim - Método HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Sim - URL de destino. Use {ts} em qualquer lugar da URL para inserir o timestamp atual para cache-busting.
headers [string, string][] Não - Headers personalizados como pares [nome, valor]
unblocker boolean Não false Injeta headers de navegador realistas (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)
timeout_ms number Não 15000 Timeout geral em ms (máx: 120000)
connect_timeout_ms number Não 5000 Timeout de conexão em ms
accept_timeout_ms number Não 5000 Timeout de aceite em ms (tempo para aguardar a aceitação da conexão)
server_response_timeout_ms number Não 15000 Timeout de response do servidor em ms (tempo para aguardar o primeiro byte)
dns_cache_timeout_sec number Não 120 TTL do cache DNS em segundos (máx: 240)
followRedirects number Não desativado Máximo de redirecionamentos a seguir (0-20). Omita para desativar.
tryJsonData boolean Não false Analisa o corpo do response como JSON, se possível
returnBuffer boolean Não false Retorna o buffer bruto em vez da string decodificada
data any Não - Corpo do request (string ou objeto, auto-serializado para JSON)
proxy string Não - URL de proxy (http, socks4 ou socks5) ou um ID de proxy retornado por um response anterior
validate object Não - Regras de validação de response (veja abaixo)

Regras de Validação

O objeto validate permite definir condições para sucesso e falha. Se uma condição fail corresponder, o request será tratado como falho. Se as condições accept forem definidas, apenas os responses correspondentes serão tratados como bem-sucedidos.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Campo Tipo Descrição
validate.status.accept number[] Códigos de status HTTP a aceitar
validate.status.fail number[] Códigos de status HTTP a rejeitar
validate.headers.accept object Pares chave-valor de header que devem estar presentes
validate.headers.fail object Pares chave-valor de header que acionam falha
validate.data.accept string[] Strings que devem aparecer no corpo do response
validate.data.fail string[] Strings no corpo do response que acionam falha

Exemplo

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 Descrição
status number Código de status HTTP do destino
headers array Um objeto por salto de redirecionamento. Cada um possui um campo result com a linha de status mais cada header de response. Headers de múltiplos valores (Set-Cookie, Link, WWW-Authenticate) retornam como arrays de strings.
data string/object Corpo do response (JSON se tryJsonData for true)
total_time number Tempo total do request em segundos
error string Mensagem de erro se o request falhar

Proxy Request

POST /api/proxy/

Roteia o seu request através de proxies rotativos com tentativa automática em caso de falha.

Request Body

Parâmetro Tipo Obrigatório Padrão Descrição
request object Sim - Um corpo de request único (mesmos campos do Single Request acima)
timeout_ms number Não 45000 Timeout geral para todas as tentativas em ms (máx: 120000)
maxTries number Não 5 Máximo de tentativas de rotação de proxy (máx: 90)
ignoreProxies string[] Não - IDs de proxy a excluir da rotação (use IDs retornados por responses anteriores)

Exemplo

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 Descrição
proxy string Identificador codificado do proxy utilizado. Reutilize-o em um request Single ou Browser passando-o como o campo proxy, ou pule-o no próximo request Proxy via ignoreProxies.
total number Duração externa total em segundos (float). Inclui seleção de proxy, tentativas e a tentativa bem-sucedida. total_time é apenas o request interno; total é sempre >= total_time.
error string Mensagem de erro se o request falhar

Todos os campos de response do Single Request também estão incluídos.

Browser Request

POST /api/browser/

Abre a sua URL em uma instância do navegador Chrome. A página carrega, o JavaScript é executado e você obtém o HTML totalmente renderizado mais o cookie jar.

Request Body

Parâmetro Tipo Obrigatório Padrão Descrição
url string Sim - URL de destino
headers object Não - Headers personalizados como pares chave-valor
cookies array Não - Cookies a definir: [{name, value, domain?}]
userAgent string Não - String de User-Agent personalizada
proxy string Não - URL de proxy ou um ID de proxy retornado por um response anterior
timeout_ms number Não 30000 Timeout de carregamento da página em ms (máx: 120000)
checkStatus number Não - Status HTTP esperado (o request falha se for diferente)
checkText string Não - Texto que deve aparecer na página renderizada

Exemplo

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 Descrição
status number Código de status HTTP do destino
headers object Headers de response
body string or object Conteúdo da página totalmente renderizado. String HTML quando o content-type for HTML; objeto quando a página retornar JSON e for auto-analisada.
cookies array Objetos de cookie completos da página. Cada cookie inclui name, value, domain, path, expires, httpOnly, secure, sameSite e outras propriedades de cookie.
userAgent string User-Agent do navegador utilizado
error string Mensagem de erro se o request falhar

Códigos de Status HTTP

Código Significado
200 Request concluído (verifique o status interno para o response do destino)
400 Corpo do request, parâmetros ou IP de destino inválidos em uma faixa privada/reservada
401 Chave de API ausente ou inválida
429 Rate limit excedido
500 Erro interno do servidor
503 Serviço temporariamente desativado ou com capacidade máxima atingida

Próximos Passos

Atualizado em: 1 de julho de 2026
Erros da API →