Yerel API belgeleri: Tarayıcı profillerini betiklerle yönetin.

Genel bakış

Yerel API, profilleri kendi betiklerinizle toplu olarak yönetmek için tasarlanmış bir Prism Pro özelliğidir: Kendi verilerinize göre profil oluşturun, profilleri sırayla başlatın, durumlarını kontrol edin ve işiniz bitince kapatın. Yalnızca profillerin kendisini yönetir; çerezleri, şifreleri, proxy kimlik bilgilerini ve sayfa içeriğini okumaz, Puppeteer / Playwright için hata ayıklama uç noktası da sağlamaz. Yapay zekanın web sayfalarını okumasını, tıklamasını ve form doldurmasını istiyorsanız MCP kullanın.

Hızlı başlangıç

1. Yerel API'yi başlatın

   Prism'in sol tarafındaki “Otomasyon API'si” öğesini açın ve “Yerel API'yi başlat” düğmesine tıklayın. Bu özellik Prism Pro gerektirir.

2. Adresi ve belirteci kopyalayın

   Pencerede “API adresi” ve “Bu oturumun erişim belirteci” gösterilir. Belirteç yalnızca API başarıyla başlatıldığında bir kez gösterilir, bu yüzden hemen kopyalayın; daha sonra yeni bir belirteç gerekirse API'yi durdurup yeniden başlatın.

3. İlk isteğinizi gönderin

   Bir terminalde iki değişken tanımlayın, ardından hizmet durumunu kontrol edip profillerinizi listeleyin. Yanıtta "state": "running" varsa adres ve belirteç çalışıyor demektir.

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'de curl başka bir komutun takma adıdır; bunun yerine curl.exe yazın veya PowerShell'in yerleşik Invoke-RestMethod komutunu kullanın:

$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

İstek kuralları

API yalnızca bu bilgisayardaki betiklerin veya programların gönderdiği istekleri kabul eder. Aşağıdaki kurallardan birine uymayan istek yürütülmez ve tabloda gösterilen hatayı döndürür:

Prism, yerel API ve MCP isteklerini geliş sırasına göre tek tek işler. Bir profili başlatmak, proxy testi ve tarayıcının açılması nedeniyle genellikle birkaç saniye sürer; bu süre içinde sonraki istekler kuyrukta bekler. Bir sonraki isteği göndermeden önce öncekinin yanıtını bekleyin.

Uç noktalar

{id} bir profil kimliğidir ve GET /v1/profiles sonucundan alınabilir. Tüm başarılı yanıtların HTTP durumu 200'dür; GET /v1/status dışında sonuç result alanında yer alır. API'de profil düzenleme veya silme uç noktası yoktur.

Profil nesnesi

Profil listesi, profil durumu, başlatma ve kapatma uç noktalarının hepsi aynı profil nesnesini döndürür:

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

Yanıtlar hiçbir zaman proxy adreslerini veya kimlik bilgilerini, parmak izi ayarlarını, çerezleri, şifreleri, site verilerini ya da uzantı verilerini içermez.

Sorgulama, başlatma ve kapatma

GET /v1/status

Adresin ve belirtecin çalıştığını doğrulamak için hizmet durumunu döndürür. result alanı içinde dönmeyen tek yanıt budur:

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

GET /v1/profiles

Profil nesnelerinden oluşan bir dizi döndürür; en son değiştirilen profiller önce gelir. Çöp kutusundaki profiller listede yer almaz.

GET /v1/profiles/{id}/status

Bir profilin geçerli durumunu döndürür. Profil yoksa veya çöp kutusuna taşınmışsa 404 PROFILE_NOT_FOUND döner.

POST /v1/profiles/{id}/start

