Автоматизация работы с Octo Browser через API — полное руководство

Что такое API

API (Application Programming Interface) — это программный интерфейс, способ, с помощью которого программы общаются между собой. Представьте, что вы в ресторане: вы делаете заказ, официант передает его на кухню и возвращает готовое блюдо. Точно так же ваша программа отправляет запрос через API и получает ответ от сервера Octo Browser.

HTTP-запросы

Для взаимодействия с API используются HTTP-запросы — сообщения, которые клиент отправляет серверу для запроса или передачи данных.

Основные HTTP-методы

Структура запроса

Каждый запрос состоит из нескольких частей:

• URL: куда отправлять запрос.

• Метод: что мы хотим сделать (GET, POST и т. д.).

• Заголовки (Headers): дополнительная информация о запросе (например, API-токен).  

• Тело запроса (Body): данные, которые мы отправляем (например, информация для нового профиля).

Давайте разберем создание профиля с использованием POST-запроса, Node.js и библиотеки Axios. Пример скрипта запроса:

const axios = require('axios');
const data = JSON.stringify({
  "title": "Test profile from api",
  "fingerprint": {
    "os": "win"
  }
});
const config = {
  method: 'post',
maxBodyLength: Infinity,
  url: 'https://app.octobrowser.net/api/v2/automation/profiles',
  headers: { 
    'Content-Type': 'application/json', 
    'X-Octo-Api-Token': '<GET_TOKEN_IN_CLIENT>'
  },
  data : data
};
axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

URL: 'https://app.octobrowser.net/api/v2/automation/profiles' (адрес API для работы с профилями).

Метод: 'post' (создать новый профиль).

Тело запроса (data): JSON-объект с обязательными данными (имя профиля и ОС).

Заголовки (headers): 

• Content-Type': 'application/json' — сообщает серверу, что данные в формате JSON. 

• 'X-Octo-Api-Token': '<GET_TOKEN_IN_CLIENT>' — уникальный API-токен (доступен в настройках мастер-аккаунта на подписке Base и выше).

После отправки запроса сервер всегда возвращает HTTP-ответ, который включает статус-код — трехзначное число, определяющее результат обработки запроса.

Ответы сервера

• Успешно (2xx):

{"success":true,"msg":"","data":{"uuid":"<profile_uuid>"},"code":null}

• Ошибки (4xx и 5xx):
  
  

  • 400 Bad Request — неверный синтаксис или отсутствует обязательный параметр.

  • 401 Unauthorized — неверный или отсутствующий API-токен.

  • 404 Not Found — URL не существует.

  • 429 Too Many Requests — превышен лимит запросов.

  • 500 Internal Server Error — ошибка сервера.

Блок .catch в скрипте помогает обработать эти ошибки.

Документация Octo Browser по API

В официальной документации по работе с API Octo Browser представлена структура запросов и примеры их использования:

• Меню слева — разделы: Profiles, Proxies, Local Client API, Teams и др.

• В центре — описание запроса: адрес (endpoint), метод (GET, POST и т. д.), параметры, заголовки и возможные варианты использования.

• Справа — готовые примеры запросов (Example Requests) и ответы сервера (Example Response).

• Выпадающее меню LANGUAGE — выбор языка программирования для примеров: Node.js, Python, Java, C#, PHP и др.

Работа с Public и Local API

Public API

• Удаленный интерфейс через интернет, не требует запуска клиента.

• Запросы выполняются по адресу: https://app.octobrowser.net.

• Лимиты зависят от подписки:

С помощью Public API можно:

• получать информацию о профилях;

• создавать, редактировать и удалять профили;

• работать с тегами, командами, прокси.

Пример запроса: создание профиля

POST https://app.octobrowser.net/api/v2/automation/profiles

Заголовок: X-Octo-Api-Token: <ВАШ_API_ТОКЕН>

Local API

• Работает локально, когда Octo Browser запущен на устройстве.

• Лимиты зависят от типа запроса: Start Profile — 1 запрос, One-time Profile — 4 запроса. Остальные запросы Local API не влияют на лимиты.

