Referencia de la API local: gestione perfiles del navegador desde sus scripts.

Resumen

La API local es una función de Prism Pro pensada para gestionar perfiles por lotes con sus propios scripts: crearlos a partir de sus datos, iniciarlos en orden, comprobar su estado y cerrarlos cuando termine. Solo gestiona los perfiles en sí: no lee cookies, contraseñas, credenciales de proxy ni el contenido de las páginas, y tampoco ofrece un endpoint de depuración para Puppeteer / Playwright. Para que una IA lea páginas, haga clic y rellene formularios, use MCP.

Inicio rápido

1. Inicie la API local

   En Prism, abra “API de automatización” en la barra lateral izquierda y haga clic en “Iniciar API local”. Esta función requiere Prism Pro.

2. Copie la dirección y el token

   La ventana muestra “Dirección de la API” y “Token de acceso de esta sesión”. El token solo se muestra una vez, cuando la API se inicia correctamente, así que cópielo enseguida; si más adelante necesita un token nuevo, detenga la API y vuelva a iniciarla.

3. Envíe su primera solicitud

   En la línea de comandos, defina dos variables, compruebe el estado del servicio y liste los perfiles. Si la respuesta incluye "state": "running", la dirección y el token funcionan.

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"

En Windows PowerShell, curl es un alias de otro comando: escriba curl.exe en su lugar o use Invoke-RestMethod, integrado en 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

Reglas de solicitud

La API solo acepta solicitudes enviadas por scripts o programas de este equipo. Si una solicitud no cumple alguna de estas reglas, no se ejecuta y devuelve el error indicado en la tabla:

Prism procesa las solicitudes de la API local y de MCP de una en una, en el orden en que llegan. Iniciar un perfil implica probar el proxy y abrir el navegador, lo que suele tardar unos segundos; mientras tanto, las solicitudes siguientes esperan en cola. Espere a que cada solicitud responda antes de enviar la siguiente.

Endpoints

{id} es el ID del perfil, que se obtiene del resultado de GET /v1/profiles. Todas las respuestas correctas tienen el estado HTTP 200 y, salvo la de GET /v1/status, devuelven el resultado en el campo result. La API no tiene endpoints para modificar ni eliminar perfiles.

Objeto de perfil

La lista de perfiles, el estado de un perfil, el inicio y el cierre devuelven el mismo 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"
  }
}

Las respuestas nunca incluyen direcciones ni credenciales de proxy, parámetros de huella digital, cookies, contraseñas, datos de sitios web ni datos de extensiones.

Consultar, iniciar y cerrar

GET /v1/status

Devuelve el estado del servicio, para confirmar que la dirección y el token funcionan. Es la única respuesta que no va dentro de result:

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

GET /v1/profiles

Devuelve una matriz de objetos de perfil, empezando por los modificados más recientemente. Los perfiles de la papelera no se incluyen.

GET /v1/profiles/{id}/status

Devuelve el estado actual de un perfil. Si el perfil no existe o está en la papelera, devuelve 404 PROFILE_NOT_FOUND.

POST /v1/profiles/{id}/start

• Equivale a hacer clic en “Abrir” en la aplicación: Prism comprueba el núcleo y la licencia de los núcleos Pro, prueba el proxy, detecta si ha cambiado la IP de salida y, por último, abre la ventana del navegador. Si todo va bien, devuelve el objeto de perfil con el estado running.
• Si el perfil ya está en ejecución, devuelve su estado actual sin abrirlo otra vez.
• Prism solo procesa la siguiente solicitud cuando la de inicio ya ha respondido. Para iniciar varios perfiles, llame al endpoint para cada uno de ellos, de uno en uno; cuántos pueden ejecutarse a la vez depende de la memoria y la CPU del equipo.
• Si falta el núcleo correspondiente, la prueba del proxy no se supera, la IP de salida del proxy ha cambiado (con la política block) o queda un proceso huérfano, el inicio falla con 502 y error.message explica el motivo.
• Los casos en los que la aplicación le pediría confirmación para continuar fallan directamente a través de la API; por ejemplo, cuando los datos de geolocalización de la salida del proxy se contradicen. Ante este tipo de errores, abra el perfil en la aplicación Prism o cambie su identidad de red a manual.
• Prism registra los perfiles para los que se ha llamado al endpoint de inicio (incluidos los que ya estaban en ejecución) y los cierra todos al hacer clic en “Parada de emergencia” en la ventana “API de automatización”. Al hacer clic en “Detener API”, o en los botones de detención y de parada de emergencia de la ventana de MCP, solo se detiene la API: estos perfiles siguen abiertos.