• Uygulamada “Aç” düğmesine tıklamakla aynı şekilde çalışır: Prism çekirdeği ve Pro çekirdek lisansını kontrol eder, proxy'yi test edip çıkış IP'sinin değişip değişmediğine bakar, ardından tarayıcı penceresini açar. Başarılı olursa durumu running olan profil nesnesini döndürür.
• Profil zaten çalışıyorsa geçerli durumu hemen döndürülür; profil ikinci kez açılmaz.
• Prism, bir başlatma isteği yanıtlanmadan sonraki isteği işlemez. Çok sayıda profil başlatmak için uç noktayı her profil için sırayla çağırmanız yeterlidir; aynı anda kaç profilin çalışabileceği bilgisayarınızın belleğine ve CPU'suna bağlıdır.
• Gerekli çekirdek yoksa, proxy testi başarısız olursa, proxy çıkış IP'si değişmişse (politika block ise) veya kalıntı bir işlem varsa başlatma başarısız olur ve 502 döner; nedeni error.message alanında açıklanır.
• Uygulamanın devam etmeden önce onayınızı isteyeceği durumlarda (örneğin proxy çıkışına ait coğrafi konum verileri birbiriyle çeliştiğinde) API isteği doğrudan başarısız olur. Bu tür hatalarda profili Prism uygulamasında açabilir veya ağ kimliğini manual olarak değiştirebilirsiniz.
• Başlatma uç noktasını çağırdığınız profiller (çağrı sırasında zaten çalışmakta olanlar dahil) kaydedilir; “Otomasyon API'si” penceresinde “Acil durdur” düğmesine tıklandığında bunlar da kapatılır. “API'yi durdur” düğmesi ile MCP penceresindeki durdurma ve acil durdurma düğmeleri yalnızca API'yi durdurur; bu profiller açık kalır.

POST /v1/profiles/{id}/close

Tarayıcı penceresini kapatır, profil verilerini korur ve durumu closed olan profil nesnesini döndürür; profil çalışmıyorsa da doğrudan closed döndürülür. Tarayıcı 8 saniye içinde kapanmaz ve veri dizinini kullanmaya devam ederse döndürülen durum orphaned olur; kapatma uç noktasını bir kez daha çağırdığınızda kalıntı işlem sonlandırılır.

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"

Profil oluşturma

Oluşturma uç noktaları yeni profilleri kapalı durumda kaydeder; tarayıcı açılmaz. Tüm alanlar isteğe bağlıdır: Belirtilmeyen alanlar, uygulamada “Yeni profil” ile oluşturulan profillerle aynı varsayılan değerleri alır ve her profil için yeni bir parmak izi tohumu oluşturulur. Bilinmeyen alanlar reddedilir.

Tek bir profil oluşturma

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

Başarılı olursa yeni profil döndürülür:

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

Toplu oluşturma

