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

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

Базов URL

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

Удостоверяване

Всяка заявка изисква вашия API ключ в 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 ключове в Dashboard. Ключовете използват префикса pk_live_.

Хедъри на отговора

Всеки отговор от /api/* съдържа два корелационни хедъра:

Хедър	Стойност	Описание
`X-FourA-Request-Id`	UUID	Уникален ID, присвоен на заявката. Връща се при всеки отговор, включително 4xx и 5xx. Записвайте го в лог от ваша страна.
`X-FourA-Credits`	цяло число	Кредити, изразходвани за тази заявка. Връщат се при успех и при грешка (работата е извършена и в двата случая). Вижте Резултати от заявките за това кои резултати се таксуват.

Същият ID на заявката служи като ключ за прегледа на данните (payload) на заявката и отговора в Activity Log на Dashboard (пазят се 24 часа, последните 200 за ключ), така че можете да намерите точната заявка по-късно и да я изпълните отново от Activity директно в Playground. Включете го, когато се свързвате с поддръжката, и той ще локализира заявката за секунди.

$ 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
...

Вижте Response Headers за пълния списък и съвети за употреба.

Endpoints

Използвате тези endpoints чрез MCP? @fouradata/mcp сървърът обвива и четирите endpoints като нативни MCP инструменти (foura_auto, foura_single, foura_proxy, foura_browser) със същите входни формати плюс опция offload_large за оптимизирана за токени обработка на големи отговори.

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

Endpoint	Най-подходящ за
`POST /auto/`	Интелигентно извличане. Подавате URL, FourA избира най-евтиния работещ път (директен, ротиран proxy или браузър) и запомня кое работи за съответния хост.
`POST /single/`	Бързи HTTP заявки (requests), статични страници, APIs
`POST /proxy/`	Защитени сайтове с автоматична ротация на proxy, опционално ограничаване по държава, видима за целта
`POST /browser/`	Страници, рендирани с JavaScript, SPAs
`GET /profiles`	Каталогът с браузърни профили за `single` и `proxy`. Публичен, без API ключ.

За по-задълбочен преглед кога да изберете всеки от тях, вижте Избор на правилния Endpoint и ръководството за Smart Fetch.

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

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

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

Smart Fetch (Автоматично)

POST /api/auto/

Подавате URL адрес плюс опционални validate правила. FourA преминава през съобразена с разходите стълба (евтина директна проверка, ротирано proxy, пълен браузър) и спира на първото стъпало, което връща response, приет от вашите правила. При повтарящи се извиквания към същия хост, вместо това се възпроизвежда топла сесия, така че второто попадение е евтино.

Не настройвате повторни опити, размери на пулове или брой proxy сървъри. FourA ги научава за всеки хост.

Request Body

Параметър	Тип	Задължителен	По подразбиране	Описание
`url`	string	Да	-	Целеви URL
`method`	string	Не	`"GET"`	HTTP метод
`headers`	[string, string][]	Не	-	Потребителски headers като двойки [име, стойност]
`data`	any	Не	-	Request тяло за заявки, различни от GET
`validate`	object	Не	-	Критерии за успех, същата структура като `validate` на Single Request (вижте по-долу). Кажете на auto как изглежда реална страница, за да може да различи съдържание от challenge страница.
`returnSession`	boolean	Не	`true`	Включете печелившата сесия (`proxy`, `cookies`, `userAgent`) в response, за да можете да я възпроизведете чрез `/api/single/` или `/api/browser/`.
`forceProxy`	boolean	Не	`true`	Винаги маршрутизирайте през ротиращо proxy. Задайте `false`, за да позволите по-евтиния директен път, когато целта го позволява (някои защити са по-строги към proxy трафика).
`timeout_ms`	integer	Не	`120000`	Общ бюджет от време за цялото извикване, в милисекунди. Всички подопити се изпълняват в рамките на този бюджет. Минимум `5000`, максимум `180000`.
`ignoreProxies`	string[]	Не	-	Proxy ID-та, които да се избягват при всеки подопит. Използвайте ID-та, върнати от предишни `/api/auto/` или `/api/proxy/` responses.
`followRedirects`	integer	Не	`5`	Максимален брой пренасочвания за следване по евтините стъпала на стълбата. `0` за деактивиране. Максимум `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..."
  }
}

Поле	Тип	Описание
`status`	число	HTTP статус от целта.
`data`	string или object	Тяло на response.
`headers`	array или object	Целеви response headers. Single и proxy стъпките връщат array от header обекти за всеки хоп; browser стъпките връщат плосък обект.
`meta.rung`	string	Коя стъпка от стълбицата е доставила response. Едно от: `probe` (евтин директен request), `proxy` (ротиращ proxy), `browser` (пълно рендиране в браузър), `cache` (възпроизведена топла сесия) или `fail` (нито една стъпка не е дала приет response).
`meta.solved`	boolean	Дали bot challenge е решено по време на това извикване.
`meta.attempts`	число	Направени под-опити преди успех.
`meta.credits`	число	Общо изразходвани кредити за това извикване. Съвпада с `X-FourA-Credits`.
`session.proxy`	string	Кодирано ID на proxy, което е доставило response. Използвайте го отново при Single или Browser request. Налично, когато `returnSession` е `true`.
`session.cookies`	array	Cookies от печелившия опит. Налично, когато `returnSession` е `true`.
`session.userAgent`	string	User-Agent, използван при печелившия опит. Наличен, когато `returnSession` е `true`.
`error`	string	Съобщение за грешка, ако извикването е неуспешно.

Пример

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

Бележки

Auto е координатор. Той извиква вътрешно Single, Proxy или Browser и препраща вашия API ключ към всяко под-извикване. Всяко под-извикване се появява във вашия Журнал на активността; външното /api/auto/ извикване не добавя отделен ред за таксуване.
Подайте validate.data.accept с подниз, който се съдържа само в реалната страница. Без него auto не може да различи реално 200 от междинна страница с предизвикателство, върната със статус 200.
timeout_ms ограничава цялото извикване. Едно първоначално (cold) заявяване към защитен сайт може да отнеме десетки секунди; преизползваните (warm) сесии обикновено приключват за под секунда.

Single заявка

POST /api/single/

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

Тяло на заявката

Параметър	Тип	Задължителен	По подразбиране	Описание
`method`	string	Да	-	HTTP метод: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
`url`	string	Да	-	Целеви URL. Използвайте `{ts}` навсякъде в URL адреса, за да вмъкнете текущото времево клеймо за избягване на кеширането.
`headers`	[string, string][]	Не	-	Потребителски headers като двойки [име, стойност]
`unblocker`	boolean	Не	`true`	Изпращане на реалистични браузърски headers (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Включено по подразбиране. Задайте `false`, за да изпратите обикновен клиентски подпис.
`timeout_ms`	number	Не	15000	Общо време за изчакване в ms (макс: 120000)
`connect_timeout_ms`	number	Не	5000	Време за изчакване на връзката в ms
`accept_timeout_ms`	number	Не	5000	Време за изчакване за приемане в ms (време за изчакване за приемане на връзката)
`server_response_timeout_ms`	number	Не	15000	Време за изчакване на сървърен response в ms (време за изчакване за първия байт)
`dns_cache_timeout_sec`	number	Не	120	DNS кеш TTL в секунди (макс: 240)
`followRedirects`	number	Не	disabled	Максимален брой пренасочвания за следване (0-20). Пропуснете, за да деактивирате.
`tryJsonData`	boolean	Не	false	Парсване на response body като JSON, ако е възможно
`returnBuffer`	boolean	Не	false	Връщане на суров буфер вместо декодиран string
`data`	any	Не	-	Request body (string или обект, автоматично сериализиран в JSON)
`proxy`	string	Не	-	Proxy ID от предишен response, за да се фиксира същият изход. Подайте непрозрачния string обратно буквално. Суров proxy адрес се отхвърля с `400 Invalid proxy format`.
`browser`	string	Не	Chrome	Браузър за представяне: Chrome, Edge, Safari, Firefox или Tor. Вижте Браузърни профили.
`os`	string	Не	-	Операционна система за представяне: Windows, macOS, Android или iOS. Име на фамилия приема всяка от нейните версии.
`version`	string	Не	newest	Версия на браузъра за представяне, както е посочено в каталога. Най-новото съвпадение печели, когато няколко отговарят на условието.
`profile`	string	Не	-	Точен profile id от `GET /api/profiles`, вместо трите полета по-горе.
`validate`	object	Не	-	Правила за валидиране на response (вижте по-долу)

Браузърни профили

По подразбиране даден request представя най-новия Google Chrome. Някои цели приемат един браузър и отхвърлят друг, така че browser, os и version стесняват каталога от измерени профили, а profile избира един по id.

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

Правила:

Изборът изисква unblocker (включено по подразбиране). При изключен unblocker не се изпращат browser headers, така че request се отхвърля, вместо да се приложи частично.
Когато няколко профила съвпадат, най-новата версия печели.
Комбинация, която каталогът не може да предостави, връща грешка с посочване на наличното. Този request никога не се изпраща като различен браузър.
Същите четири полета са налични в обекта request на POST /proxy/.

GET /api/profiles връща пълния каталог и не изисква API ключ:

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

osFamily е стойността за филтриране при изграждане на селектор; os пази името на версията за показване.

Правила за валидиране

Обектът validate ви позволява да дефинирате условия за успех и неуспех. Ако условие fail е изпълнено, заявката се третира като неуспешна. Ако са зададени условия accept, само съвпадащите отговори се третират като успешни.

{
  "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 статус кодове за приемане
`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, които предизвикват грешка

Пример

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

Отговор:

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

Когато целта стартира проверка за ботове по пътя към тялото, отговорът съдържа и обект defense, който указва доставчика и дали проверката е премината:

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

Поле	Тип	Описание
`status`	число	HTTP код на състоянието от целта
`headers`	масив	По един обект за всяка стъпка на пренасочване. Всеки има поле `result` със статусния ред плюс всеки response header. Многостойностните header-и (`Set-Cookie`, `Link`, `WWW-Authenticate`) се връщат като масиви от низове.
`data`	низ/обект	Тяло на response (JSON, ако `tryJsonData` е true)
`total_time`	число	Общо време за request в секунди
`proxy`	низ	Кодирано ID на proxy сървъра, през който е минал даденият request (само когато към request-а е подаден `proxy`). Използвайте го отново при последващо извикване, за да фиксирате същия изход.
`defense`	обект	Присъства само когато целта е изпълнила проверка за ботове върху този request. `defense.solved` показва дали проверката е премината. Вижте Защити срещу ботове за всяко поле и пълния списък с доставчици.
`error`	низ	Съобщение за грешка, ако даденият request е неуспешен

Proxy Request

POST /api/proxy/

Насочва вашия request през ротиращи proxy сървъри с автоматичен повторен опит при неуспех. По желание ограничете избора до набор от видими за целта изходни държави.

Тяло на request

Параметър	Тип	Задължителен	По подразбиране	Описание
`request`	обект	Да	-	Единично тяло на request (същите полета като Single Request по-горе)
`timeout_ms`	число	Не	45000	Общо време за изчакване за всички опити в ms (макс: 120000)
`maxTries`	число	Не	5	Максимален брой опити за ротация на proxy (макс: 90)
`ignoreProxies`	string[]	Не	-	ID-та на proxy сървъри, които да бъдат изключени от ротацията (използвайте ID-та, върнати от предишни response-и)
`exitCountries`	string[]	Не	-	Строг списък с разрешени двубуквени кодове на държави, видими за целта (напр. `["CZ", "GB"]`). Стойностите се изчистват от празни места, преобразуват се в главни букви и се премахват дубликатите. Proxy сървърите с неизвестни изходи се изключват и даденият request никога не преминава към непоискана държава.

Ограничаване по exitCountries

Изборът използва най-новите налични метаданни за видимите за целта държави, които обикновено се опресняват на около десет минути. Това не е търсене на геолокация в реално време по време на request. Не правете извод за обслужващата държава от адреса на хоста на proxy сървъра.

Ако в текущия пул няма съвпадение за заявените държави, даденият response връща HTTP 200 с обвивка за грешка:

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

Запазете заявения обхват и опитайте отново по-късно. Променете или го разширете само когато изискването за държава на вашия работен процес се промени изрично.

Пример

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

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",
  "exitCountry": "CZ",
  "total": 2.341
}

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

Всички полета на отговора за заявка Single също са включени, сред тях и defense: опит с proxy, който е срещнал проверка за бот, го отчита по същия начин като Single.

Browser Request

POST /api/browser/

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

Request Body

Параметър	Тип	Задължителен	По подразбиране	Описание
`url`	string	Да	-	Целеви URL адрес
`headers`	object	Не	-	Персонализирани заглавки (headers) като двойки ключ-стойност
`cookies`	array	Не	-	Бисквитки (cookies) за задаване: `[{name, value, domain?}]`
`userAgent`	string	Не	-	Персонализиран низ за User-Agent
`unblocker`	boolean	Не	`true`	Автоматично решаване на често срещани CAPTCHA предизвикателства за ботове (като Cloudflare clearance) по време на зареждане на страницата. Включено по подразбиране. Задайте `false`, за да се рендира това, което страницата връща, включително CAPTCHA страници, без опит за решаване.
`proxy`	string	Не	-	Proxy ID от предишен отговор за запазване на същия изходен възел. Подайте обратно непрозрачния низ точно както е. Подаването на суров адрес на proxy ще бъде отхвърлено с `400 Invalid proxy format`.
`timeout_ms`	number	Не	30000	Време за изчакване при зареждане на страница в ms (макс: 120000)
`checkStatus`	number	Не	-	Очакван HTTP статус (заявката се проваля, ако е различен)
`checkText`	string	Не	-	Текст, който трябва да присъства в рендираната страница

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

Отговор:

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

Поле	Тип	Описание
`status`	number	HTTP status code от целта
`headers`	object	Response headers
`body`	string or object	Напълно рендирано съдържание на страницата. String HTML, когато content-type е HTML; object, когато страницата е върнала JSON и е автоматично парсната.
`cookies`	array	Пълни cookie обекти от страницата. Всяко cookie включва `name`, `value`, `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite` и други свойства на cookie.
`userAgent`	string	Използван браузър User-Agent
`defenseSolved`	boolean	`true`, ако е срещната защита от ботове и е успешно преодоляна при това извикване. Липсва в противен случай. Определя цената от 15 срещу 30 кредита.
`defenses`	object	`present` изброява всеки vendor, разпознат по време на зареждането на страницата, `cleared` изброява тези, чието преодоляване крайната страница притежава. Един vendor може да се появи в `present` и никога в `cleared`. Вижте Anti-Bot Defenses.
`proxy`	string	Кодиран ID на проксито, през което е минала заявката (само когато `proxy` е подаден в заявката). Използвайте го повторно при последващи извиквания, за да запазите същия изход.
`error`	string	Съобщение за грешка, ако заявката е неуспешна

HTTP Status Codes

Код	Значение
200	Заявката е завършена (проверете вътрешния `status` за response от целта)
400	Невалиден body на заявката, параметри или IP на целта в частен/резервиран диапазон
401	Липсващ или невалиден API key
429	Превишен rate limit
500	Вътрешна грешка на сървъра
502	`Upstream unavailable`. FourA достигна своя двигател, но отговорът беше неизползваем. Опитайте отново.
503	Услугата е временно деактивирана или е достигнала капацитет, или `Backend service unavailable` докато двигателят се рестартира
504	`Upstream timeout`. Двигателят не завърши в рамките на времевия бюджет за тази заявка. Увеличете `timeout_ms` или опитайте отново.

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

Smart Fetch (Auto): Кога да оставите FourA да избере пътя вместо вас
Choosing the Right Endpoint: Кога да изберете ръчно Single, Proxy или Browser
Authentication: Управлявайте своите API keys
Error Handling: Справяйте се с грешките елегантно
Anti-Bot Defenses: Прочетете полето defense и възпроизведете преодоляване
Rate Limits: Разберете лимитите на заявките
Quick Start: Вашата първа заявка за 30 секунди

Обновено: 12 август 2026 г.