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.

URL Base

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

Autenticação

Cada request exige 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 do /api/* carrega dois headers de correlação:

Header	Valor	Descrição
`X-FourA-Request-Id`	UUID	ID único atribuído ao request. Retornado em cada response, incluindo 4xx e 5xx. Registre no seu lado.
`X-FourA-Credits`	integer	Créditos gastos neste request. Retornado no sucesso e na falha (o trabalho foi feito de qualquer forma). Consulte Resultados do request para saber quais resultados são faturáveis.

O mesmo ID de request indexa a visualização do payload de request e response no Activity Log do Dashboard (mantido por 24 horas, os últimos 200 por chave), para que você possa pesquisar o request exato mais tarde e repeti-lo do Activity direto para o Playground. Inclua-o quando você entrar em contato com o suporte e isso identificará 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
x-foura-credits: 2
...

Veja Response Headers para a lista completa e dicas de uso.

Endpoints

Usando estes endpoints via MCP? O servidor @fouradata/mcp encapsula todos os quatro endpoints como ferramentas nativas do MCP (foura_auto, foura_single, foura_proxy, foura_browser) com os mesmos formatos de entrada, além de uma opção de adesão offload_large para tratamento de grandes respostas amigável a tokens.

A FourA fornece quatro endpoints de request, cada um otimizado para um cenário diferente:

Endpoint	Melhor para
`POST /auto/`	Busca inteligente. Você passa uma URL, a FourA escolhe o caminho mais barato que funciona (direto, proxy rotativo ou browser) e lembra o que funciona por host.
`POST /single/`	Requests HTTP rápidos, páginas estáticas, APIs
`POST /proxy/`	Sites protegidos com rotação automática de proxy, escopo opcional de país visível para o alvo
`POST /browser/`	Páginas renderizadas por JavaScript, SPAs
`GET /profiles`	O catálogo de perfis de browser para `single` e `proxy`. Público, sem chave de API.

Para uma explicação mais detalhada sobre quando escolher cada um, veja Escolhendo o Endpoint Correto e o guia do Smart Fetch.

Restrições de URL de Destino

Alvos que resolvem para intervalos de IP privados, loopback ou reservados (RFC 5735, RFC 6598, blocos reservados de 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" }

Smart Fetch (Auto)

POST /api/auto/

Você passa uma URL e regras validate opcionais. O FourA percorre uma escada com base em custos (sonda direta barata, proxy rotativo, navegador completo) e para no primeiro degrau que retornar uma response que as suas regras aceitem. Em chamadas repetidas para o mesmo host, uma sessão quente é reproduzida, de forma que o segundo acesso é barato.

Você não ajusta as tentativas, os tamanhos de pool ou a quantidade de proxy. O FourA aprende isso por host.

Corpo da request

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`url`	string	Sim	-	URL de destino
`method`	string	Não	`"GET"`	Método HTTP
`headers`	[string, string][]	Não	-	Headers personalizados como pares [nome, valor]
`data`	any	Não	-	Corpo da request para requests que não sejam GET
`validate`	object	Não	-	Critérios de sucesso, no mesmo formato do `validate` do Single Request (veja abaixo). Diga ao auto como é uma página real para que ele possa diferenciar conteúdo de uma página de desafio.
`returnSession`	boolean	Não	`true`	Incluir a sessão vencedora (`proxy`, `cookies`, `userAgent`) na response para que você possa repeti-la através do `/api/single/` ou `/api/browser/`.
`forceProxy`	boolean	Não	`true`	Sempre rotear por um proxy rotativo. Defina `false` para permitir o caminho direto mais barato quando o alvo permitir (algumas defesas são mais restritas em relação ao tráfego de proxy).
`timeout_ms`	integer	Não	`120000`	Orçamento de tempo total para toda a chamada, em milissegundos. Todas as subtentativas rodam dentro deste orçamento. Mínimo `5000`, máximo `180000`.
`ignoreProxies`	string[]	Não	-	IDs de proxy para evitar em todas as subtentativas. Use IDs retornados pelas responses anteriores do `/api/auto/` ou `/api/proxy/`.
`followRedirects`	integer	Não	`5`	Máximo de redirecionamentos para seguir nos degraus baratos da escada. `0` para desativar. Máximo `20`.

Response

{
  "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..."
  }
}

Campo	Tipo	Descrição
`status`	number	Status HTTP do alvo.
`data`	string ou objeto	Corpo da response.
`headers`	array ou objeto	Headers da response do alvo. Rungs single e de proxy retornam um array de objetos de header por salto; rungs de browser retornam um objeto plano.
`meta.rung`	string	Qual rung da ladder entregou a response. Um de: `probe` (request direta barata), `proxy` (proxy rotativo), `browser` (renderização completa no browser), `cache` (sessão aquecida reproduzida) ou `fail` (nenhum rung produziu uma response aceita).
`meta.solved`	boolean	Se um desafio de bot foi resolvido durante esta chamada.
`meta.attempts`	number	Subtentativas feitas antes do sucesso.
`meta.credits`	number	Total de créditos gastos nesta chamada. Corresponde a `X-FourA-Credits`.
`session.proxy`	string	ID codificado do proxy que entregou a response. Reutilize-o em uma request Single ou Browser. Presente quando `returnSession` é `true`.
`session.cookies`	array	Cookies da tentativa vencedora. Presente quando `returnSession` é `true`.
`session.userAgent`	string	User-Agent usado na tentativa vencedora. Presente quando `returnSession` é `true`.
`error`	string	Mensagem de erro se a chamada falhou.

Exemplo

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

Notas

Auto é um coordenador. Ele chama Single, Proxy ou Browser internamente e encaminha sua chave de API para cada subchamada. Cada subchamada aparece no seu Log de Atividade; a chamada externa /api/auto/ não adiciona uma linha faturável separada.
Passe validate.data.accept com uma substring que apenas a página real contém. Sem isso, o auto não consegue distinguir um 200 real de um desafio intersticial retornado com status 200.
timeout_ms limita a chamada inteira. Um primeiro acesso frio a um site protegido pode levar dezenas de segundos; sessões quentes reutilizadas geralmente terminam em menos de um segundo.

Single Request

POST /api/single/

Envia uma requisição HTTP com características de rede realistas semelhantes a um navegador, sem iniciar um navegador real. Este é o endpoint mais rápido.

Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`method`	string	Sim	-	HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
`url`	string	Sim	-	URL de destino. Use `{ts}` em qualquer lugar na URL para inserir o timestamp atual para cache-busting.
`headers`	[string, string][]	Não	-	Headers personalizados como pares [name, value]
`unblocker`	boolean	Não	`true`	Envie headers realistas de navegador (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Ativado por padrão. Defina `false` para enviar uma assinatura de cliente simples.
`timeout_ms`	number	Não	15000	Timeout geral em ms (máximo: 120000)
`connect_timeout_ms`	number	Não	5000	Connection timeout em ms
`accept_timeout_ms`	number	Não	5000	Accept timeout em ms (tempo de espera pela aceitação da conexão)
`server_response_timeout_ms`	number	Não	15000	Server response timeout em ms (tempo de espera pelo primeiro byte)
`dns_cache_timeout_sec`	number	Não	120	DNS cache TTL em segundos (máximo: 240)
`followRedirects`	number	Não	desativado	Máximo de redirecionamentos a seguir (0-20). Omitir para desativar.
`tryJsonData`	boolean	Não	false	Faça o parse do response body como JSON, se possível
`returnBuffer`	boolean	Não	false	Retorne o buffer bruto em vez da string decodificada
`data`	any	Não	-	Request body (string ou objeto, serializado automaticamente para JSON)
`proxy`	string	Não	-	Proxy ID de um response anterior, para fixar a mesma saída. Passe a string opaca de volta sem alterações. Um endereço de proxy bruto é rejeitado com `400 Invalid proxy format`.
`browser`	string	Não	Chrome	Navegador a apresentar: Chrome, Edge, Safari, Firefox ou Tor. Consulte os Perfis de navegador.
`os`	string	Não	-	Sistema operacional a apresentar: Windows, macOS, Android ou iOS. O nome de uma família aceita qualquer uma de suas versões.
`version`	string	Não	newest	Versão do navegador a apresentar, conforme listado no catálogo. A correspondência mais recente vence quando várias se encaixam.
`profile`	string	Não	-	ID de perfil exato de `GET /api/profiles`, em vez dos três campos acima.
`validate`	object	Não	-	Regras de validação do response (veja abaixo)

Perfis de navegador

Por padrão, um request apresenta o Google Chrome mais recente. Alguns destinos aceitam um navegador e recusam outro, então browser, os e version reduzem um catálogo de perfis medidos, e profile seleciona um por id.

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

Regras:

A seleção requer unblocker (ativado por padrão). Com o desbloqueador desligado, nenhum header de navegador é enviado, portanto o request é recusado em vez de parcialmente aplicado.
Quando vários perfis correspondem, a versão mais recente vence.
Uma combinação que o catálogo não pode apresentar retorna um erro informando o que está disponível. O request nunca é enviado como um navegador diferente.
Os mesmos quatro campos estão disponíveis dentro do objeto request de POST /proxy/.

GET /api/profiles retorna o catálogo completo e não precisa de chave de API:

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

osFamily é o valor pelo qual filtrar ao construir um seletor; os mantém o nome da versão para exibição.

Regras de Validação

O objeto validate permite que você defina condições de sucesso e falha. Se uma condição fail corresponder, a request será tratada como falha. Se condições accept forem definidas, apenas as responses correspondentes serão tratadas como bem-sucedidas.

{
  "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 para aceitar
`validate.status.fail`	number[]	Códigos de status HTTP para 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 da response
`validate.data.fail`	string[]	Strings no corpo da 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",
    "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,
  "proxy": "A1B2C3"
}

Quando o alvo executa uma verificação de bot no caminho para o body, a resposta também carrega um objeto defense identificando o fornecedor e se a verificação foi aprovada:

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}

Campo	Tipo	Descrição
`status`	number	Código de status HTTP do alvo
`headers`	array	Um objeto por salto de redirecionamento. Cada um tem um campo `result` com a linha de status e cada header de response. Headers com 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
`proxy`	string	ID codificado do proxy pelo qual o request passou (apenas quando um `proxy` foi fornecido no request). Reutilize-o em uma chamada subsequente para fixar a mesma saída.
`defense`	object	Presente apenas quando o alvo executou uma verificação de bot neste request. `defense.solved` indica se a verificação foi superada. Consulte Defesas Anti-Bot para ver todos os campos e a lista completa de fornecedores.
`error`	string	Mensagem de erro se o request falhar

Proxy Request

POST /api/proxy/

Roteia seu request através de proxies rotativos com repetição automática em caso de falha. Opcionalmente, limite a seleção a um conjunto de países de saída visíveis para o alvo.

Corpo do Request

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	Número máximo de tentativas de rotação de proxy (máx: 90)
`ignoreProxies`	string[]	Não	-	IDs de proxy a serem excluídos da rotação (use os IDs retornados por responses anteriores)
`exitCountries`	string[]	Não	-	Allowlist estrita de códigos de país de duas letras visíveis para o alvo (ex. `["CZ", "GB"]`). Os valores são aparados, convertidos para maiúsculas e deduplicados. Proxies com saídas desconhecidas são excluídos e o request nunca recorre a um país não solicitado.

Escopo de exitCountries

A seleção usa os metadados mais recentes disponíveis de países visíveis para o alvo, normalmente atualizados em cerca de dez minutos. Não é uma consulta de geolocalização ao vivo durante o request. Não infira o país de serviço a partir do endereço de host do proxy.

Se o pool atual não tiver correspondência para os países solicitados, o response retornará HTTP 200 com um envelope de erro:

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

Mantenha o escopo solicitado e tente novamente mais tarde. Altere ou amplie apenas quando o requisito de país do seu fluxo de trabalho mudar explicitamente.

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

Resposta:

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

Campo	Tipo	Descrição
`proxy`	string	Identificador codificado do proxy usado. Reutilize-o em um request Single ou Browser passando-o como o campo `proxy`, ou pule-o no próximo request Proxy via `ignoreProxies`.
`exitCountry`	string	Código de país de duas letras visível para o destino do proxy que atendeu o request. Presente apenas quando o request definir `exitCountries`. Sempre verifique se é um dos códigos que você solicitou antes de confiar no response.
`total`	number	Duração externa de wall-clock em segundos (float). Inclui seleção de proxy, novas 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. Em uma falha de escopo, `code` é `no_eligible_proxy` e `details.exitCountries` reflete o escopo normalizado.

Todos os campos do response de Single Request também estão incluídos, defense entre eles: uma tentativa de proxy que encontrou uma verificação de bot relata isso da mesma forma que o Single.

Browser Request

POST /api/browser/

Abre sua URL em uma instância do navegador Chrome. A página carrega, o JavaScript executa e você recebe 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	-	Custom headers como pares chave-valor
`cookies`	array	Não	-	Cookies para definir: `[{name, value, domain?}]`
`userAgent`	string	Não	-	String User-Agent personalizada
`unblocker`	boolean	Não	`true`	Resolve automaticamente desafios comuns de bots (Cloudflare clearance, barreiras similares) durante o carregamento da página. Ativado por padrão. Defina `false` para renderizar o que a página retornar, incluindo uma página de desafio, sem resolver.
`proxy`	string	Não	-	ID do proxy de um response anterior, para fixar a mesma saída. Passe a string opaca de volta exatamente como está. Um endereço de proxy bruto é rejeitado com `400 Invalid proxy format`.
`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"
  }'

Resposta:

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

Campo	Tipo	Descrição
`status`	number	Código de status HTTP do destino
`headers`	object	Cabeçalhos da resposta
`body`	string or object	Conteúdo da página totalmente renderizado. String HTML quando o content-type for HTML; object quando a página retornar JSON e for convertida automaticamente.
`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
`defenseSolved`	boolean	`true` se uma defesa anti-bot foi encontrada e genuinamente superada nesta chamada. Ausente caso contrário. Define o custo de 15 vs 30 créditos.
`defenses`	object	`present` lista cada vendor reconhecido durante o carregamento da página, `cleared` lista aqueles cuja liberação a página final possui. Um vendor pode aparecer em `present` e nunca em `cleared`. Veja Anti-Bot Defenses.
`proxy`	string	ID codificado do proxy pelo qual a request passou (apenas quando um `proxy` foi fornecido na request). Reutilize em chamadas subsequentes para manter a mesma saída.
`error`	string	Mensagem de erro se a request falhar

Códigos de Status HTTP

Código	Significado
200	Request concluída (verifique o `status` interno para a resposta do destino)
400	Corpo da request inválido, parâmetros inválidos ou IP de destino em um intervalo privado/reservado
401	API key ausente ou inválida
429	Rate limit excedido
500	Erro interno do servidor
502	`Upstream unavailable`. A FourA alcançou seu motor, mas a resposta foi inutilizável. Tente novamente.
503	Serviço temporariamente desativado ou na capacidade máxima, ou `Backend service unavailable` enquanto um motor reinicia
504	`Upstream timeout`. O motor não terminou dentro do tempo limite para esta request. Aumente o `timeout_ms` ou tente novamente.

Próximos Passos

Smart Fetch (Auto): Quando deixar a FourA escolher o caminho para você
Choosing the Right Endpoint: Quando escolher Single, Proxy ou Browser manualmente
Authentication: Gerencie suas API keys
Error Handling: Trate erros adequadamente
Anti-Bot Defenses: Leia o campo defense e repita uma liberação
Rate Limits: Entenda os limites de requests
Quick Start: Sua primeira request em 30 segundos

Atualizado em: 12 de agosto de 2026