Справочник по локальному API: управляйте профилями браузера из своих скриптов.

Обзор

Локальный API — функция Prism Pro для массового управления профилями из ваших собственных скриптов: создавайте профили на основе своих данных, запускайте их по очереди, проверяйте статус и закрывайте после работы. API управляет только самими профилями: он не читает файлы cookie, пароли, учетные данные прокси и содержимое страниц и не предоставляет отладочных эндпоинтов для Puppeteer / Playwright. Чтобы ИИ читал страницы, нажимал на элементы и заполнял формы, используйте MCP.

Быстрый старт

1. Запустите локальный API

   В Prism откройте «API автоматизации» на панели слева и нажмите «Запустить локальный API». Для этой функции нужен Prism Pro.

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

   В окне появятся «Адрес API» и «Токен доступа текущего сеанса». Токен показывается только один раз — после успешного запуска, поэтому скопируйте его сразу; чтобы позже получить новый токен, остановите и снова запустите API.

3. Отправьте первый запрос

   Задайте в терминале две переменные, затем проверьте состояние службы и получите список профилей. Если в ответе есть "state": "running", адрес и токен работают.

PRISM_API='http://127.0.0.1:43123'   # the API address shown in Prism
PRISM_TOKEN='<token>'                # the token shown in Prism

curl -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/status"
curl -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles"

В Windows PowerShell curl — псевдоним другой команды, поэтому вводите curl.exe или используйте встроенный командлет PowerShell Invoke-RestMethod:

$api = 'http://127.0.0.1:43123'
$headers = @{ Authorization = 'Bearer <token>' }
(Invoke-RestMethod -Uri "$api/v1/profiles" -Headers $headers).result | Format-Table serialNumber, name, status

Правила запросов

API принимает только запросы от скриптов и программ на этом компьютере. Запрос, нарушающий одно из правил ниже, не выполняется, и API возвращает ошибку, указанную в таблице:

Prism обрабатывает запросы локального API и MCP по одному, в порядке поступления. Запуск профиля включает проверку прокси и открытие браузера и обычно занимает несколько секунд; все это время следующие запросы ждут в очереди. Отправляйте следующий запрос только после ответа на предыдущий.

Эндпоинты

{id} — ID профиля; его можно взять из результата GET /v1/profiles. Все успешные ответы имеют HTTP-статус 200, и все они, кроме GET /v1/status, содержат результат в поле result. Эндпоинтов для изменения и удаления профилей в API нет.

Объект профиля

Список профилей, статус профиля, запуск и закрытие возвращают один и тот же объект профиля:

{
  "result": {
    "id": "8f0c2b9e-4d6a-4f51-9a7e-2f1c3d5b6a70",
    "serialNumber": 12,
    "name": "Shop A",
    "group": "Project A",
    "tags": ["automation"],
    "status": "running",
    "lastOpenedAt": "2026-10-02T08:30:00.000Z"
  }
}

Ответы API не содержат адресов и учетных данных прокси, параметров отпечатка, файлов cookie, паролей, данных сайтов и расширений.

Статус, запуск и закрытие

GET /v1/status

Возвращает состояние службы — так можно убедиться, что адрес и токен работают. Это единственный ответ, который не обернут в result:

{
  "state": "running",
  "transport": "loopback",
  "protocolVersion": 1
}

GET /v1/profiles

Возвращает массив объектов профилей, первыми идут недавно измененные. Профили из корзины в него не попадают.

GET /v1/profiles/{id}/status

Возвращает текущее состояние одного профиля. Если профиль не существует или перемещен в корзину, возвращается 404 PROFILE_NOT_FOUND.

POST /v1/profiles/{id}/start

