Довідник локального API: керуйте профілями браузера зі своїх скриптів.

Огляд

Локальний API — це функція Prism Pro для пакетного керування профілями з власних скриптів: створюйте профілі на основі своїх даних, запускайте їх по черзі, перевіряйте статус і закривайте після роботи. Він керує лише самими профілями — не читає файли 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

Повертає поточний стан одного профілю. Якщо профіль не існує або перебуває в кошику, API повертає 404 PROFILE_NOT_FOUND.

POST /v1/profiles/{id}/start

• Те саме, що натиснути «Відкрити» в програмі: Prism перевіряє ядро й ліцензію на ядра 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 після створення.

Безпечні повторні запити

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

• Передайте ключ у заголовку Idempotency-Key або в полі тіла requestKey: 8–128 символів — латинські літери, цифри та . _ : -. Якщо передано обидва, вони мають збігатися.
• Повторний запит із тим самим ключем і тим самим вмістом протягом 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. Обидва працюють через ту саму локальну службу й мають спільний ліміт — 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 API повертає 403?

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

Вікно «API автоматизації» показує, що API запущено, але маркера немає. Що робити?

Коли MCP увімкнено, Prism автоматично запускає спільну для API і MCP локальну службу, тому у вікні видно лише адресу. Маркер показується лише один раз — після успішного запуску кнопкою «Запустити локальний 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.

Пов’язані можливості та посібники