База знаний
Профили по API: список, правка, одноразовый, куки, выгрузка
Отбор профилей из списка
profile/list и browser/list принимают доводы в адресе. Без доводов ответ прежний: весь список в обычном порядке, и старые скрипты разницы не видят.
В ответе рядом с list всегда стоят total, page и pageSize. Незнакомый довод не отвергается, а называется в ignored: опечатка видна, а не превращается в пустой список.
Длинный список номеров уходит телом POST profile/list, а не в адрес. У каждой строки есть notes, status, updatedAt, launches, runTimeMs и openSince.
- Отбор
- ids, group, groupId, tags, tagsMode, search, running, passwordProtected, scenario, template, status, proxy
- Даты
- createdFrom, createdTo, updatedFrom, updatedTo, usedFrom, usedTo
- Порядок
- sort: name, createdAt, updatedAt, lastUsedAt, launches, runTime, group; order: asc или desc
- Страницы
- page с 1, pageSize от 1 до 100; fields выбирает столбцы
- Пример
- GET /api/v1/profile/list?tags=ads&sort=lastUsedAt&order=desc&pageSize=50
search ищет в имени, группе, заметке, тегах, адресе прокси и в номере от шести знаков. С fields он ищет только в заказанных полях. tagsMode all требует все названные теги, any хотя бы один.
Правка профиля
POST profile/update меняет только присланные поля, с проверками окна профиля: доля только для запуска, пароль на профиль, значения, которые окно не примет.
- Запрос
- { profileId, name: Shop-02, proxy: { port: 8081 } }
- Ответ
- { code: 0, data: { changed, profile, notSent, localOnly } }
- Открытый профиль
- needsRelaunch, pendingKeys: применится при следующем запуске
- Только этот компьютер
- fingerprint (ручные значения отпечатка), login (вход сайта), twoFactorKey (ключ 2FA)
proxy, fingerprint и login правятся по частям; null снимает их. У прокси с тем же сервером пароль остаётся. Отказ проверки не меняет ничего; отказ отпечатка называет годные значения в data.allowed.
Одноразовый профиль одним запросом
POST profile/quick заводит профиль и сразу открывает его, как кнопка «Одноразовый профиль» в окне. Он принимает fingerprintTemplate, proxy или proxyId, geolocation, webrtc, cookies, startUrl, headless и name.
Ответ тот же, что у browser/start, плюс temporary и profileId. После закрытия профиль удаляется целиком и в корзину не попадает, а оставшийся от убитой программы убирается при следующем запуске.
Он живёт только на этом компьютере, но место по тарифу занимает, пока открыт.
Прокси проверяется перед запуском
Перед каждым запуском прокси проверяется. Отказ несёт причину в data.reason: proxy_silent, proxy_refused, proxy_not_found, proxy_auth, exit_country_unknown или exit_services_blocked, а msg говорит её словами.
Открывшийся запуск несёт data.exit: адрес выхода (пустой, если страна взята из прошлой проверки), страну и то, проверена ли страна сейчас или взята из прошлой проверки. Для медленного прокси пришлите proxyWaitSec от 5 до 60 секунд; по умолчанию 12.
Куки профиля
GET profile/cookies читает куки одного профиля, все или одного домена с поддоменами, в JSON или в тексте Netscape. POST profile/cookies/export делает то же для 100 профилей сразу и отвечает по каждому.
POST profile/cookies/import принимает куки списком или текстом в JSON, Netscape или Firefox, как «Импорт куки» в окне принимает файл. Тело до 16 МБ; истёкшие куки считаются и не кладутся.
Куки остаются на этом компьютере. На наш сервер они не уходят, а у сервера MCP нет ходов с куки, поэтому ИИ-помощник ваших входов не видит.
| Профиль | Чтение | Загрузка |
|---|---|---|
| Открыт, любой движок | Сразу | Сразу, в открытый браузер |
| Закрыт, встроенный движок | Сразу | Сразу |
| Закрыт, ARMANOS Browser | Открывается скрыто только для чтения: без сайтов, без сети и без расширений | В очередь: куки войдут до первой страницы следующего запуска |
Чтение не считается запуском
Выгрузка и ввоз профилей
POST profile/export принимает до 100 profileIds. С kind settings настройки приходят прямо в ответе, без паролей прокси и ключей 2FA, если не прислать includeCredentials; с kind full каждый закрытый профиль ложится в архив .armanos вместе с сессией под паролем archivePassword.
POST profile/import принимает настройки в data или имена файлов архивов и настроек в files. Обе дороги идут по профилю за раз и отвечают по каждому.
Архивы лежат в папке ARMANOS в «Загрузках», а в режиме сервера в папке exports внутри ARMANOS_OUT_DIR; путь запрос не задаёт никогда. Настройки, чей номер профиля здесь уже занят, приходят с identityChanged: для сайтов это теперь другая машина.
Режим WebRTC нового профиля
profile/create и profile/quick принимают webrtc с полем mode, а для custom ещё ip: адрес в интернете, IPv4 или IPv6. Ответ profile/create всегда несёт webrtc.
Другие программы зовут те же режимы иначе: altered, mask или ip здесь proxy, manual это custom, local или natural это real, udpDisabled или disableUDP это noudp, а disabled это off.
- proxy
- «Адрес прокси», по умолчанию
- custom
- «Свой адрес», нужен ip
- real
- «Настоящий»
- noudp
- «Без UDP»
- off
- «Выключен»
Негодное значение получает отказ кодом webrtc.mode, webrtc.empty, webrtc.notIp, webrtc.private или webrtc.special в msg, а data.message говорит причину словами.
Коды в ответе
Отказ приходит кодом в msg, а не переведённой фразой, и скрипт может ветвиться по нему.
- profile_password_required
- Профиль закрыт паролем: сначала откройте его
- profile_not_yours
- Профиль открыт вам коллегой: удалить его или выгрузить файлом может только хозяин или администратор
- share_run_only
- Профиль открыт вам только для запуска: правка и куки наружу с уровня правки
- share_move_full_only
- Перенести общий профиль в другую группу можно только с полным доступом
- unknown_field
- Незнакомое поле: data.field называет его, ничего не записано
- share_fp_values_own_only
- Ручные значения отпечатка правятся только у своего профиля
- profile_running
- Полной выгрузке и скрытому чтению нужен закрытый профиль
- profile_busy
- Профиль открыт на другой машине
- bad_param
- У довода негодное значение; data.param называет его
- payload_too_large
- Тело больше предела этого хода
- quota
- В тарифе нет места ещё для одного профиля
Чего это не делает
- Это не передаёт профили в другой аккаунт. Выгрузка и ввоз переносят файлы, аккаунт остаётся вашим.
- Это не пишет файл туда, куда скажет запрос.
Где это решается
Каждая строка ниже называет стенд, который это проверяет.
- Отбор, порядок и страницы списка, одно правило в локальном API и на сервере
- packages/shared/test/отбор-профилей.js, apps/desktop/test/api-список.js
- Одноразовый профиль по API удаляется после закрытия и не уезжает в аккаунт
- apps/desktop/test/api-одноразовый.js, apps/desktop/test/api-одноразовый-живьём.js
- Куки открытых и закрытых профилей и скрытое чтение без сети
- apps/desktop/test/api-куки.js, apps/desktop/test/api-куки-закрытого-живьём.js
- Выгрузка и ввоз отвечают по каждому профилю и не пишут вне своей папки, а режим сервера берёт папку из ARMANOS_OUT_DIR
- apps/desktop/test/api-выгрузка-загрузка.js · apps/desktop/test/режим-сервера.js
- Каждый ход с номером профиля отказывает закрытому паролем профилю
- apps/desktop/test/api-двери-за-паролем.js
- Правка скриптом и через MCP идёт дорогой окна
- apps/desktop/test/api-правка.js, apps/desktop/test/api-правка-живьём.js, apps/desktop/test/api-правка-другие-ходы-живьём.js
Вопросы
- Почему отбор ничего не вернул?
- Посмотрите ignored в ответе: довод с опечаткой назван там и не применён.
- Правка доезжает до других моих компьютеров?
- Да, кроме полей, которые ответ называет в localOnly.
Попробуйте на одном скрипте
Бесплатный тариф даёт два профиля, без срока и без карты.