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

Справочник за всички FourA API endpoints с параметри на requests и формати на responses.

Base URL

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

Автентификация

Всяка request изисква вашия API key в X-API-Key header:

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 keys в Dashboard. Те използват префикса pk_live_.

Response Headers

Всеки response от /api/* съдържа един correlation header:

Header	Стойност	Описание
`X-Foura-Request-Id`	UUID	Уникален ID, присвоен на request. Връща се при всеки response, включително 4xx и 5xx. Записвайте го във вашите логове.

Същият ID свързва прегледа на request и response payload в Activity Log на Dashboard (пази се 24 часа, последните 200 на API key), така че можете да потърсите точната 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 сървърът обвива и трите endpoints като native MCP tools (foura_single, foura_proxy, foura_browser) със същите input shapes плюс offload_large opt-in за token-friendly large-response handling.

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

Endpoint	Най-подходящ за
`POST /single/`	Бързи HTTP requests, статични страници, APIs
`POST /proxy/`	Защитени сайтове с автоматична proxy ротация
`POST /browser/`	Страници, рендирани с JavaScript, SPAs

Ограничения за целевия URL

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

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

Single Request

POST /api/single/

Изпраща HTTP request с реалистични browser-like wire характеристики, без да стартира реален браузър. Това е най-бързият endpoint.

Request Body

Параметър	Тип	Задължителен	По подразбиране	Описание
`method`	string	Да	-	HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
`url`	string	Да	-	Целеви URL. Използвайте `{ts}` навсякъде в URL, за да вмъкнете текущия timestamp за cache-busting.
`headers`	[string, string][]	Не	-	Персонализирани headers като [name, value] двойки
`unblocker`	boolean	Не	false	Инжектиране на реалистични browser headers (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)
`timeout_ms`	number	Не	15000	Общ timeout в ms (макс: 120000)
`connect_timeout_ms`	number	Не	5000	Connection timeout в ms
`accept_timeout_ms`	number	Не	5000	Accept timeout в ms (време за изчакване на приемане на връзката)
`server_response_timeout_ms`	number	Не	15000	Server response timeout в ms (време за изчакване на първия байт)
`dns_cache_timeout_sec`	number	Не	120	DNS cache TTL в секунди (макс: 240)
`followRedirects`	number	Не	disabled	Максимален брой redirects за следване (0-20). Пропуснете за деактивиране.
`tryJsonData`	boolean	Не	false	Парсване на response body като JSON, ако е възможно
`returnBuffer`	boolean	Не	false	Връщане на необработен buffer вместо декодиран string
`data`	any	Не	-	Request body (string или обект, автоматично сериализиран до JSON)
`proxy`	string	Не	-	Proxy URL (http, socks4 или socks5) или proxy ID, върнат от предходен response
`validate`	object	Не	-	Правила за валидация на response (вижте по-долу)

Правила за валидация

Обектът 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"] }
  }
}

Поле	Тип	Описание
`validate.status.accept`	number[]	HTTP status кодове за приемане
`validate.status.fail`	number[]	HTTP status кодове за отхвърляне
`validate.headers.accept`	object	Header key-value двойки, които трябва да присъстват
`validate.headers.fail`	object	Header key-value двойки, които предизвикват неуспех
`validate.data.accept`	string[]	Strings, които трябва да се появят в response body
`validate.data.fail`	string[]	Strings в response body, които предизвикват неуспех

Пример

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
}

Поле	Тип	Описание
`status`	number	HTTP status код от целта
`headers`	array	По един обект за всеки redirect hop. Всеки има `result` поле със статус линията плюс всеки response header. Multi-value headers (`Set-Cookie`, `Link`, `WWW-Authenticate`) се връщат като масиви от strings.
`data`	string/object	Response body (JSON, ако `tryJsonData` е true)
`total_time`	number	Общо време на request в секунди
`error`	string	Съобщение за грешка, ако request е неуспешна

Proxy Request

POST /api/proxy/

Маршрутизира вашата request през ротиращи proxies с автоматичен повторен опит при неуспех.

Request Body

Параметър	Тип	Задължителен	По подразбиране	Описание
`request`	object	Да	-	Единично request body (същите полета като при Single Request по-горе)
`timeout_ms`	number	Не	45000	Общ timeout за всички опити в ms (макс: 120000)
`maxTries`	number	Не	5	Максимален брой опити за proxy ротация (макс: 90)
`ignoreProxies`	string[]	Не	-	Proxy IDs за изключване от ротацията (използвайте IDs, върнати от предходни responses)

Пример

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
}

Поле	Тип	Описание
`proxy`	string	Кодиран идентификатор на използваното proxy. Използвайте го повторно в Single или Browser request, като го подадете в полето `proxy`, или го пропуснете при следващата Proxy request чрез `ignoreProxies`.
`total`	number	Външно outer wall-clock времетраене в секунди (float). Включва избора на proxy, повторните опити и успешния опит. `total_time` е само вътрешната request; `total` винаги е >= `total_time`.
`error`	string	Съобщение за грешка, ако request е неуспешна

Всички полета от response на Single Request също са включени.

Browser Request

POST /api/browser/

Отваря вашия URL в Chrome browser инстанция. Страницата се зарежда, JavaScript се изпълнява и получавате напълно рендирания HTML плюс cookie jar.

Request Body

Параметър	Тип	Задължителен	По подразбиране	Описание
`url`	string	Да	-	Целеви URL
`headers`	object	Не	-	Персонализирани headers като key-value двойки
`cookies`	array	Не	-	Cookies за задаване: `[{name, value, domain?}]`
`userAgent`	string	Не	-	Персонализиран User-Agent string
`proxy`	string	Не	-	Proxy URL или proxy ID, върнат от предходен response
`timeout_ms`	number	Не	30000	Page load timeout в ms (макс: 120000)
`checkStatus`	number	Не	-	Очакван HTTP status (request се проваля, ако е различен)
`checkText`	string	Не	-	Текст, който трябва да се появи в рендираната страница

Пример

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

Поле	Тип	Описание
`status`	number	HTTP status код от целта
`headers`	object	Response headers
`body`	string or object	Напълно рендирано съдържание на страницата. String HTML, когато content-type е HTML; обект, когато страницата е върнала JSON и е била автоматично парсната.
`cookies`	array	Пълни cookie обекти от страницата. Всяка cookie включва `name`, `value`, `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite` и други cookie свойства.
`userAgent`	string	Използван browser User-Agent
`error`	string	Съобщение за грешка, ако request е неуспешна

HTTP Status Codes

Код	Значение
200	Request е завършена (проверете вътрешния `status` за response от целта)
400	Невалидно request body, параметри или целево IP в частен/резервиран диапазон
401	Липсващ или невалиден API key
429	Превишен rate limit
500	Вътрешна грешка на сървъра
503	Услугата е временно деактивирана или е с изчерпан капацитет

Следващи стъпки

Автентификация: Управлявайте вашите API keys
Обработка на грешки: Справяйте се с грешките елегантно
Rate Limits: Разберете ограниченията за requests
Бърз старт: Вашата първа request за 30 секунди

Обновено: 1 юли 2026 г.