• Работает так же, как кнопка «Открыть» в приложении: Prism проверяет ядро (для ядер Pro — и лицензию Pro), прокси и смену выходного IP, а затем открывает окно браузера. При успехе возвращается объект профиля со статусом running.
• Если профиль уже запущен, сразу возвращается его текущее состояние; повторно профиль не открывается.
• Prism переходит к следующему запросу только после того, как запрос на запуск вернет ответ. Чтобы запустить много профилей, вызывайте эндпоинт для каждого по очереди; сколько профилей может работать одновременно, зависит от памяти и CPU компьютера.
• Если нужного ядра нет, проверка прокси не пройдена, выходной IP прокси изменился (при политике block) или остались процессы, запуск завершается ошибкой 502, а причина указана в error.message.
• Если в приложении для продолжения потребовалось бы ваше подтверждение, через API запрос сразу завершается ошибкой — например, когда данные геолокации выходного IP прокси противоречат друг другу. При таких ошибках откройте профиль в приложении Prism или переключите его сетевую идентичность на manual.
• Prism запоминает профили, для которых вызывался эндпоинт запуска (в том числе уже запущенные на момент вызова), и закрывает их, когда вы нажимаете «Экстренно остановить» в окне «API автоматизации». При нажатии кнопки «Остановить API», а также кнопок остановки и экстренной остановки в окне MCP останавливается только API, а эти профили остаются открытыми.

POST /v1/profiles/{id}/close

Закрывает окно браузера, сохраняет данные профиля и возвращает объект профиля со статусом closed; если профиль не запущен, сразу возвращается closed. Если браузер не завершился за 8 секунд и каталог данных все еще занят, возвращается статус orphaned; повторный запрос на закрытие завершит оставшиеся процессы.

PROFILE_ID='8f0c2b9e-4d6a-4f51-9a7e-2f1c3d5b6a70'   # an id from GET /v1/profiles
curl -X POST -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles/$PROFILE_ID/start"
curl -X POST -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles/$PROFILE_ID/close"

Создание профилей

Эндпоинты создания сохраняют профили закрытыми — браузер не открывается. Все поля необязательны: для пропущенных полей используются те же значения по умолчанию, что и при нажатии «Новый профиль» в приложении, а каждый профиль получает новый сид отпечатка. Неизвестные поля отклоняются.

Создание одного профиля

curl -X POST "$PRISM_API/v1/profiles" \
  -H "Authorization: Bearer $PRISM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-b-001" \
  -d '{
    "name": "Shop B",
    "group": "Project A",
    "tags": ["automation"],
    "startUrls": ["https://example.com/"],
    "proxy": { "protocol": "socks5", "host": "203.0.113.10", "port": 1080, "username": "user", "password": "pass" }
  }'

При успехе возвращается новый профиль:

{
  "result": {
    "id": "3b1f7a52-9c4e-4d2b-8f60-1a2b3c4d5e6f",
    "serialNumber": 13,
    "name": "Shop B",
    "group": "Project A",
    "tags": ["automation"],
    "status": "closed"
  }
}

Пакетное создание

Тело запроса POST /v1/profiles/batch содержит массив profiles (от 1 до 50 элементов); каждый элемент описывается так же, как при создании одного профиля, только requestKey указывается на верхнем уровне тела или в заголовке. Сначала Prism проверяет все профили: если хотя бы один задан неверно, не создается ни один, а в сообщении об ошибке указаны профиль и поле (profiles[1] — второй профиль: нумерация начинается с 0). Результаты возвращаются в порядке ввода:

{
  "requestKey": "shops-batch-001",
  "profiles": [
    { "name": "Shop C", "group": "Project A" },
    { "name": "Shop D", "group": "Project A", "fingerprint": { "platform": "windows" } }
  ]
}

{
  "result": {
    "profiles": [
      { "id": "…", "serialNumber": 14, "name": "Shop C", "group": "Project A", "tags": [], "status": "closed" },
      { "id": "…", "serialNumber": 15, "name": "Shop D", "group": "Project A", "tags": [], "status": "closed" }
    ],
    "count": 2
  }
}

Поля профиля

Поля прокси

Поля отпечатка

Шаблоны оборудования

Если шаблон не соответствует platform, запрос отклоняется. Положение и размер окна, файлы cookie, данные расширений и подобные настройки через API задать нельзя — измените их в приложении Prism после создания профиля.

Повторы без дубликатов

Если сеть оборвалась или запрос завершился по тайм-ауту, вы можете не знать, создан ли профиль. Передавайте ключ запроса при каждом создании — тогда повторная попытка не создаст профиль дважды:

