Запуск і робота з профілями

Перш ніж агент зможе автоматизувати сторінку, цільовий профіль має бути запущений. Ця сторінка проводить вас через весь життєвий цикл за допомогою API локального демона — отримання списку профілів, створення (з відбитком та проксі), запуск, опитування статусу та зупинка — а також пояснює помилку PROFILE_NOT_RUNNING, на яку ви наразитесь, якщо пропустите крок запуску.

Усі запити йдуть до локального демона. API керування профілями розташоване під http://localhost:7891/api; API автоматизації (навігація, кліки, введення тексту, знімок) розташоване під http://localhost:7891/api/automation/:profileId/<action> і описане в розділах HTTP API та Довідник API.

Конверт відповіді

Кожен ендпоінт демона повертає однаковий JSON-конверт, тож ваш код може розгалужуватись за полем ok, перш ніж читати data:

Success

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

Failure

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

Деякі ендпоінти повертають "data": null при успіху (запуск, зупинка, розблокування). Перевіряйте ok, а не форму data.

Значення статусу профілю

Профіль повідомляє один статус виконання. Автоматизація працює лише поки профіль у статусі running.

Статус	Значення
idle	Створений, але не запущений. Процес браузера не працює.
launching	Запуск прийнято; браузер стартує та синхронізує стан віддаленої сесії.
running	Браузер запущено. Ендпоінти автоматизації працюють.
stopping	Зупинку прийнято; куки та вкладки синхронізуються перед закриттям браузера.
locked	Профіль відкрито на іншому пристрої. Ви не можете запустити його тут, доки блокування не буде знято.

Заувага

launch — асинхронний. Успішний запуск одразу повертає 202 Accepted, ще до того, як браузер завершить старт. Опитуйте ендпоінт статусу, доки він не покаже running, перш ніж надсилати дії автоматизації — див. Дочекайтеся, поки профіль не запущено.

Список профілів

Повертає кожен профіль із його поточним статусом виконання. Для читання списку ліцензія не потрібна.

List profiles with status

curl -s localhost:7891/api/profiles | jq '.data[] | {id, name, status}'

Якщо ви — зовнішній агент, якому не передали конкретний ID профілю, отримайте список профілів і дайте оператору обрати один. Щойно у вас з’явиться ID, збережіть його в змінній середовища на весь подальший потік:

Pin the profile ID

PROFILE=<profile-id>

Створення профілю

Створення профілю потребує активної ліцензії. Тіло запиту несе назву профілю, проксі, відбиток та геолокацію. При успіху демон повертає 201 з новим профілем і status: "idle".

Create a profile (fingerprint + proxy)

curl -s localhost:7891/api/profiles -X POST \
  -H 'Content-Type: application/json' -d '{
    "name": "My Profile",
    "proxy": {"type": "none"},
    "fingerprint": {
      "os": "windows",
      "userAgent": "Mozilla/5.0 ...",
      "screenWidth": 1920, "screenHeight": 1080,
      "language": "en-US", "timezone": "America/New_York",
      "webrtc": "fake"
    },
    "geolocation": {"enabled": false}
  }'

Поле webrtc приймає real, fake або disabled. Щоб під’єднати проксі замість {"type": "none"}, передайте деталі підключення в об’єкті proxy — див. Налаштування проксі. Повний перелік полів відбитка та їх відповідність браузеру див. у Параметри відбитка.

Нехай сервер побудує відбиток

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

Generate a realistic fingerprint

curl -s localhost:7891/api/generate-fingerprint -X POST \
  -H 'Content-Type: application/json' -d '{"os": "windows"}' | jq .data

Деталі див. у Генерація відбитка.

Оновлення профілю

Під час оновлення всі поля необов’язкові — надсилайте лише те, що хочете змінити. Демон повертає оновлений профіль із його поточним статусом.

Rename and tag a profile

curl -s localhost:7891/api/profiles/$PROFILE -X PATCH \
  -H 'Content-Type: application/json' -d '{"name": "New Name", "tags": ["work"]}'

Запуск профілю

Запуск стартує процес браузера для профілю. Він асинхронний: при успіху ви отримуєте 202 Accepted з "data": null, а статус переходить у launching.

Launch a profile

curl -s localhost:7891/api/profiles/$PROFILE/launch -X POST

Перед прийняттям запуск проходить дві перевірки:

1. Активна ліцензія. Немає активної підписки → 403 з NO_SUBSCRIPTION (акаунт ніколи не оплачувався) або LICENSE_EXPIRED (підписка прострочена). Тарифи лише платні — див. Тарифи та ціни.
2. Вільний слот одночасного запуску. Ваш тариф обмежує, скільки профілів можуть працювати одночасно — Starter 3, Pro 40, Agency 300. Якщо ви вже досягли ліміту, запуск повертає 403 CONCURRENT_LIMIT_REACHED; спершу зупиніть запущений профіль або підвищте тариф.

