Довідник API

Це повний довідник API автоматизації Santiago: набір ендпоінтів, які локальний демон надає для керування запущеним профілем браузера. Кожен ендпоінт керує реальною сторінкою на базі Playwright усередині антидетект-браузера, тож той самий відбиток і проксі, які ви налаштували для профілю, застосовуються до кожної дії.

Про налаштування та загальне використання дивіться Основи HTTP API та Найкращі практики. Готові наскрізні сценарії дивіться у посібниках з автоматизації.

Базовий URL і домовленості

Усі ендпоінти автоматизації працюють через локальний демон і спрямовані на один запущений профіль за його id:

http://localhost:7891/api/automation/:profileId/<action>

Демон слухає лише на http://localhost:7891. Замініть :profileId на id запущеного профілю — спочатку запустіть його (дивіться Запуск профілів для автоматизації). Виклики до профілю, який не запущено, повертають 404 PROFILE_NOT_RUNNING.

Націлювання на елемент

Більшість ендпоінтів взаємодії приймають або ref (id елемента зі snapshot), або selector (CSS-селектор). Потрібен принаймні один. Робочий процес із ref найнадійніший: зробіть snapshot, прочитайте id [ref=eN], потім дійте на них.

Формат відповіді

Кожен ендпоінт повертає однаковий конверт.

Success

{ "ok": true, "data": { ... } }

Error