• Передайте ключ длиной 8–128 символов в заголовке Idempotency-Key или в поле requestKey тела запроса; допустимы латинские буквы, цифры и символы . _ : -. Если указаны оба, они должны совпадать.
• Повтор с тем же ключом и тем же содержимым в течение 24 часов возвращает профили, созданные в первый раз (HTTP 200), — даже после перезапуска Prism.
• Тот же ключ с другим содержимым вернет 409 IDEMPOTENCY_CONFLICT. Если профиль из первого запроса удален (в том числе перемещен в корзину), API вернет 409 IDEMPOTENCY_RESULT_GONE и не станет незаметно создавать его заново; чтобы создать профиль снова, используйте новый ключ.
• По истечении 24 часов тот же ключ считается новым запросом.
• В течение 24 часов хранится не более 1000 запросов с ключом, и этот лимит общий с созданием профилей через MCP (каждое создание через MCP тоже засчитывается); при достижении лимита API возвращает 429 IDEMPOTENCY_CAPACITY, пока не истечет срок старых записей.
• Ключи и содержимое запросов хранятся на этом компьютере только в виде криптографических хешей, а не открытым текстом, поэтому пароли прокси в них не сохраняются.

Ключи удобно составлять из собственных данных, например из номера строки таблицы или номера заказа: shop-b-001.

Обработка ошибок

Если запрос отклонен еще на входе (см. «Правила запросов»), error — строка, например {"error":"unauthorized"}. Если ошибка произошла, когда Prism обрабатывал запрос, error — объект:

{
  "error": {
    "code": "INVALID_PROFILE_INPUT",
    "message": "Invalid profile creation request; see details",
    "retryable": false,
    "details": [
      { "path": "profiles[1].proxy.port", "message": "Too big: expected number to be <=65535" }
    ]
  }
}

Программам следует ориентироваться на HTTP-статус и code; message — пояснение для человека, частично на китайском языке, и его формулировки могут меняться от версии к версии. Если retryable имеет значение true, тот же запрос можно повторить позже. details появляется только при ошибках в параметрах создания, содержит не более 20 элементов и никогда не повторяет отправленные значения.

MCP_REQUEST_FAILED — общее имя ошибки, которое используется внутри Prism; локальный API тоже его возвращает.

Примеры кода

Замените адрес и токен в примерах значениями из окна Prism. Примеры создают профили, а затем запускают и закрывают только что созданный профиль.

Python

Нужна библиотека requests (pip install requests):

import requests

API = "http://127.0.0.1:43123"   # the API address shown in Prism
TOKEN = "<token>"                # the token shown in Prism

session = requests.Session()
session.headers["Authorization"] = f"Bearer {TOKEN}"

def call(method, path, **kwargs):
    response = session.request(method, API + path, timeout=70, **kwargs)
    body = response.json()
    if not response.ok:
        raise RuntimeError(f"{response.status_code}: {body['error']}")
    return body.get("result", body)

created = call("POST", "/v1/profiles/batch",
               headers={"Idempotency-Key": "shops-batch-002"},
               json={"profiles": [{"name": "Shop C"}, {"name": "Shop D"}]})
for profile in created["profiles"]:
    print("created", profile["serialNumber"], profile["id"])

profiles = call("GET", "/v1/profiles")
for profile in profiles:
    print(profile["serialNumber"], profile["name"], profile["status"])

first = created["profiles"][0]["id"]
print(call("POST", f"/v1/profiles/{first}/start")["status"])   # running
print(call("POST", f"/v1/profiles/{first}/close")["status"])   # closed

Node.js

Начиная с Node.js 18, fetch встроен — устанавливать зависимости не нужно:

// prism.mjs — run with: node prism.mjs (Node.js 18 or later)
const API = 'http://127.0.0.1:43123' // the API address shown in Prism
const TOKEN = '<token>'              // the token shown in Prism

async function call(method, path, body, headers = {}) {
  const response = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${TOKEN}`, ...(body ? { 'Content-Type': 'application/json' } : {}), ...headers },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(70_000),
  })
  const data = await response.json()
  if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(data.error)}`)
  return data.result ?? data
}

const profile = await call('POST', '/v1/profiles', {
  name: 'Shop E',
  fingerprint: { language: 'en-US', timezone: 'America/New_York', networkIdentityMode: 'manual' },
}, { 'Idempotency-Key': 'shop-e-001' })
console.log('created', profile.serialNumber, profile.id)