POST /v1/profiles/{id}/close

Cierra la ventana del navegador, conserva los datos del perfil y devuelve el objeto de perfil con el estado closed; si el perfil no está en ejecución, devuelve closed directamente. Si el navegador no se ha cerrado al cabo de 8 segundos y sigue ocupando el directorio de datos, devuelve el estado orphaned; llamar otra vez al endpoint de cierre finaliza el proceso huérfano.

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"

Crear perfiles

Los endpoints de creación guardan los perfiles nuevos cerrados, sin abrir el navegador. Todos los campos son opcionales: los que se omiten toman los mismos valores predeterminados que “Nuevo perfil” en la aplicación, y cada perfil recibe una semilla de huella digital nueva. Los campos desconocidos se rechazan.

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

Si se crea correctamente, se devuelve el perfil nuevo:

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

Crear por lotes

El cuerpo de POST /v1/profiles/batch es una matriz profiles de 1 a 50 elementos; cada uno se escribe igual que en la creación individual, pero requestKey va en el nivel superior o en el encabezado. Prism valida primero todos los perfiles: si alguno no es válido, no se crea ninguno, y el mensaje de error indica qué perfil y qué campo fallan (profiles[1] es el segundo perfil; se empieza a contar desde 0). Los resultados se devuelven en el orden 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 del perfil

Campos del proxy

Campos de huella digital

Plantillas de hardware

Si la plantilla no coincide con platform, la solicitud se rechaza. La posición y el tamaño de la ventana, las cookies, los datos de extensiones y otros ajustes similares no se pueden definir mediante la API; puede cambiarlos en la aplicación Prism después de crear el perfil.

Reintentos sin duplicados

Si se corta la red o una solicitud agota el tiempo de espera, puede que no sepa si el perfil llegó a crearse. Indique una clave de solicitud en cada creación y un reintento nunca creará duplicados:

• Envíe una clave de 8 a 128 caracteres en el encabezado Idempotency-Key o en el campo requestKey del cuerpo; puede contener letras ASCII, dígitos y . _ : -. Si la envía en ambos, deben coincidir.
• Si reintenta con la misma clave y el mismo contenido en un plazo de 24 horas, se devuelven los perfiles creados la primera vez (HTTP 200), incluso después de reiniciar Prism.
• La misma clave con un contenido distinto devuelve 409 IDEMPOTENCY_CONFLICT. Si se ha eliminado algún perfil creado la primera vez (incluso si solo se ha movido a la papelera), se devuelve 409 IDEMPOTENCY_RESULT_GONE en lugar de volver a crearlo sin avisar; para crearlo de nuevo, use otra clave.
• Pasadas 24 horas, la misma clave cuenta como una solicitud nueva.
• Se conservan como máximo 1000 solicitudes con clave durante 24 horas, un límite compartido con la creación desde MCP (cada creación desde MCP cuenta como una); al llegar al límite, se devuelve 429 IDEMPOTENCY_CAPACITY hasta que caduquen los registros antiguos.
• Las claves y el contenido de las solicitudes solo se guardan en este equipo como resúmenes criptográficos, nunca en texto plano, de modo que con ellos no se almacena ninguna contraseña de proxy.

Genere las claves a partir de sus propios datos, como el número de fila de una hoja de cálculo o un número de pedido: shop-b-001.

Gestión de errores

Cuando una solicitud se rechaza en la entrada (consulte “Reglas de solicitud”), error es una cadena, por ejemplo {"error":"unauthorized"}. Cuando Prism falla al procesar una solicitud, error es un 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" }
    ]
  }
}

Los programas deben basarse en el estado HTTP y en code; message es una explicación para personas, en parte en chino, y su redacción puede cambiar entre versiones. Cuando retryable es true, la misma solicitud se puede reintentar más tarde sin cambios. details solo aparece en errores de los campos de creación, con un máximo de 20 entradas, y nunca repite los valores enviados.

MCP_REQUEST_FAILED es un nombre de error genérico que Prism usa internamente y que también usa la API local.

Ejemplos de código

Sustituya la dirección y el token de los ejemplos por los valores que muestra Prism. Los ejemplos crean perfiles e inician y cierran un perfil recién creado.

Python

Requiere 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 y posteriores incluyen fetch, así que no hace falta instalar dependencias:

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

