Документация › Справка API › Справочник API Endpoints

Справочник API Endpoints

Справочник по всем API endpoints FourA с параметрами request и форматами response.

Base URL

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

Authentication

Каждый request требует ваш API ключ в 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"}'

Создавайте и управляйте API ключами в Dashboard. Ключи используют префикс pk_live_.

Response Headers

Каждый response от /api/* содержит один корреляционный header:

Header Value Description
X-Foura-Request-Id UUID Уникальный ID, назначенный для request. Возвращается в каждом response, включая 4xx и 5xx. Логируйте его на своей стороне.

Этот же ID связывает превью полезной нагрузки request и response в Activity Log в Dashboard (хранится 24 часа, последние 200 на ключ), позволяя вам найти точный request позже и повторить его из Activity прямо в Playground. Укажите его при обращении в поддержку, и он поможет найти request за секунды.

$ 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

Используете эти endpoints через MCP? @fouradata/mcp server оборачивает все три endpoints как нативные инструменты MCP (foura_single, foura_proxy, foura_browser) с теми же структурами ввода, а также опцией offload_large для удобной обработки больших response с экономией токенов.

FourA предоставляет три request endpoints, каждый из которых оптимизирован под определенные сценарии:

Endpoint Best for
POST /single/ Быстрые HTTP requests, статические страницы, APIs
POST /proxy/ Защищенные сайты с автоматической ротацией proxy
POST /browser/ Страницы с рендерингом JavaScript, SPAs

Target URL Restrictions

Цели, которые разрешаются в приватные, loopback или зарезервированные диапазоны IP (RFC 5735, RFC 6598, зарезервированные блоки IPv6), отклоняются с кодом 400 до того, как request покинет FourA. Перенаправляются только публичные хосты и IP-адреса.

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

Single Request

POST /api/single/

Отправляет HTTP request с реалистичными характеристиками сетевого уровня, имитирующими браузер, без запуска реального браузера. Это самый быстрый endpoint.

Request Body

Parameter Type Required Default Description
method string Yes - HTTP-метод: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Yes - Целевой URL. Используйте {ts} в любом месте URL для вставки текущей метки времени для обхода кэширования.
headers [string, string][] No - Пользовательские headers в виде пар [имя, значение]
unblocker boolean No false Внедрение реалистичных headers браузера (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)
timeout_ms number No 15000 Общий таймаут в мс (макс: 120000)
connect_timeout_ms number No 5000 Таймаут соединения в мс
accept_timeout_ms number No 5000 Таймаут принятия соединения в мс (время ожидания принятия соединения)
server_response_timeout_ms number No 15000 Таймаут response сервера в мс (время ожидания первого байта)
dns_cache_timeout_sec number No 120 TTL DNS-кэша в секундах (макс: 240)
followRedirects number No disabled Максимальное количество редиректов для перехода (0-20). Опустите, чтобы отключить.
tryJsonData boolean No false Парсить тело response как JSON, если это возможно
returnBuffer boolean No false Возвращать необработанный буфер вместо декодированной строки
data any No - Тело request (строка или объект, автоматически сериализуемый в JSON)
proxy string No - URL-адрес proxy (http, socks4 или socks5) или ID proxy, возвращенный предыдущим response
validate object No - Правила валидации response (см. ниже)

Validation Rules

Объект validate позволяет задавать условия для успешного и неуспешного выполнения. Если условие fail совпадает, request считается неудачным. Если заданы условия accept, только соответствующие им responses считаются успешными.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Field Type Description
validate.status.accept number[] HTTP-коды статуса для принятия
validate.status.fail number[] HTTP-коды статуса для отклонения
validate.headers.accept object Пары ключ-значение в header, которые должны присутствовать
validate.headers.fail object Пары ключ-значение в header, которые вызывают ошибку
validate.data.accept string[] Строки, которые должны присутствовать в теле response
validate.data.fail string[] Строки в теле response, которые вызывают ошибку

Example

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
}
Field Type Description
status number HTTP-код статуса от целевого ресурса
headers array Один объект на каждый шаг редиректа. Каждый содержит поле result со строкой статуса и всеми headers в response. Headers с множественными значениями (Set-Cookie, Link, WWW-Authenticate) возвращаются в виде массивов строк.
data string/object Тело response (JSON, если параметр tryJsonData равен true)
total_time number Общее время request в секундах
error string Сообщение об ошибке, если request завершился неудачно

Proxy Request

POST /api/proxy/

Маршрутизирует ваш request через ротируемые proxies с автоматическим повтором при сбое.

Request Body

Parameter Type Required Default Description
request object Yes - Тело одиночного request (те же поля, что и в Single Request выше)
timeout_ms number No 45000 Общий таймаут для всех попыток в мс (макс: 120000)
maxTries number No 5 Максимальное количество попыток ротации proxy (макс: 90)
ignoreProxies string[] No - ID proxy для исключения из ротации (используйте ID, возвращенные предыдущими responses)

Example

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
}
Field Type Description
proxy string Закодированный идентификатор использованного proxy. Используйте его повторно в Single или Browser request, передав в поле proxy, или пропустите его в следующем Proxy request с помощью ignoreProxies.
total number Внешняя общая длительность в секундах (float). Включает выбор proxy, повторные попытки и успешную попытку. total_time указывает на время только внутреннего request; total всегда >= total_time.
error string Сообщение об ошибке, если request завершился неудачно

Также включены все поля response из Single Request.

Browser Request

POST /api/browser/

Открывает ваш URL в экземпляре браузера Chrome. Страница загружается, выполняется JavaScript, и вы получаете полностью отрендеренный HTML вместе с cookies.

Request Body

Parameter Type Required Default Description
url string Yes - Целевой URL
headers object No - Пользовательские headers в виде пар ключ-значение
cookies array No - Cookies для установки: [{name, value, domain?}]
userAgent string No - Пользовательская строка User-Agent
proxy string No - URL-адрес proxy или ID proxy, возвращенный предыдущим response
timeout_ms number No 30000 Таймаут загрузки страницы в мс (макс: 120000)
checkStatus number No - Ожидаемый HTTP-статус (при несовпадении request завершается ошибкой)
checkText string No - Текст, который должен присутствовать на отрендеренной странице

Example

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..."
}
Field Type Description
status number HTTP-код статуса от целевого ресурса
headers object Response headers
body string or object Полностью отрендеренное содержимое страницы. Строка HTML, если content-type равен HTML; объект, если страница вернула JSON и он был автоматически распарсен.
cookies array Полные объекты cookies со страницы. Каждая cookie включает name, value, domain, path, expires, httpOnly, secure, sameSite и другие свойства cookie.
userAgent string Использованный User-Agent браузера
error string Сообщение об ошибке, если request завершился неудачно

HTTP Status Codes

Code Meaning
200 Request выполнен (проверьте внутренний status для получения response цели)
400 Некорректное тело request, параметры или целевой IP находится в приватном/зарезервированном диапазоне
401 Отсутствует или недействителен API ключ
429 Превышен rate limit
500 Внутренняя ошибка сервера
503 Сервис временно отключен или перегружен

Next Steps

  • Authentication: Управляйте вашими API ключами
  • Error Handling: Корректно обрабатывайте ошибки
  • Rate Limits: Ознакомьтесь с лимитами на requests
  • Quick Start: Ваш первый request за 30 секунд
Обновлено: 1 июля 2026 г.
Ошибки API →