console.log((await call('POST', `/v1/profiles/${profile.id}/start`)).status) // running
console.log((await call('POST', `/v1/profiles/${profile.id}/close`)).status) // closed

Локальный API и MCP

Локальный API предназначен для ваших собственных скриптов, а ИИ-клиенты подключаются к Prism через MCP. У MCP свой токен и свои разрешения: ИИ видит только профили, разрешенные в разделе «Локальный ИИ · MCP», и не может вызывать локальный API. API и MCP используют одну и ту же локальную службу и общий лимит 120 запросов за 60 секунд; при остановке MCP, в том числе экстренной, локальный API тоже останавливается.

ИИ тоже может создавать профили с помощью инструментов MCP prism_create_profile и prism_create_profiles — с теми же полями, что описаны на этой странице. Для этого включите «Разрешить ИИ создавать профили» в разделе «Локальный ИИ · MCP» (по умолчанию выключено); сможет ли ИИ управлять новыми профилями, зависит от заданного вами режима доступа к профилям. Ключи запросов у MCP и локального API учитываются отдельно, но лимит в 1000 записей за 24 часа у них общий.

Безопасность

• Токен — это ключ к управлению профилями на этом компьютере: не сохраняйте его в репозиториях кода, журналах и чатах. Если есть подозрение на утечку, остановите и снова запустите API — старый токен сразу перестанет действовать.
• API слушает только 127.0.0.1, поэтому другие устройства в локальной сети и в интернете не могут подключиться к нему напрямую. Проверка заголовка Host в основном отсекает запросы из браузеров и случайные ошибочные обращения, но не заменяет контроль доступа: не открывайте доступ к API через переадресацию портов или обратный прокси.
• Другие программы на этом компьютере тоже смогут вызывать API, если получат токен. Включайте API только на доверенных компьютерах, а после работы нажимайте «Остановить API».
• Кнопка «Экстренно остановить» в окне «API автоматизации» останавливает API и закрывает еще работающие профили, запущенные через API в текущем сеансе.
• Каждый запрос, который выполняет Prism, записывается в локальный журнал аудита vault/logs/automation-audit.jsonl (в каталоге данных Prism): время, действие, результат, ID запроса, ID профилей и причина ошибки — без токена, содержимого запроса и содержимого страниц. Запросы, отклоненные из-за нарушения правил запросов, и GET /v1/status в журнал не записываются.

Частые вопросы

Можно ли вызывать API с веб-страницы или из расширения браузера?

Нет. Запросы из браузера содержат заголовок Origin, и API их отклоняет. Вызывайте API из терминала, скрипта или локальной программы.

Почему запрос к localhost возвращает 403?

API требует, чтобы заголовок Host в точности совпадал с 127.0.0.1 и портом из адреса API, поэтому localhost отклоняется. Указывайте в адресе имя хоста 127.0.0.1.

Что делать, если окно «API автоматизации» показывает, что API запущен, но токена нет?

Когда MCP включен, Prism автоматически запускает локальную службу, общую для API и MCP, и тогда окно показывает только адрес. Токен показывается только один раз — когда API успешно запускается кнопкой «Запустить локальный API». Чтобы получить новый токен, нажмите «Остановить API», а затем «Запустить локальный API». На время остановки подключение MCP тоже прерывается.

Действует ли старый токен после перезапуска Prism?

Нет. При каждом запуске API создаются новые порт и токен; после остановки API или выхода из Prism старый токен перестает действовать.

Можно ли через API изменять или удалять профили?

Нет. API может создавать профили, получать сведения о них, запускать и закрывать их; изменять настройки и удалять профили можно в приложении Prism.

Можно ли подключить Puppeteer, Playwright или Selenium?

Нет. API не предоставляет ни отладочного порта, ни адреса WebDriver. Действия на уровне страниц можно поручить ИИ-клиенту через MCP.

Можно ли запустить сразу много профилей?

Да, вызывайте эндпоинт запуска для каждого профиля по очереди. Prism обрабатывает запросы последовательно и переходит к следующему, когда профиль запустится; сколько профилей может работать одновременно, зависит от памяти и CPU компьютера.

Работает ли API в Windows?

Да. Prism Pro для macOS и для Windows предоставляет один и тот же локальный API. В Windows PowerShell используйте curl.exe или Invoke-RestMethod.

Связанные функции и руководства