{ "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }

Дії, які лише завершуються успіхом або помилкою (click, hover, type, рухи миші тощо), повертають { "ok": true } без data. Ендпоінти, які видають значення (snapshot, screenshot, navigate, tabs, evaluate, dialog), заповнюють data.

Таймаути

Константа	Значення	Стосується
Таймаут навігації	30 с	navigate, back, forward, reload, відкриття вкладки з URL
Таймаут дії	2 с	Ендпоінти взаємодії (click, hover, type, select-option, scroll-to, скріншоти елемента)
Таймаут очікування	15 с (за замовчуванням)	Ендпоінт wait; перевизначається полем timeout

Чому взаємодії падають швидко

Таймаут дії навмисно короткий (2 с). На анімованих чи нестабільних сторінках довге очікування прокрутки до елемента — марна трата часу. Якщо дія на основі локатора перевищує таймаут, перейдіть до дій миші на основі координат або fill-page.

Навігація

Метод	Шлях	Ключові параметри	Призначення
POST	/:profileId/navigate	url (обов’язковий)	Перейти за URL.
POST	/:profileId/back	немає	Перейти назад в історії.
POST	/:profileId/forward	немає	Перейти вперед в історії.
POST	/:profileId/reload	немає	Перезавантажити поточну сторінку.

Усі чотири повертають { ok, data: { url, title } } з підсумковими URL і заголовком сторінки.

Navigate to a URL

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/navigate \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'

Response

{ "ok": true, "data": { "url": "https://example.com/", "title": "Example Domain" } }

Snapshot і screenshot

Метод	Шлях	Ключові параметри	Призначення
POST	/:profileId/snapshot	selector, depth	Захопити дерево доступності сторінки й отримати посилання на елементи.
POST	/:profileId/screenshot	fullPage, ref, selector	Зробити скріншот PNG у кодуванні base64.

POST /:profileId/snapshot

Захоплює дерево доступності поточної сторінки. Це основний спосіб «побачити» структуру сторінки та отримати id [ref=eN] для подальших дій.

Поле	Тип	За замовчуванням	Опис
selector	string	—	CSS-селектор, щоб обмежити знімок піддеревом одного елемента
depth	number	—	Обмежити глибину дерева

Snapshot the page

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/snapshot \
  -H 'Content-Type: application/json' \
  -d '{}'

Response

{ "ok": true, "data": { "snapshot": "- heading \"Example\" [ref=e1]\n- textbox \"Email\" [ref=e2]\n..." } }

POST /:profileId/screenshot

Робить скріншот. Повертає рядок PNG у кодуванні base64. Передайте ref або selector, щоб захопити один елемент; інакше захоплюється область перегляду (або повна сторінка).

Поле	Тип	За замовчуванням	Опис
fullPage	boolean	false	Захопити всю прокручувану сторінку (ігнорується, коли задано ref/selector)
ref	string	—	Скріншот конкретного елемента за ref
selector	string	—	Скріншот конкретного елемента за CSS-селектором

Response

{ "ok": true, "data": { "screenshot": "iVBORw0KGgo..." } }

Клік і взаємодія

Усі наведені нижче ендпоінти взаємодії приймають або ref (зі snapshot), або selector (CSS); потрібен принаймні один.

Метод	Шлях	Ключові параметри	Призначення
POST	/:profileId/click	ref/selector, button, doubleClick, modifiers	Клікнути по елементу.
POST	/:profileId/hover	ref/selector	Навести курсор на елемент.
POST	/:profileId/drag	startRef/startSelector, endRef/endSelector	Перетягнути й відпустити між двома елементами.
POST	/:profileId/scroll-to	ref/selector	Прокрутити сторінку так, щоб елемент став видимим.

POST /:profileId/click

Поле	Тип	За замовчуванням	Опис
ref	string	—	Посилання на елемент зі snapshot
selector	string	—	CSS-селектор
button	"left" | "right" | "middle"	"left"	Кнопка миші
doubleClick	boolean	false	Подвійний клік
modifiers	string[]	—	"Alt", "Control", "ControlOrMeta", "Meta", "Shift"

Click by ref

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/click \
  -H 'Content-Type: application/json' \
  -d '{"ref": "e20"}'

POST /:profileId/hover

Поле	Тип	Опис
ref	string	Посилання на елемент
selector	string	CSS-селектор

POST /:profileId/drag

Перетягнути від елемента-джерела до цільового елемента. Кожна сторона приймає ref або селектор.

Поле	Тип	Опис
startRef	string	Посилання на елемент-джерело
startSelector	string	CSS-селектор джерела
endRef	string	Посилання на цільовий елемент
endSelector	string	CSS-селектор цілі

POST /:profileId/scroll-to

Прокрутити сторінку так, щоб елемент став видимим.

Поле	Тип	Опис
ref	string	Посилання на елемент
selector	string	CSS-селектор

Випадні списки

Два ендпоінти охоплюють два види випадних списків, які ви зустрічаєте в інтернеті: нативні елементи <select> та кастомні віджети комбобокса ARIA.

Метод	Шлях	Ключові параметри	Призначення
POST	/:profileId/select-option	ref/selector, values (обов’язковий)	Вибрати опцію(ї) в нативному <select>.
POST	/:profileId/select-combobox	ref/selector, value (обов’язковий), optionSelector	Розумний вибір для кастомних випадних списків комбобокса ARIA.

POST /:profileId/select-option

Вибрати опцію(ї) в нативному елементі <select>.

Поле	Тип	Обов’язковий	Опис
ref / selector	string	так	Цільовий елемент <select>
values	string[]	так	Значення для вибору

Response

{ "ok": true, "data": { "selected": ["value1"] } }

POST /:profileId/select-combobox

Розумний вибір для випадних списків комбобокса ARIA — кастомних віджетів <div role="combobox">, які використовують багато сучасних вебзастосунків. Він виконує всю послідовність: клік для відкриття, читання aria-controls для пошуку listbox, очікування, доки listbox стане видимим (5 с), пошук [role="option"], що відповідає value (або вашому optionSelector), і клік по ньому.

Поле	Тип	Обов’язковий	Опис
ref / selector	string	так	Цільовий елемент комбобокса
value	string	так	Текст опції для вибору
optionSelector	string	—	Кастомний CSS-селектор для опції (перевизначає зіставлення за текстом)

Select a custom-dropdown option

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/select-combobox \
  -H 'Content-Type: application/json' \
  -d '{"ref": "e5", "value": "March"}'

Response

{ "ok": true, "data": { "selected": "March" } }

Введення тексту та клавіатура

Метод	Шлях	Ключові параметри	Призначення
POST	/:profileId/type	ref/selector, text (обов’язковий)	Очистити поле та ввести значення (людиноподібна затримка між клавішами).
POST	/:profileId/press-sequentially	ref/selector, text (обов’язковий), delay	Вводити текст клавіша за клавішею без попереднього очищення.
POST	/:profileId/press-key	key (обов’язковий), modifiers	Натиснути клавішу або комбінацію клавіш.
POST	/:profileId/fill-form	fields (обов’язковий)	Заповнити кілька полів одночасно (на основі ref/selector).
POST	/:profileId/fill-page	fields, submit, waitAfterSubmit	Високорівневе заповнення форми на основі координат + опційне надсилання.

POST /:profileId/type

Сфокусувати поле, очистити його наявне значення, потім ввести нове значення з людиноподібною затримкою між клавішами.

Поле	Тип	Обов’язковий	Опис
ref / selector	string	так	Цільовий елемент введення
text	string	так	Текст для введення

Type into a field

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/type \
  -H 'Content-Type: application/json' \
  -d '{"ref": "e2", "text": "jane.doe@example.com"}'

POST /:profileId/press-sequentially

Вводить текст клавіша за клавішею в цільовий елемент (без попереднього очищення). Корисно для полів, які реагують на кожне натискання.

Поле	Тип	За замовчуванням	Опис
ref / selector	string	обов’язковий	Цільовий елемент
text	string	обов’язковий	Текст для введення
delay	number	50	Затримка між клавішами в мс

POST /:profileId/press-key

Натиснути одну клавішу клавіатури або комбінацію. З modifiers демон об’єднує їх в акорд (наприклад, Control+a).

Поле	Тип	Опис
key	string	Назва клавіші: "Enter", "Tab", "Escape", "a", "F1" тощо.
modifiers	string[]	"Alt", "Control", "ControlOrMeta", "Meta", "Shift"

Submit a form with Enter

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/press-key \
  -H 'Content-Type: application/json' \
  -d '{"key": "Enter"}'

POST /:profileId/fill-form

Заповнює кілька полів форми за один виклик. Кожне поле заповнюється через локатор Playwright (клік, очищення, введення); якщо це не вдається, демон переходить до стратегії на основі координат (визначення обмежувального прямокутника, клік по центру, виділити все, видалити, ввести). Результат кожного поля повідомляє використану стратегію strategy (locator або coords).

Поле	Тип	Обов’язковий	Опис
fields	array	так	[{ ref?, selector?, value }]

Fill several fields

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/fill-form \
  -H 'Content-Type: application/json' \
  -d '{
    "fields": [
      {"ref": "e2", "value": "Jane Doe"},
      {"selector": "#email", "value": "jane@example.com"}
    ]
  }'

