ローカル API リファレンス：スクリプトでブラウザプロファイルを管理する。

概要

ローカル API は Prism Pro の機能で、自作のスクリプトでプロファイルを一括管理するのに向いています。たとえば、業務データからプロファイルを作成し、順番に起動して状態を確認し、使い終わったら閉じる、といった使い方です。API が管理するのはプロファイルそのものだけで、Cookie、パスワード、プロキシの認証情報、ページの内容は読み取りません。Puppeteer / Playwright 用のデバッグエンドポイントも提供しません。AI にページの読み取り、クリック、フォーム入力を行わせたい場合は、MCP を使ってください。

クイックスタート

1. ローカル API を起動

   Prism の左側のサイドバーで「オートメーションAPI」を開き、「ローカル API を起動」をクリックします。この機能を使うには Prism Pro が必要です。

2. アドレスとトークンをコピー

   ウィンドウに「APIアドレス」と「セッションアクセストークン」が表示されます。トークンは起動に成功したときに一度だけ表示されるので、すぐにコピーしてください。あとで新しいトークンが必要になったら、API を停止してから再起動します。

3. 最初のリクエストを送信

   ターミナルで 2 つの変数を設定し、サービスの状態を確認してから、プロファイルの一覧を取得します。レスポンスに "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 が受け付けるのは、この PC 上のスクリプトやプログラムから送信されたリクエストだけです。次のルールを満たさないリクエストは実行されず、表に示したエラーが返されます。

Prism は、ローカル API と MCP のリクエストを受け取った順に 1 件ずつ処理します。プロファイルの起動にはプロキシのチェックとブラウザを開く処理が含まれるため、通常は数秒かかります。その間に届いたリクエストは順番待ちになります。前のリクエストの応答が返ってから、次のリクエストを送ってください。

エンドポイント一覧

{id} はプロファイル ID で、GET /v1/profiles の結果から取得できます。成功時の HTTP ステータスはすべて 200 です。GET /v1/status を除き、結果は result フィールドに入ります。プロファイルの編集や削除を行うエンドポイントはありません。

プロファイルオブジェクト

プロファイルの一覧取得、状態の取得、起動、終了のいずれでも、同じプロファイルオブジェクトが返されます。

{
  "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"
  }
}

プロキシのアドレスや認証情報、フィンガープリントのパラメーター、Cookie、パスワード、サイトデータ、拡張機能のデータは、どのエンドポイントからも返されません。

照会・起動・終了

GET /v1/status

サービスの状態を返します。アドレスとトークンが使えるかどうかの確認に使います。結果が result に格納されない唯一のレスポンスです。

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

GET /v1/profiles

プロファイルオブジェクトの配列を、最近変更したものから順に返します。ゴミ箱内のプロファイルは含まれません。

GET /v1/profiles/{id}/status

1 つのプロファイルの現在の状態を返します。プロファイルが存在しないか、ゴミ箱に移動済みの場合は 404 PROFILE_NOT_FOUND が返されます。

POST /v1/profiles/{id}/start

• アプリで「開く」をクリックしたときと同じ処理です。カーネルと Pro カーネルのライセンスを確認し、プロキシと出口 IP の変化をチェックしてから、ブラウザウィンドウを開きます。成功すると、状態が running のプロファイルオブジェクトを返します。
• プロファイルがすでに実行中の場合は、現在の状態をそのまま返し、重複して開くことはありません。
• 起動リクエストの応答が返るまで、Prism は次のリクエストを処理しません。複数のプロファイルを起動する場合は、1 つずつ順番に呼び出してください。同時に実行できるプロファイルの数は、PC のメモリと CPU によって決まります。
• 対応するカーネルがない、プロキシのチェックに失敗した、プロキシの出口 IP が変化した（ポリシーが block の場合）、残存プロセスがある、のいずれかに該当すると起動は失敗し、502 が返されます。理由は error.message に示されます。
• アプリであれば確認を求められる状況では、API 経由の操作はそのまま失敗します。たとえば、プロキシの出口について位置情報のデータが互いに矛盾している場合です。このようなエラーが出たときは、Prism のアプリでそのプロファイルを開くか、ネットワークアイデンティティを manual に変更してください。
• 起動エンドポイントを呼び出したプロファイル（呼び出した時点ですでに実行中だったものを含む）は記録され、「オートメーション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"

プロファイルの作成

作成エンドポイントは、プロファイルを閉じた状態で保存し、ブラウザは開きません。フィールドはすべて省略可能です。省略したフィールドにはアプリの「新規プロファイル」と同じ既定値が使われ、プロファイルごとに新しいフィンガープリントシードが生成されます。不明なフィールドが含まれているとリクエストは拒否されます。

