Referência da API local: gerencie perfis de navegador com seus scripts.

Visão geral

A API local é um recurso do Prism Pro para gerenciar perfis em lote com seus próprios scripts: crie perfis a partir dos seus dados, inicie-os em sequência, verifique o status deles e feche-os quando terminar. Ela gerencia apenas os perfis em si — não lê cookies, senhas, credenciais de proxy nem o conteúdo das páginas, e não oferece endpoints de depuração para Puppeteer / Playwright. Para que a IA leia páginas, clique e preencha formulários, use o MCP.

Início rápido

1. Iniciar a API local

   No Prism, abra “API de automação” na barra lateral esquerda e clique em “Iniciar API local”. Este recurso requer o Prism Pro.

2. Copiar o endereço e o token

   A janela mostra “Endereço da API” e “Token de acesso desta sessão”. O token aparece só uma vez, quando a API inicia com sucesso, então copie-o na hora; se precisar de um novo token depois, pare e reinicie a API.

3. Enviar a primeira requisição

   Defina duas variáveis em um terminal, verifique o status do serviço e liste os perfis. Se a resposta contiver "state": "running", o endereço e o token estão funcionando.

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"

No Windows PowerShell, curl é um alias de outro comando: digite curl.exe ou use o Invoke-RestMethod, nativo do PowerShell:

$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

Regras de requisição

A API só aceita requisições enviadas por scripts ou programas deste computador. Uma requisição que não cumpra uma destas regras não é executada e retorna o erro indicado na tabela:

O Prism processa as requisições da API local e do MCP uma de cada vez, na ordem em que chegam. Iniciar um perfil inclui testar o proxy e abrir o navegador, o que costuma levar alguns segundos; nesse meio-tempo, as requisições seguintes ficam na fila. Espere cada requisição retornar antes de enviar a próxima.

Lista de endpoints

{id} é o ID do perfil, obtido no resultado de GET /v1/profiles. As respostas bem-sucedidas usam o status HTTP 200; com exceção de GET /v1/status, elas trazem o resultado no campo result. A API não tem endpoints para editar ou excluir perfis.

Objeto de perfil

A lista de perfis, o status do perfil, a inicialização e o fechamento retornam o mesmo objeto de perfil:

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

As respostas nunca incluem endereços ou credenciais de proxy, parâmetros de impressão digital, cookies, senhas, dados de sites nem dados de extensões.

Consultar, iniciar e fechar

GET /v1/status

Retorna o status do serviço, para confirmar que o endereço e o token funcionam. É a única resposta que não vem dentro de result:

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

GET /v1/profiles

Retorna um array de objetos de perfil, com os modificados mais recentemente primeiro. Perfis na lixeira não aparecem.

GET /v1/profiles/{id}/status

Retorna o status atual de um perfil. Se o perfil não existir ou estiver na lixeira, a API retorna 404 PROFILE_NOT_FOUND.

POST /v1/profiles/{id}/start

• Funciona como clicar em “Abrir” no aplicativo: o Prism verifica o núcleo e a licença dos núcleos Pro, testa o proxy, confere se o IP de saída mudou e então abre a janela do navegador. Em caso de sucesso, retorna o objeto de perfil com status running.
• Se o perfil já estiver em execução, o status atual é retornado e nada é aberto duas vezes.
• O Prism só processa a próxima requisição depois que a requisição de inicialização retorna. Para iniciar vários perfis, basta chamar o endpoint para cada um, em sequência; quantos perfis podem rodar ao mesmo tempo depende da memória e da CPU do computador.
• Se o núcleo não estiver instalado, o teste de proxy falhar, o IP de saída do proxy tiver mudado (com a política block) ou houver um processo remanescente, a inicialização falha com 502, e error.message explica o motivo.
• Pela API, as situações em que o aplicativo pediria sua confirmação para continuar simplesmente falham — por exemplo, quando as fontes de dados geográficos divergem sobre a saída do proxy. Ao receber esse tipo de erro, abra o perfil no aplicativo Prism ou mude a identidade de rede dele para manual.
• Os perfis para os quais o endpoint de inicialização foi chamado (inclusive os que já estavam em execução no momento da chamada) ficam registrados e são fechados juntos quando você clica em “Parada de emergência” na janela “API de automação”. “Parar API”, assim como parar o MCP ou acionar a parada de emergência na janela do MCP, apenas interrompe a API; esses perfis continuam abertos.

