Справочник по 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" } }

Снимок и скриншот

Метод	Путь	Ключевые параметры	Назначение
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 (из снимка), либо 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	—	Ref элемента из снимка
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	Ref элемента
selector	string	CSS-селектор

POST /:profileId/drag

Перетащить от исходного элемента к целевому. Каждая сторона принимает ref или селектор.

Поле	Тип	Описание
startRef	string	Ref исходного элемента
startSelector	string	CSS-селектор источника
endRef	string	Ref целевого элемента
endSelector	string	CSS-селектор цели

POST /:profileId/scroll-to

Прокрутить элемент в зону видимости.

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

Выпадающие списки

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

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

POST /:profileId/select-option

Выбрать опцию(и) в нативном элементе <select>.

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

Response

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

POST /:profileId/select-combobox

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

Поле	Тип	Обязательный	Описание
ref / selector	string	да	Целевой элемент combobox
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 для поиска центров, затем мышь + клавиатура). Один вызов может заполнить целую форму, выбрать значения в combobox и кликнуть отправку — заменяя множество обращений. Combobox-ы открываются, кликается соответствующая опция, и выбор проверяется (с одной автоматической повторной попыткой).

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

Каждая запись в fields:

Поле	Тип	По умолчанию	Описание
selector	string	обязательный	CSS-селектор для элемента
value	string	обязательный	Значение для ввода или текст опции для выбора
type	"text" | "combobox"	"text"	Вид поля
nth	number	0	Индекс с отсчётом от 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" } }

Ожидание

Метод	Путь	Ключевые параметры	Назначение
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}'

Диалог

Метод	Путь	Ключевые параметры	Назначение
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	Снимок или скриншот завершились с ошибкой.
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	Пакетный запрос не удалось выполнить (например, профиль не запущен).

Следующие шаги

См. Лучшие практики для устойчивого построения последовательностей и руководства по автоматизации для полных сквозных сценариев, которые сочетают эти эндпоинты.