プロファイルを 1 つ作成

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 回に指定できるのは 1–50 個です。各要素の書き方は単体の作成と同じですが、requestKey だけはトップレベルまたはリクエストヘッダーで指定します。Prism はまずすべての設定を検証し、1 つでも誤りがあれば何も作成しません。エラーメッセージには、どのプロファイルのどのフィールドに問題があるかが示されます（profiles[1] は 2 番目のプロファイルを指します。番号は 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 が返されます。最初のリクエストで作成されたプロファイルが削除されている（ゴミ箱への移動を含む）場合は、黙って作り直すことはせず 409 IDEMPOTENCY_RESULT_GONE を返します。作り直したい場合は別のキーを使ってください。
• 24 時間を過ぎると、同じキーでも新しいリクエストとして扱われます。
• 24 時間以内のキー付きリクエストは最大 1,000 件まで保持されます。この上限は MCP による作成と共通で、MCP で作成するたびに 1 件を使用します。上限に達すると 429 IDEMPOTENCY_CAPACITY が返され、古い記録の期限が切れると再び受け付けられます。
• キーとリクエストの内容は、鍵付きハッシュ（ダイジェスト）としてのみこの PC に保存されます。プロキシのパスワードが平文で保存されることはありません。

キーは、スプレッドシートの行番号や注文番号など、業務データから生成することをおすすめします（例：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

MCP との関係

ローカル API は、自分で書いたスクリプトから使うためのものです。AI クライアントは MCP 経由で Prism に接続してください。MCP は独自のトークンと権限を使い、「ローカルAI・MCP」で許可したプロファイルだけが AI から見えます。AI がローカル API を呼び出すことはできません。両者は同じローカルサービスと、60 秒あたり 120 件のリクエスト上限を共有しています。MCP を停止するか、MCP の緊急停止を行うと、ローカル API も停止します。

AI も MCP ツール prism_create_profile と prism_create_profiles でプロファイルを作成でき、パラメーターはこのページと同じです。そのためには、「ローカルAI・MCP」で「AI によるプロファイル作成を許可」をオンにする必要があります（既定はオフ）。新しいプロファイルを AI が操作できるかどうかは、プロファイルの権限設定によって決まります。MCP とローカル API のリクエストキーは別々に管理されますが、記録の上限（24 時間以内に 1,000 件）は共通です。

セキュリティ上の注意

• トークンは、この PC でプロファイルを管理するための鍵にあたります。コードリポジトリ、ログ、チャットには書き込まないでください。漏えいの疑いがある場合は、API を停止して再起動してください。古いトークンはすぐに無効になります。
• API は 127.0.0.1 でのみ待ち受けるため、LAN やインターネット上の他のデバイスから直接アクセスすることはできません。Host のチェックは主にブラウザからのアクセスや誤用を防ぐためのもので、アクセス制御の代わりにはなりません。ポートフォワーディングやリバースプロキシで外部に公開しないでください。
• この PC 上の他のプログラムも、トークンを入手すれば API を呼び出せます。API は信頼できる PC でのみ有効にし、使い終わったら「API を停止」をクリックしてください。
• 「オートメーションAPI」ウィンドウの「緊急停止」を使うと API が停止し、今回 API で起動してまだ実行中のプロファイルが閉じられます。
• Prism が実行したすべてのリクエストは、この PC の監査ログ vault/logs/automation-audit.jsonl（Prism のデータディレクトリ内）に書き込まれます。記録されるのは日時、操作、結果、リクエスト ID、プロファイル ID、失敗の理由で、トークン、リクエストの内容、ページの内容は記録されません。リクエストのルールで拒否されたリクエストと GET /v1/status は記録されません。

よくある質問

ウェブページやブラウザ拡張機能から呼び出せますか？

できません。ブラウザから送信されるリクエストには Origin ヘッダーが付くため、API に拒否されます。ターミナル、スクリプト、ローカルのプログラムから呼び出してください。

localhost を使うと 403 が返されるのはなぜですか？

API は、Host ヘッダーが API アドレスの 127.0.0.1 とポートに完全に一致することを求めるため、localhost は拒否されます。アドレスのホスト名には 127.0.0.1 を使ってください。

「オートメーションAPI」ウィンドウに実行中と表示されているのにトークンが表示されない場合は、どうすればよいですか？

MCP を有効にすると、Prism は API と MCP が共有するローカルサービスを自動で起動します。このとき、ウィンドウにはアドレスだけが表示されます。トークンは、「ローカル API を起動」をクリックして起動に成功したときに一度だけ表示されます。新しいトークンを取得するには、まず「API を停止」をクリックし、次に「ローカル API を起動」をクリックしてください。停止している間は、MCP の接続も切断されます。

Prism を再起動した後も、以前のトークンを使えますか？

使えません。API を起動するたびに新しいポートとトークンが生成されます。API を停止するか Prism を終了すると、古いトークンは無効になります。

API でプロファイルを編集・削除できますか？

できません。API でできるのはプロファイルの作成、照会、起動、終了です。設定の編集や削除は Prism のアプリで行ってください。

Puppeteer、Playwright、Selenium を接続できますか？

できません。API はデバッグポートも WebDriver のアドレスも提供しません。ページ単位の操作が必要な場合は、MCP を通じて AI クライアントに任せられます。

多数のプロファイルを一度に起動できますか？

起動エンドポイントを 1 つずつ順番に呼び出せば可能です。Prism はリクエストを順に処理し、1 つのプロファイルの起動が完了してから次を処理します。同時に実行できる数は、PC のメモリと CPU によって決まります。

Windows でも使えますか？

使えます。macOS 版と Windows 版の Prism Pro のどちらにもローカル API があり、エンドポイントも同じです。Windows PowerShell では curl.exe または Invoke-RestMethod を使ってください。

関連する機能とチュートリアル