POST /v1/profiles/{id}/close

Fecha a janela do navegador, mantém os dados do perfil e retorna o objeto de perfil com status closed; se o perfil não estiver em execução, retorna closed imediatamente. Se o navegador não for encerrado em até 8 segundos e continuar usando o diretório de dados, o status retornado é orphaned; chamar o endpoint de fechamento mais uma vez encerra o processo remanescente.

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"

Criar perfis

Os endpoints de criação salvam os novos perfis como fechados, sem abrir o navegador. Todos os campos são opcionais: os omitidos recebem os mesmos valores padrão de “Novo perfil” no aplicativo, e cada perfil ganha uma nova semente de impressão digital. Campos desconhecidos são recusados.

Criar um perfil

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

Em caso de sucesso, o novo perfil é retornado:

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

Criar em lote

O corpo de POST /v1/profiles/batch é um array profiles de 1 a 50 itens por requisição, cada um com o mesmo formato da criação individual, exceto que requestKey fica no nível superior do corpo ou no cabeçalho. O Prism valida todas as configurações primeiro: se alguma tiver erro, nada é criado, e a mensagem de erro indica o perfil e o campo com problema (profiles[1] é o segundo perfil; a contagem começa em 0). Os resultados voltam na ordem de entrada:

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

Campos do perfil

Campos de proxy

Campos de impressão digital

Modelos de hardware

Um modelo que não corresponda a platform é recusado. Posição e tamanho da janela, cookies, dados de extensões e configurações semelhantes não podem ser definidos pela API; altere-os no aplicativo Prism depois da criação.

Novas tentativas seguras

Quando a rede cai ou uma requisição esgota o tempo limite, você pode não saber se o perfil foi criado. Informe uma chave de requisição em cada criação; assim, uma nova tentativa nunca cria o perfil duas vezes:

• Envie a chave no cabeçalho Idempotency-Key ou no campo requestKey do corpo: de 8 a 128 caracteres, com letras ASCII (a–z, A–Z), números e . _ : -. Se enviar nos dois lugares, os valores precisam ser iguais.
• Repetir a requisição com a mesma chave e o mesmo conteúdo em até 24 horas retorna os perfis criados na primeira vez (HTTP 200), mesmo depois que o Prism é reiniciado.
• A mesma chave com conteúdo diferente retorna 409 IDEMPOTENCY_CONFLICT. Se um perfil criado na primeira requisição tiver sido excluído (inclusive movido para a lixeira), a API retorna 409 IDEMPOTENCY_RESULT_GONE em vez de recriá-lo sem avisar; para criá-lo de novo, use outra chave.
• Depois de 24 horas, a mesma chave conta como uma nova requisição.
• Até 1.000 requisições com chave ficam guardadas por 24 horas, um limite compartilhado com a criação pelo MCP (cada criação pelo MCP conta como uma); ao atingir o limite, a API retorna 429 IDEMPOTENCY_CAPACITY até que registros antigos expirem.
• Chaves e conteúdos das requisições ficam neste computador apenas como resumos criptográficos, nunca em texto puro; assim, nenhuma senha de proxy é armazenada junto com eles.

Gere as chaves a partir dos seus próprios dados, como a linha de uma planilha ou o número de um pedido: shop-b-001.

Tratamento de erros

Quando a requisição é recusada logo na entrada (veja “Regras de requisição”), error é uma string, como {"error":"unauthorized"}. Quando o Prism falha ao processar a requisição, error é um objeto:

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

Programas devem se basear no status HTTP e em code; message é uma explicação para leitura humana, em parte em chinês, e o texto pode mudar entre versões. Quando retryable é true, a mesma requisição pode ser repetida mais tarde, sem alterações. details só aparece em erros de campos de criação, com no máximo 20 itens, e nunca repete os valores enviados.

MCP_REQUEST_FAILED é um nome de erro genérico usado internamente pelo Prism; a API local também o usa.

Exemplos de código

Substitua o endereço e o token dos exemplos pelos valores exibidos na janela do Prism. Os exemplos criam perfis e depois iniciam e fecham um perfil recém-criado.

Python

Requer 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

O Node.js 18 ou posterior já inclui fetch, então não é preciso instalar dependências:

// 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 local e MCP

A API local é feita para os scripts que você mesmo escreve; clientes de IA devem se conectar ao Prism pelo MCP. O MCP usa token e permissões próprios: só os perfis permitidos em “IA local · MCP” ficam visíveis para a IA, e a IA não pode chamar a API local. Os dois compartilham o mesmo serviço local e o limite de 120 requisições a cada 60 segundos; parar o MCP ou acionar a parada de emergência do MCP também interrompe a API local.

A IA também pode criar perfis com as ferramentas MCP prism_create_profile e prism_create_profiles, que aceitam os mesmos campos desta página. Para isso, ative “Permitir que a IA crie perfis” em “IA local · MCP” (desativada por padrão); se a IA pode controlar os novos perfis depende do modo de acesso aos perfis que você definiu. O MCP e a API local mantêm chaves de requisição separadas, mas compartilham o limite de 1.000 registros em 24 horas.

Segurança

• O token é a chave para gerenciar os perfis deste computador: não o coloque em repositórios de código, logs nem históricos de chat. Se suspeitar de vazamento, pare e reinicie a API; o token antigo deixa de valer na hora.
• A API escuta apenas em 127.0.0.1, então outros dispositivos da rede local ou da internet não conseguem acessá-la diretamente. A verificação do Host serve principalmente para barrar navegadores e usos acidentais, e não substitui um controle de acesso; não exponha a API com redirecionamento de portas nem proxy reverso.
• Outros programas deste computador também podem chamar a API se obtiverem o token. Ative-a só em computadores confiáveis e clique em “Parar API” quando terminar.
• “Parada de emergência”, na janela “API de automação”, interrompe a API e fecha os perfis que ela iniciou nesta sessão e que ainda estão em execução.
• Cada requisição executada pelo Prism é registrada no log de auditoria local vault/logs/automation-audit.jsonl (no diretório de dados do Prism), que guarda a data e hora, a ação, o resultado, o ID da requisição, os IDs dos perfis e o motivo da falha — nunca o token, o conteúdo da requisição nem o conteúdo das páginas. Requisições recusadas pelas regras de requisição e chamadas a GET /v1/status não são registradas.

Perguntas frequentes

Posso chamar a API de uma página da web ou de uma extensão do navegador?

Não. Requisições enviadas por um navegador levam o cabeçalho Origin, que a API recusa. Faça as chamadas de um terminal, de um script ou de um programa local.

Por que recebo 403 ao usar localhost?

A API exige que o cabeçalho Host coincida exatamente com o 127.0.0.1 e a porta do endereço da API, então localhost é recusado. Use 127.0.0.1 como nome do host no endereço.

O que fazer se a janela “API de automação” mostra a API em execução, mas sem token?

Com o MCP habilitado, o Prism inicia automaticamente o serviço local compartilhado pela API e pelo MCP e, nesse caso, a janela mostra apenas o endereço. O token só aparece uma vez, quando você clica em “Iniciar API local” e a API inicia com sucesso: clique em “Parar API” e depois em “Iniciar API local” para obter um novo token. Enquanto o serviço estiver parado, a conexão do MCP também fica interrompida.

O token antigo continua valendo depois de reiniciar o Prism?

Não. Cada vez que a API é iniciada, são gerados uma nova porta e um novo token; ao parar a API ou sair do Prism, o token antigo deixa de valer.

Posso editar ou excluir perfis pela API?

Não. A API pode criar, consultar, iniciar e fechar perfis; para editar ou excluir perfis, use o aplicativo Prism.

Posso conectar Puppeteer, Playwright ou Selenium?

Não. A API não oferece porta de depuração nem endereço WebDriver. Para ações dentro das páginas, deixe um cliente de IA fazê-las pelo MCP.

Posso iniciar muitos perfis de uma vez?

Sim: chame o endpoint de inicialização para cada perfil, um de cada vez. O Prism processa as requisições em ordem e só passa para a próxima quando o perfil termina de iniciar; quantos perfis podem rodar ao mesmo tempo depende da memória e da CPU do computador.

Funciona também no Windows?

Sim. O Prism Pro oferece a mesma API local no macOS e no Windows. No Windows PowerShell, use curl.exe ou Invoke-RestMethod.

Recursos e tutoriais relacionados