La API local está pensada para sus propios scripts; los clientes de IA deben conectarse a Prism mediante MCP. MCP usa su propio token y sus propios permisos: la IA solo ve los perfiles permitidos en “IA local · MCP” y no puede llamar a la API local. Ambos comparten el mismo servicio local y el mismo límite de 120 solicitudes cada 60 segundos; si detiene MCP o usa su parada de emergencia, la API local también se detiene.

Una IA también puede crear perfiles con las herramientas MCP prism_create_profile y prism_create_profiles, que admiten los mismos campos que se describen en esta página. Para ello, active “Permitir a la IA crear perfiles” en “IA local · MCP” (desactivado de forma predeterminada); que la IA pueda controlar los perfiles nuevos depende del modo de acceso a perfiles que haya configurado. MCP y la API local usan claves de solicitud independientes, pero comparten el límite de 1000 registros cada 24 horas.

Recomendaciones de seguridad

• El token es la llave para gestionar los perfiles de este equipo: no lo incluya en repositorios de código, registros ni chats. Si sospecha que se ha filtrado, detenga la API y vuelva a iniciarla; el token anterior deja de funcionar de inmediato.
• La API solo escucha en 127.0.0.1, así que otros dispositivos de la red local o de internet no pueden acceder a ella directamente. La comprobación de Host sirve sobre todo para rechazar las solicitudes de los navegadores y evitar usos accidentales, pero no sustituye a un control de acceso; no exponga la API mediante reenvío de puertos ni un proxy inverso.
• Otros programas de este equipo también pueden llamar a la API si obtienen el token. Actívela solo en equipos de confianza y, cuando termine, haga clic en “Detener API”.
• “Parada de emergencia”, en la ventana “API de automatización”, detiene la API y cierra los perfiles que la API haya iniciado en esta sesión y que sigan en ejecución.
• Cada solicitud que ejecuta Prism se anota en el registro de auditoría local vault/logs/automation-audit.jsonl (en el directorio de datos de Prism), que guarda la hora, la acción, el resultado, el ID de la solicitud, los ID de perfil y el motivo del fallo, nunca el token, el contenido de la solicitud ni el contenido de las páginas. No se registran las solicitudes rechazadas por las reglas de solicitud ni las llamadas a GET /v1/status.

Preguntas frecuentes

¿Puedo llamar a la API desde una página web o una extensión del navegador?

No. Las solicitudes que envía un navegador llevan el encabezado Origin, y la API las rechaza. Llámela desde la línea de comandos, un script o un programa local.

¿Por qué localhost devuelve 403?

La API exige que el encabezado Host coincida exactamente con 127.0.0.1 y el puerto de la dirección de la API, así que localhost se rechaza. Use 127.0.0.1 como nombre de host en la dirección.

¿Qué hago si la ventana “API de automatización” indica que la API está en ejecución, pero no muestra el token?

Cuando MCP está habilitado, Prism inicia automáticamente el servicio local que comparten la API y MCP, y en ese caso la ventana solo muestra la dirección. El token solo se muestra una vez, cuando la API se inicia correctamente con “Iniciar API local”: haga clic en “Detener API” y después en “Iniciar API local” para obtener un token nuevo. Mientras el servicio está detenido, la conexión de MCP también se interrumpe.

¿Sigue funcionando el token anterior después de reiniciar Prism?

No. Cada vez que se inicia la API se generan un puerto y un token nuevos; al detener la API o salir de Prism, el token anterior deja de ser válido.

¿Se pueden modificar o eliminar perfiles con la API?

No. La API puede crear, consultar, iniciar y cerrar perfiles; para modificar su configuración o eliminarlos, use la aplicación Prism.

¿Puedo conectar Puppeteer, Playwright o Selenium?

No. La API no ofrece ningún puerto de depuración ni dirección de WebDriver. Para acciones dentro de las páginas, puede encargárselas a un cliente de IA mediante MCP.

¿Puedo iniciar muchos perfiles a la vez?

Sí, llamando al endpoint de inicio para cada perfil, de uno en uno. Prism procesa las solicitudes en orden y pasa a la siguiente cuando el perfil ha terminado de iniciarse; cuántos pueden ejecutarse a la vez depende de la memoria y la CPU del equipo.

¿Funciona también en Windows?

Sí. Prism Pro ofrece la misma API local en macOS y en Windows. En Windows PowerShell, use curl.exe o Invoke-RestMethod.

Funciones y guías relacionadas