• Можно авторизоваться, запускать/останавливать профили, подключать библиотеки автоматизации.

• Запросы выполняются по адресу: http://localhost:58888 (58888 — порт локального HTTP-сервера).

Пример запроса: запуск профиля

POST http://localhost:58888/api/profiles/start

Заголовок: Content-Type: application/json и тело JSON с UUID и опциями.

Инструменты для отправки запросов

Postman

1. Скачайте Postman или воспользуйтесь веб-версией.

2. Загрузите API Octo Browser в workspace через кнопку Run in Postman.

3. Выберите запрос (например, POST Create Profile → Simple Profile).

4. Укажите https://app.octobrowser.net вместо {{baseUrl}}.
   
   

   

5. Укажите API-токен во вкладке Headers.

   

6. Укажите необходимые параметры профиля во вкладке Body.

   

7. Нажмите Send, чтобы создать профиль.

Аналогично и с запуском профиля: 

1. Выберите запрос POST Start Profile.

2. Укажите URL локального API: http://localhost:58888.

3. Найдите UUID профиля в меню «История и восстановление», в таблице профилей или через запрос GET Get Profiles.

4. Во вкладке Body задайте параметры:

• uuid: ID профиля;

• headless: запуск без GUI (true/false);

• debug_port: включение порта для автоматизации (true/false или конкретный порт);

• timeout: время ожидания в секундах;

• only_local: ограничение доступа к localhost (true/false);

• flags: дополнительные аргументы (например, ["--start-maximized"]);

• password: пароль профиля, если установлен.

5. Нажмите Send и проверьте ответ.

VS Code

1. Скачайте и установите VS Code.

2. Скачайте и установите node.js для JavaScript.

3. Скачайте и установите Python для Python-скриптов.

4. Откройте VS Code и создайте папку для проекта.

5. Установите зависимости:

   • Для Node.js: npm install axios.

   • Для Python: pip install requests.

6. Скопируйте пример из документации Octo для POST Create Profile на node.js+axios.

7. Создайте файл с расширением .js, вставьте в него скрипт.

8. Укажите ваш API-токен и сохраните файл.

9. Выполните скрипт командой node <название файла> (например, node post_create_profile).

Аналогично для запуска профиля с помощью Python: выберите POST Start Profile в Example Request, вставьте скрипт в файл с расширением .py, сохраните и запустите его.

Terminal/CMD

Также работать с API можно в Terminal/CMD. Для этого выберите в меню LANGUAGE язык cURL — cURL.

Укажите API-токен в запросе POST Create Profile и выполните:

Важный нюанс: для CMD на Windows необходимо адаптировать синтаксис, так как CMD интерпретирует команды немного иначе, чем Unix-подобные оболочки. В частности, нужно правильно экранировать кавычки и учитывать переносы строк. Пример адаптированного скрипта запуска профиля:

curl --location "http://localhost:58888/api/profiles/start" ^
--header "Content-Type: application/json" ^
--data "{\"uuid\": \"42c4231d71f6495fb33e70d97915c696\", \"headless\": false, \"debug_port\": true, \"timeout\": 120, \"only_local\": true, \"flags\": [], \"password\": \"\"}"

*Укажите UUID необходимого профиля

Это не все возможные варианты работы с API Octo Browser, для примера мы привели лишь некоторые из них.

Библиотеки автоматизации и CDP

CDP (Chrome DevTools Protocol) позволяет управлять действиями в профиле через код: открывать сайты, кликать, вводить текст, делать скриншоты.

Octo Browser поддерживает подключение по CDP через Local API. Когда вы запускаете профиль через POST Start Profile, необходимо передать параметр debug_port: true (или указать конкретный порт), и Octo откроет порт для удаленного подключения (например, ws://127.0.0.1:53215/devtools/browser/...).

Пример запуска профиля с CDP-портом:

curl --location 'http://localhost:58888/api/profiles/start' \
--header 'Content-Type: application/json' \
--data '{
    "uuid": "eb5d6441b2b349368b31fd901b82a8ac",
    "headless": false,
    "debug_port": true,
    "timeout": 120,
    "only_local": true
}'