Response

{
  "ok": true,
  "data": {
    "results": [
      { "ref": "e1", "ok": true },
      { "selector": "#email", "ok": true },
      { "ref": "e3", "ok": false, "error": "Element not found" }
    ]
  }
}

POST /:profileId/fill-page

Високорівневе заповнення на основі координат, яке повністю обходить локатори Playwright (evaluate для пошуку центрів, потім миша + клавіатура). Один виклик може заповнити цілу форму, вибрати комбобокси та клікнути кнопку надсилання — замінюючи багато звернень. Комбобокси відкриваються, клікається відповідна опція, а вибір перевіряється (з однією автоматичною повторною спробою).

Поле	Тип	За замовчуванням	Опис
fields	array	—	Масив об’єктів полів (дивіться нижче)
submit	object	—	{ selector?, text? } кнопка надсилання (спершу selector, потім запасний варіант text)
waitAfterSubmit	number	2000	Мілісекунди очікування після кліку надсилання

Кожен запис у fields:

Поле	Тип	За замовчуванням	Опис
selector	string	обов’язковий	CSS-селектор елемента
value	string	обов’язковий	Значення для введення або текст опції для вибору
type	"text" | "combobox"	"text"	Вид поля
nth	number	0	Індекс із нуля, коли селектор збігається з кількома елементами
optionSelector	string	li[role=option]	CSS для елементів опцій (лише для combobox)

Потрібен принаймні один із fields або submit (інакше 400 BAD_REQUEST).

Fill and submit a form in one call

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/fill-page \
  -H 'Content-Type: application/json' \
  -d '{
    "fields": [
      {"selector": "#firstName", "value": "Jane"},
      {"selector": "#month", "value": "March", "type": "combobox"}
    ],
    "submit": {"text": "Submit"},
    "waitAfterSubmit": 3000
  }'

Response

{
  "ok": true,
  "data": {
    "results": [
      { "selector": "#firstName", "type": "text", "ok": true },
      { "selector": "#month", "type": "combobox", "ok": true, "selectedValue": "March" }
    ],
    "submit": { "ok": true, "url": "https://example.com/welcome" }
  }
}

Миша (на основі координат)