POST /v1/profiles/batch isteğinin gövdesi bir profiles dizisidir ve bir istekte 1–50 öğe bulunabilir; dizinin her öğesi tek profil oluştururken olduğu gibi yazılır, ancak requestKey en üst düzeyde veya istek başlığında belirtilir. Prism önce tüm profilleri doğrular: Herhangi biri geçersizse hiçbir profil oluşturulmaz ve hata mesajı hangi profilin hangi alanının hatalı olduğunu belirtir (profiles[1] ikinci profil demektir; sayım 0'dan başlar). Sonuçlar giriş sırasıyla döndürülür:

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

Profil alanları

Proxy alanları

Parmak izi alanları

Donanım şablonları

Şablon platform değeriyle uyuşmazsa istek reddedilir. Pencere konumu ve boyutu, çerezler, uzantı verileri gibi ayarlar API ile belirlenemez; bunları profil oluşturulduktan sonra Prism uygulamasında değiştirebilirsiniz.

Güvenli yeniden deneme

Ağ bağlantısı kesildiğinde veya istek zaman aşımına uğradığında profilin oluşturulup oluşturulmadığını bilemeyebilirsiniz. Her oluşturma isteğine bir istek anahtarı ekleyin; böylece yeniden deneme hiçbir zaman ikinci bir profil oluşturmaz:

• Anahtarı Idempotency-Key istek başlığında veya gövdedeki requestKey alanında gönderin; anahtar 8–128 karakter uzunluğunda olmalı ve yalnızca ASCII harf, rakam ve . _ : - içermelidir. İkisini birden gönderirseniz değerler aynı olmalıdır.
• 24 saat içinde aynı anahtar ve aynı içerikle yapılan yeniden deneme, ilk seferde oluşturulan profilleri döndürür (HTTP 200); bu, Prism yeniden başlatıldıktan sonra da geçerlidir.
• Anahtar aynı ama içerik farklıysa 409 IDEMPOTENCY_CONFLICT döner. İlk istekte oluşturulan bir profil silinmişse (çöp kutusuna taşınması dahil) API, profili sessizce yeniden oluşturmak yerine 409 IDEMPOTENCY_RESULT_GONE döndürür; profili yeniden oluşturmak için yeni bir anahtar kullanın.
• 24 saat geçtikten sonra aynı anahtar yeni bir istek sayılır.
• Anahtarlı istekler 24 saat boyunca saklanır ve en fazla 1.000 istek tutulur; bu sınır, MCP üzerinden yapılan profil oluşturma işlemleriyle ortaktır (MCP ile yapılan her oluşturma bir kayıt kullanır). Sınıra ulaşıldığında API, eski kayıtların süresi dolana kadar 429 IDEMPOTENCY_CAPACITY döndürür.
• Anahtarlar ve istek içerikleri bu bilgisayarda yalnızca kriptografik özet olarak saklanır; proxy şifreleri açık metin olarak saklanmaz.

Anahtarları kendi verilerinizden, örneğin bir tablo satır numarasından veya sipariş numarasından oluşturmanızı öneririz: shop-b-001.

Hata işleme

İstek daha girişte reddedilirse (bkz. “İstek kuralları”) error bir dizedir, örneğin {"error":"unauthorized"}. Prism isteği işlerken bir hata oluşursa error bir nesnedir:

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

Programlarınız HTTP durumuna ve code değerine göre karar vermelidir; message insanlar için yazılmış bir açıklamadır, kısmen Çincedir ve ifadesi sürümden sürüme değişebilir. retryable true ise aynı istek daha sonra olduğu gibi yeniden denenebilir. details yalnızca geçersiz oluşturma alanlarında yer alır, en fazla 20 öğe içerir ve gönderilen değerleri hiçbir zaman içermez.

MCP_REQUEST_FAILED, Prism'in dahili olarak kullandığı genel bir hata adıdır; yerel API de bu adı kullanır.

Kod örnekleri

Örneklerdeki adresi ve belirteci Prism penceresinde gösterilen değerlerle değiştirin. Örnekler profil oluşturur, ardından yeni oluşturulan profili başlatıp kapatır.

Python

requests paketi gerekir (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'den itibaren fetch yerleşik olarak gelir; herhangi bir bağımlılık kurmanız gerekmez:

// 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

Yerel API ve MCP

Yerel API sizin yazdığınız betikler içindir; yapay zeka istemcileri Prism'e MCP üzerinden bağlanmalıdır. MCP'nin kendi belirteci ve izinleri vardır: Yalnızca “Yerel yapay zeka · MCP” penceresinde izin verilen profiller yapay zekaya görünür ve yapay zeka yerel API'yi çağıramaz. İkisi aynı yerel hizmeti ve 60 saniyede 120 isteklik ortak sınırı paylaşır; MCP durdurulduğunda veya acil olarak durdurulduğunda yerel API de durur.

Yapay zeka da bu sayfadakiyle aynı alanları kullanan prism_create_profile ve prism_create_profiles MCP araçlarıyla profil oluşturabilir. Bunun için “Yerel yapay zeka · MCP” penceresinde “Yapay zekâ profil oluşturabilsin” seçeneğini açmanız gerekir (varsayılan olarak kapalıdır); yapay zekanın yeni profilleri kontrol edip edemeyeceği, ayarladığınız profil erişim moduna bağlıdır. MCP ile yerel API'nin istek anahtarları birbirinden bağımsızdır, ancak 24 saatte 1.000 kayıtlık sınır ikisi için ortaktır.

Güvenlik önerileri

• Belirteç, bu bilgisayardaki profilleri yönetmenin anahtarıdır: Onu kod depolarına, günlüklere veya sohbet kayıtlarına yazmayın. Sızdığından şüpheleniyorsanız API'yi durdurup yeniden başlatın; eski belirteç hemen geçersiz olur.
• API yalnızca 127.0.0.1 üzerinde dinler; yerel ağdaki veya internetteki diğer cihazlar API'ye doğrudan erişemez. Host denetimi esas olarak tarayıcıları ve hatalı kullanımı engellemek içindir, erişim denetiminin yerini tutmaz; API'yi port yönlendirme veya ters proxy ile dışarıya açmayın.
• Bu bilgisayardaki başka programlar da belirteci elde ederse API'yi çağırabilir. API'yi yalnızca güvendiğiniz bilgisayarlarda etkinleştirin ve işiniz bitince “API'yi durdur” düğmesine tıklayın.
• “Otomasyon API'si” penceresindeki “Acil durdur” düğmesi API'yi durdurur ve bu oturumda API üzerinden başlatılıp hâlâ çalışan profilleri kapatır.
• Prism'in yürüttüğü her istek, bu bilgisayardaki vault/logs/automation-audit.jsonl denetim günlüğüne (Prism veri dizininde) yazılır. Günlüğe zaman, işlem, sonuç, istek kimliği, profil kimlikleri ve hata nedeni kaydedilir; belirteç, istek içeriği ve sayfa içeriği asla kaydedilmez. İstek kuralları nedeniyle reddedilen istekler ve GET /v1/status istekleri günlüğe yazılmaz.

Sık sorulan sorular

API'yi bir web sayfasından veya tarayıcı uzantısından çağırabilir miyim?

Hayır. Tarayıcıların gönderdiği isteklerde Origin başlığı bulunur ve API bu istekleri reddeder. API'yi bir terminalden, betikten veya yerel bir programdan çağırın.

Neden localhost ile 403 hatası alıyorum?

API, Host başlığının API adresindeki 127.0.0.1 ve bağlantı noktasıyla birebir eşleşmesini şart koşar; bu yüzden localhost reddedilir. Adreste ana bilgisayar adı olarak 127.0.0.1 kullanın.

“Otomasyon API'si” penceresi API'nin çalıştığını gösteriyor ama belirteç yok. Ne yapmalıyım?

MCP etkinleştirildiğinde Prism, API ile MCP'nin paylaştığı yerel hizmeti otomatik olarak başlatır; bu durumda pencerede yalnızca adres gösterilir. Belirteç yalnızca “Yerel API'yi başlat” düğmesine tıklanıp API başarıyla başlatıldığında bir kez gösterilir: Yeni bir belirteç almak için önce “API'yi durdur”, ardından “Yerel API'yi başlat” düğmesine tıklayın. Hizmet durdurulduğu sırada MCP bağlantısı da kesilir.

Prism yeniden başlatıldıktan sonra eski belirteç çalışır mı?

Hayır. API her başlatıldığında yeni bir bağlantı noktası ve yeni bir belirteç oluşturulur; API durdurulduğunda veya Prism'den çıkıldığında eski belirteç geçersiz olur.

API ile profilleri düzenleyebilir veya silebilir miyim?

Hayır. API profilleri oluşturabilir, sorgulayabilir, başlatabilir ve kapatabilir; profil ayarlarını düzenlemek ve profilleri silmek için Prism uygulamasını kullanın.

Puppeteer, Playwright veya Selenium bağlanabilir mi?

Hayır. API hata ayıklama bağlantı noktası veya WebDriver adresi sağlamaz. Sayfa düzeyindeki işlemleri MCP üzerinden bir yapay zeka istemcisine yaptırabilirsiniz.

Tek seferde çok sayıda profil başlatabilir miyim?

Evet, başlatma uç noktasını her profil için sırayla çağırabilirsiniz. Prism istekleri tek tek işler ve bir profil başlatıldıktan sonra bir sonrakine geçer; aynı anda kaç profilin çalışabileceği bilgisayarınızın belleğine ve CPU'suna bağlıdır.

Windows'ta da çalışır mı?

Evet. Prism Pro, macOS ve Windows'ta aynı yerel API'yi sunar. Windows PowerShell'de curl.exe veya Invoke-RestMethod kullanın.

İlgili özellikler ve rehberler