Ответ будет содержать адрес для подключения:

{"uuid":"eb5d6441b2b349368b31fd901b82a8ac","state":"STARTED","headless":false,"start_time":1761735064,"ws_endpoint":"ws://127.0.0.1:53215/devtools/browser/d633f197-1623-4f61-a9b0-28a65e0df2fd","debug_port":"53215","one_time":false,"browser_pid":57411,"connection_data":{"ip":"","country":""}}

Этот адрес можно использовать в любой библиотеке, которая поддерживает CDP. Например, в Puppeteer/Pyppeteer, Playwright. Подробные примеры подключения библиотек доступны в документации.

Помимо прямого использования CDP, существует возможность подключать библиотеку Selenium к профилям Octo Browser через WebDriver. В этом случае Selenium управляет уже запущенным браузером через debug_port, но использует WebDriver вместо прямых CDP-команд. Пример подключения доступен в документации.

Использование библиотек автоматизации открывает широкие возможности — от прогрева профилей и сбора куки до создания сложной логики регистрации аккаунтов и управления их действиями.

Как запустить Octo Browser в Docker

Docker — программное обеспечение для автоматизации развертывания и управления приложениями в контейнерах. Каждый контейнер имеет свою ОС (обычно Linux), библиотеки, зависимости и настройки. В отличие от виртуальной машины, контейнер легкий и запускается очень быстро.

Преимущества использования Docker для Octo Browser:

• Изоляция окружения: Octo Browser и все его зависимости работают отдельно, не конфликтуя с другими приложениями.

• Универсальность: один и тот же контейнер можно запускать на сервере, ноутбуке или VPS, и все будет работать одинаково.

• Масштабируемость: можно запускать много профилей одновременно, а при необходимости создавать новые контейнеры для работы с большим количеством профилей параллельно.

• Автоматизация: удобно использовать в скриптах, где браузер работает в headless-режиме без графического интерфейса.

Запускаем Docker:

1. Подготовьте Dockerfile. Пример Dockerfile для Ubuntu 22.04 со всеми зависимостями, включая Octo Browser и Google Chrome, доступен в документации.

2. Соберите Docker-контейнер:

docker build -t octobrowser:latest

3. Запустите контейнер:

docker run --name octo -it --rm \
       --security-opt seccomp:unconfined \
       -v '/srv/docker_octo/cache:/home/octo/.Octo Browser/' \
       -p 58895:58888 \
       octobrowser:latest

Как управлять контейнерами с Octo Browser с помощью Kubernetes

Kubernetes (K8s) помогает управлять множеством контейнеров одновременно.

• Docker — запуск одного контейнера.

• Kubernetes — целый кластер контейнеров с автоматическим распределением нагрузки.

Для запуска Kubernetes можно использовать Minikube, kind, Docker Desktop или другие решения.

Процесс работы с Octo Browser и Kubernetes:

1. Соберите Docker-контейнер.

2. Запустите контейнер.

3. Используйте Kubernetes для управления контейнерами.

Пример Deployment YAML доступен в документации. 

Полезные сценарии и сниппеты

В документации Octo Browser по работе с API вы найдете не только базовые методы, но и готовые скрипты на Node.js и Python. Описаны следующие сценарии:

1. Массовое создание профилей — укажите количество профилей и ваш API-токен.

2. Массовое добавление в указанные профили расширений, стартовых страниц и закладок — укажите список профилей, расширения, стартовые страницы, закладки и API-токен.

3. Массовое добавление расширений, стартовых страниц и закладок во все профили — укажите расширения, стартовые страницы, закладки и API-токен.

4. Массовое добавление расширений, стартовых страниц и закладок в профили с определенным тегом/тегами — укажите тег/теги, расширения, стартовые страницы, закладки и API-токен.

5. Массовое создание прокси из .txt‑файла и последующее создание профилей с этими прокси — файл должен быть в формате protocol;host;port;login;password;title;change_ip_url (change_ip_url — опционально). В скрипте укажите API-токен и имя файла.