Код помилки	HTTP	Значення
NO_SUBSCRIPTION	403	Акаунт ніколи не мав платного тарифу.
LICENSE_EXPIRED	403	Підписка прострочена.
CONCURRENT_LIMIT_REACHED	403	Усі слоти одночасного запуску вашого тарифу зайняті.
PROFILE_NOT_FOUND	404	Профілю з таким ID не існує.
PROFILE_LOCKED	409	Профіль відкрито на іншому пристрої.
UNAUTHORIZED	401	Токени сесії демона відсутні або прострочені; увійдіть через застосунок.

Ліміт одночасних, а не загальної кількості профілів

Ліміт запуску рахує профілі, що запущені зараз, а не скільки ви створили. Ви можете володіти 40 профілями на Pro і запускати лише кілька одночасно — але не можете перевищити кількість живих браузерів за тарифом. Див. Стани ліцензії.

Дочекайтеся, поки профіль не запущено

Оскільки запуск повертається ще до готовності браузера, опитуйте ендпоінт статусу, доки він не покаже running. Не надсилайте дії автоматизації під час launching.

Poll status after launch

curl -s localhost:7891/api/profiles/$PROFILE/status | jq -r .data.status

Простий цикл очікування:

Launch, then wait for running

curl -s localhost:7891/api/profiles/$PROFILE/launch -X POST

until [ "$(curl -s localhost:7891/api/profiles/$PROFILE/status | jq -r .data.status)" = "running" ]; do
  sleep 1
done

Перевірка статусу

Ендпоінт статусу — єдине джерело правди щодо того, чи можна автоматизувати профіль. Він не потребує ліцензії й повертає відповідь миттєво.

Check a single profile's status

curl -s localhost:7891/api/profiles/$PROFILE/status | jq -r .data.status

Response

{ "ok": true, "data": { "status": "running" } }

Зупинка профілю

Зупинка закриває браузер. Перед виходом процесу демон синхронізує сесію — відкриті вкладки та будь-які змінені куки завантажуються на сервер, щоб наступний запуск відновився з місця, де ви зупинились. При успіху ви отримуєте "data": null, статус переходить у stopping, а потім назад у idle.

Stop a profile

curl -s localhost:7891/api/profiles/$PROFILE/stop -X POST

Зупинка синхронізує вашу сесію

Куки та відкриті вкладки зберігаються між циклами зупинки/запуску — саме це робить профіль стійкою ідентичністю, а не одноразовою сесією. Щоб почати запуск із чистої сесії без перезапуску, натомість очистіть куки на запущеному профілі (див. Куки). Докладніше про те, що зберігається, у розділі Синхронізація сесій.

PROFILE_NOT_RUNNING

Якщо ви викликаєте ендпоінт автоматизації (/api/automation/$PROFILE/navigate, /snapshot, /click, …) для профілю, який не у статусі running, демон відповідає 404 з кодом помилки PROFILE_NOT_RUNNING.

Automating a non-launched profile

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

Це найпоширеніша помилка під час першого запуску: профіль існує, але його браузер так і не стартував (або вже був зупинений). Ендпоінти кук поводяться так само — GET/POST/DELETE /api/profiles/$PROFILE/cookies працюють лише поки профіль запущено.

Як цього уникнути:

• Запускайте профіль (POST /api/profiles/$PROFILE/launch) перед будь-яким викликом автоматизації.
• Сприймайте 202 від запуску як «прийнято, не готово». Опитуйте GET /api/profiles/$PROFILE/status, доки він не поверне running — автоматизація під час launching все одно може провалитись.
• Перевіряйте статус повторно, якщо тривалий потік зависає: збій браузера або зупинка з іншого пристрою виводять профіль зі стану running.
• Працюйте строго в межах профілю, який вам надав оператор. Не запускайте, не зупиняйте й не перемикайтеся на інший профіль, щоб «виправити» невідповідність — якщо вказаний профіль не запущено або він не підходить для задачі, зупиніться й запитайте оператора.

Наскрізний життєвий цикл

Повний потік створення → запуск → автоматизація → зупинка:

Full lifecycle

# 0. Pin the profile ID (or create one first)
PROFILE=<profile-id>

# 1. Launch (async — returns 202)
curl -s localhost:7891/api/profiles/$PROFILE/launch -X POST

# 2. Wait until the browser is up
until [ "$(curl -s localhost:7891/api/profiles/$PROFILE/status | jq -r .data.status)" = "running" ]; do
  sleep 1
done

# 3. Automate (now safe — no PROFILE_NOT_RUNNING)
curl -s localhost:7891/api/automation/$PROFILE/navigate -X POST \
  -H 'Content-Type: application/json' -d '{"url":"https://example.com"}'

# 4. Stop — syncs cookies & tabs before closing
curl -s localhost:7891/api/profiles/$PROFILE/stop -X POST

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

• HTTP API — ендпоінти дій автоматизації, коли профіль запущено.
• Довідник API — повний каталог ендпоінтів та дій.
• Найкращі практики — батчинг, знімки та правила стелсу.
• Встановлення агентного скіла — готові інструкції для AI-агента.