Низькорівневе керування мишею за координатами області перегляду. Використовуйте це, коли взаємодія на основі локатора заблокована або ненадійна.

Метод	Шлях	Ключові параметри	Призначення
POST	/:profileId/mouse/move	x, y (обов’язкові)	Перемістити курсор у точку.
POST	/:profileId/mouse/click	x, y (обов’язкові), button	Клікнути в точці.
POST	/:profileId/mouse/down	button	Натиснути кнопку миші.
POST	/:profileId/mouse/up	button	Відпустити кнопку миші.
POST	/:profileId/mouse/wheel	deltaX, deltaY	Прокрутити колесом.

POST /:profileId/mouse/move

Поле	Тип	Обов’язковий
x	number	так
y	number	так

POST /:profileId/mouse/click

Поле	Тип	За замовчуванням
x	number	обов’язковий
y	number	обов’язковий
button	"left" | "right" | "middle"	"left"

POST /:profileId/mouse/down та /:profileId/mouse/up

Поле	Тип	За замовчуванням
button	"left" | "right" | "middle"	"left"

POST /:profileId/mouse/wheel

Поле	Тип	За замовчуванням	Опис
deltaX	number	0	Горизонтальна прокрутка
deltaY	number	0	Вертикальна прокрутка (додатне = вниз)

Click at a coordinate

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/mouse/click \
  -H 'Content-Type: application/json' \
  -d '{"x": 480, "y": 320}'

Вкладки

Метод	Шлях	Ключові параметри	Призначення
GET	/:profileId/tabs	немає	Перелічити відкриті вкладки.
POST	/:profileId/tabs/new	url	Відкрити нову вкладку (порожню, якщо url пропущено).
POST	/:profileId/tabs/select	index (обов’язковий)	Перемкнутися на вкладку за індексом.
POST	/:profileId/tabs/close	index	Закрити вкладку (за замовчуванням останню; не можна закрити єдину залишену вкладку).

GET /:profileId/tabs

List tabs

curl http://localhost:7891/api/automation/$PROFILE_ID/tabs

Response

{ "ok": true, "data": { "tabs": [{ "index": 0, "url": "https://...", "title": "..." }] } }

POST /:profileId/tabs/new

Поле	Тип	За замовчуванням	Опис
url	string	—	URL для відкриття (порожня вкладка, якщо пропущено)

Повертає { ok, data: { index, url, title } }.

POST /:profileId/tabs/select

Поле	Тип	Обов’язковий
index	number	так

Повертає { ok, data: { index, url, title } }. Індекс поза діапазоном повертає 400 BAD_REQUEST.

POST /:profileId/tabs/close

Поле	Тип	За замовчуванням	Опис
index	number	остання вкладка	Індекс вкладки для закриття

Повертає { ok, data: { closedIndex } }. Закриття єдиної залишеної вкладки повертає 400 LAST_TAB — натомість зупиніть профіль.

Evaluate

Метод	Шлях	Ключові параметри	Призначення
POST	/:profileId/evaluate	code (обов’язковий)	Виконати JavaScript у контексті сторінки й повернути результат.

POST /:profileId/evaluate

Поле	Тип	Обов’язковий
code	string	так

Read the document title from the page

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/evaluate \
  -H 'Content-Type: application/json' \
  -d '{"code": "document.title"}'

Response

{ "ok": true, "data": { "result": "Example Domain" } }

Wait

Метод	Шлях	Ключові параметри	Призначення
POST	/:profileId/wait	text, selector, state, timeout	Очікувати на стан елемента/тексту або фіксований час.

POST /:profileId/wait

Якщо ви передаєте selector або text, виклик очікує, доки цей елемент досягне state. Якщо ви не передаєте жодного, він просто очікує timeout мілісекунд.

Поле	Тип	За замовчуванням	Опис
text	string	—	Очікувати на появу цього тексту
selector	string	—	Очікувати на цей CSS-селектор
state	"visible" | "hidden" | "attached" | "detached"	"visible"	Цільовий стан
timeout	number	15000	Таймаут у мс. Без text/selector очікує цей час безумовно

Wait for an element to appear

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/wait \
  -H 'Content-Type: application/json' \
  -d '{"selector": "#dashboard", "state": "visible", "timeout": 20000}'

Dialog