6. Добавление сохраненного прокси в профиль — укажите прокси, профиль и API-токен.

7. Копирование всех экспортированных профилей из списка экспорта клиента в указанную папку — укажите папку и API-токен.

8. Создание .txt‑файла с названиями всех профилей из аккаунта Octo Browser — вставьте API-токен.

API FAQ

Как передать параметры при создании профиля через API?

Пример тела запроса (body):

const body = {
  title: "profile_title", // обязательное поле
  fingerprint: {
    os: "mac", // обязательное поле: "mac", "win" или "android"
    os_arch: "arm", // необязательное поле: можно указать "x86", если хотите создать профиль mac с процессором Intel
    os_version: "13" // необязательное поле
    /*
      Возможные значения:
      — для Windows: 10, 11
      — для macOS (arm): 12, 13, 14, 15
      — для macOS (x86): 12, 13, 14, 15
      — для Android: 12, 13, 14, 15
    */
  }
};

Поле os в объекте fingerprint обязательно. Если вы не укажете другие параметры, Octo Browser сгенерирует для них оптимальные значения автоматически.

Чтобы узнать, какие еще параметры можно передавать при создании профиля:

1. Перейдите в API-документацию Octo Browser (запрос POST Create Profile).

2. Пролистайте страницу до блока Body — там указана структура всех доступных параметров. 

3. После создания профиля вы можете получить его параметры через запрос GET Get Profile — в ответе сервера будет полная структура профиля.

Как использовать одноразовые профили (one-time profiles)?

One-time profile — это одноразовый профиль, который создается и сразу запускается одним запросом API и автоматически удаляется после закрытия.

• Нет необходимости выполнять отдельные запросы на создание, запуск, остановку и удаление профиля. Может быть полезно, например, для веб-скрейпинга, где пользователю нужно лишь посетить веб-ресурс с новым отпечатком браузера, собрать данные и удалить профиль.

• Одноразовые профили можно использовать во всех подписках с доступом к API.

• Один запрос POST One-time profile учитывается как 4 запроса при подсчете лимитов RPM/RPH.

Чтобы завершить работу одноразового профиля, достаточно выполнить POST Stop Profile, закрыть окно браузера вручную или программно вызвать закрытие через Puppeteer, Playwright или аналогичные библиотеки, например с помощью await browser.close(). После закрытия профиль автоматически удаляется и не появляется в списке профилей или корзине.

Что делать при превышении лимитов API (ошибка 429)?

Остановите ваш скрипт и приостановите запросы на некоторое время. Лимиты API можно проверить в заголовках ответа сервера:

• Retry-After: 0 # — можете слать следующий запрос, если значение равно нулю.

• X-Ratelimit-Limit: 200 # RPM — общий лимит количества запросов в минуту.

• X-Ratelimit-Limit-Hour: 3000 # RPH — общий лимит количества запросов в час.

• X-Ratelimit-Remaining: 4 # remaining RPM — оставшееся количество запросов в минуту.

• X-Ratelimit-Remaining-Hour: 2999 # remaining RPH — оставшееся количество запросов в час.

• X-Ratelimit-Reset: 1671789217 # unix timestamp — время по UNIX, через которое сбросится лимит.

Не отправляйте запросы, если у вас исчерпаны лимиты, иначе время ограничения будет увеличено и могут быть применены более строгие ограничения. Проверяйте заголовки лимитов в ваших скриптах, прежде чем слать запрос.

Как получить ws_endpoint для подключения по CDP?

Когда вы запускаете профиль через API с параметром "debug_port": true (или указываете конкретный порт, например "debug_port": 20000), Octo Browser возвращает в ответе значение ws_endpoint.

Этот ws_endpoint используется библиотеками автоматизации (например, Puppeteer или Playwright) для подключения к запущенному профилю.

Где найти API-токен?

API доступен пользователям с подпиской Base и выше. API-токен отображается в клиенте Octo Browser в настройках мастер-аккаунта на вкладке «Дополнительные» (другие члены команды API-токен не видят).