Метод	Шлях	Ключові параметри	Призначення
POST	/:profileId/dialog	action (обов’язковий), promptText	Прийняти або відхилити очікуваний alert/confirm/prompt.

POST /:profileId/dialog

Демон відстежує нативні діалоги (alert, confirm, prompt) для кожного профілю в міру їх відкриття. Викличте цей ендпоінт, щоб обробити найстаріший очікуваний.

Поле	Тип	Обов’язковий	Опис
action	"accept" | "dismiss"	так	Прийняти або відхилити діалог
promptText	string	—	Текст для введення в діалогах prompt (використовується при accept)

Response

{ "ok": true, "data": { "type": "confirm", "message": "Are you sure?", "defaultValue": "" } }

Якщо немає очікуваного діалогу, виклик повертає 404 NO_DIALOG.

Пакетне виконання

Метод	Шлях	Ключові параметри	Призначення
POST	/:profileId/batch	actions (обов’язковий)	Виконати кілька дій за один HTTP-виклик з людиноподібним темпом.

POST /:profileId/batch

Виконує кілька дій послідовно в одному запиті. Демон вставляє випадкову затримку 80–250 мс між діями для людиноподібного темпу. Він зупиняється на першій помилці — решта дій пропускаються (тож вони ніколи не виконуються на застарілому стані).

Type, select, then click in one call

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/batch \
  -H 'Content-Type: application/json' \
  -d '{
    "actions": [
      {"action": "type", "ref": "e1", "text": "Jane Doe"},
      {"action": "select-combobox", "ref": "e5", "value": "March"},
      {"action": "click", "ref": "e20"}
    ]
  }'

Доступні дії та поля, які використовує кожна (так само, як і відповідний окремий ендпоінт):

Дія	Поля
click	ref/selector, button, doubleClick, modifiers
type	ref/selector, text
press-sequentially	ref/selector, text, delay
press-key	key, modifiers
select-option	ref/selector, values
select-combobox	ref/selector, value, optionSelector
hover	ref/selector
scroll-to	ref/selector
wait	text, selector, state, timeout
navigate	url
snapshot	selector, depth
screenshot	ref, selector, fullPage
evaluate	code

Response

{
  "ok": true,
  "data": {
    "results": [
      { "index": 0, "action": "type", "ok": true },
      { "index": 1, "action": "select-combobox", "ok": true, "data": { "selected": "March" } },
      { "index": 2, "action": "click", "ok": true }
    ]
  }
}

Порожній масив actions повертає 400 BAD_REQUEST.

Коди помилок

Код	Коли
PROFILE_NOT_RUNNING	id профілю не є запущеним профілем (HTTP 404).
BAD_REQUEST	Відсутні обов’язкові поля тіла або індекс вкладки поза діапазоном (HTTP 400).
LAST_TAB	Спроба закрити єдину залишену вкладку (HTTP 400).
NO_DIALOG	dialog викликано без очікуваного діалогу (HTTP 404).
NAVIGATE_FAILED	navigate / back / forward / reload не вдалися.
SNAPSHOT_FAILED / SCREENSHOT_FAILED	Snapshot або screenshot не вдалися.
CLICK_FAILED / HOVER_FAILED / DRAG_FAILED / SCROLL_FAILED	Відповідна взаємодія не вдалася (часто 2-секундний таймаут дії).
SELECT_FAILED / SELECT_COMBOBOX_FAILED	Вибір у випадному списку не вдався.
TYPE_FAILED / PRESS_SEQ_FAILED / KEY_PRESS_FAILED / FILL_FORM_FAILED / FILL_PAGE_FAILED	Введення тексту не вдалося.
MOUSE_FAILED	Дія миші за координатами не вдалася.
TABS_FAILED / TAB_NEW_FAILED / TAB_SELECT_FAILED / TAB_CLOSE_FAILED	Дія з вкладкою не вдалася.
EVALUATE_FAILED	Скрипт сторінки викинув виняток.
WAIT_FAILED	Умова очікування перевищила таймаут.
DIALOG_FAILED	Обробка діалогу не вдалася.
BATCH_FAILED	Пакетний запит не вдалося виконати (наприклад, профіль не запущено).

Наступні кроки

Дивіться Найкращі практики для стійкого впорядкування дій та посібники з автоматизації для повних наскрізних сценаріїв, що поєднують ці ендпоінти.