Referencia de la API

OpenWAF Browsers tiene dos API:

• El plano de datos en https://browsers.openwaf.dev, al que tu agente llama con una clave de navegador (bdk_…) para arrancar, listar y parar navegadores y para gestionar perfiles.
• La API de gestión en https://dash.openwaf.dev/v1/orgs/{org}/browsers, a la que llamas con un token de la API de OpenWAF (owf_…) o la sesión del panel para gestionar claves, ajustes, uso, sesiones y el registro de salida. La usan la CLI y las herramientas MCP.

#Plano de datos

URL base https://browsers.openwaf.dev. Cada ruta necesita una clave de navegador, en cualquiera de estas cabeceras:

X-API-Key: bdk_…
Authorization: Bearer bdk_…

JSON de entrada y de salida. Una clave solo ve los navegadores que arrancó ella.

#Arrancar un navegador

POST /v1/browsers. Todos los campos son opcionales.

La respuesta es el navegador:

{"id": "bs_…", "status": "running",
 "cdpUrl": "wss://browsers.openwaf.dev/cdp/…",
 "cdpHttpUrl": "https://browsers.openwaf.dev/…",
 "liveUrl": "https://browsers.openwaf.dev/…",
 "urlsExpireAt": "2026-10-29T11:00:00Z", …}

• cdpUrl es el WebSocket de DevTools del navegador: chromium.connectOverCDP(cdpUrl) en Playwright, puppeteer.connect({browserWSEndpoint: cdpUrl}) en Puppeteer, npx @playwright/mcp@latest --cdp-endpoint <cdpUrl> para MCP.
• cdpHttpUrl sirve los endpoints HTTP de DevTools (/json/version, /json/list, …) con sus URL de WebSocket apuntando de vuelta a browsers.openwaf.dev.
• liveUrl abre la pantalla en un navegador web, para mirar o tomar el control.
• Los tokens de estas URL caducan en urlsExpireAt, 1 hora después de emitirse. GET /v1/browsers/{id} devuelve otros nuevos mientras el navegador sigue en marcha.

#Listar y leer navegadores

• GET /v1/browsers lista los navegadores de la clave. Filtros: status=running, metadata=k=v (se puede repetir).
• GET /v1/browsers/{id} devuelve un navegador, con URL nuevas mientras sigue en marcha.

#Parar un navegador

PATCH /v1/browsers/{id}
Content-Type: application/json

{"action": "stop"}

Al pararlo se cierra la grabación y se guarda y libera el perfil. Un navegador también se para solo:

• tras su tiempo de inactividad (120 s por defecto) sin ningún cliente CDP ni de vista en directo;
• al llegar a la duración máxima de sesión (60 minutos en la beta);
• cuando Chrome termina;
• cuando se rota o revoca su clave, o la organización agota la cuota.

#Archivos

GET /v1/browsers/{id}/files lista las descargas y la grabación de un navegador, cada una con un enlace firmado que caduca. Los archivos de sesión se guardan 7 días.

#Registro de salida

GET /v1/browsers/{id}/egress devuelve {"items": […]} con las últimas peticiones que hizo el navegador por el proxy de salida: hora, método, host, puerto, decision (allow, deny o error), el motivo de una denegación, estado y bytes. El registro de toda la organización está en la API de gestión.

#Perfiles

Un perfil guarda cookies, sesiones iniciadas y almacenamiento local entre navegadores.

#Errores del plano de datos

Los errores son JSON: {"error": "…", "code": "…"}.

capacity_busy es capacidad compartida, no tu cuota: reintentar tras Retry-After es lo correcto. key_concurrency no se arregla esperando, salvo que se pare uno de tus navegadores.

#API de gestión

Todas las rutas cuelgan de https://dash.openwaf.dev/v1/orgs/{org}, con un token de la API (Authorization: Bearer owf_…) o la sesión del panel. Para leer basta cualquier rol de toda la organización (readonly o superior). Las claves y los ajustes necesitan admin. Parar una sesión necesita tech o superior. Las escrituras llevan X-Change-Reason y quedan en el registro de auditoría; no son configuración versionada y no aceptan dry_run.

#Resumen

{"enabled": true, "status": "enabled", "available": true,
 "api_url": "https://browsers.openwaf.dev", "plan": "beta",
 "quota": {"browser_hours": 20, "egress_gb": 5, "concurrency": 2, "max_session_minutes": 60, "max_keys": 5},
 "settings": {"egress_mode": "open", "allow": [], "web_bot_auth": true},
 "period": {"start": "2026-10-01T00:00:00Z", "end": "2026-11-01T00:00:00Z"},
 "usage": {"browser_seconds": 4310, "egress_bytes": 123456789, "sessions": 31, "denied_requests": 4},
 "usage_updated_at": "2026-10-29T12:01:00Z",
 "warning": false,
 "capacity": {"max_sessions": 5, "running": 2, "busy": false},
 "requirements": {"owners_email_verified": true, "owners_two_factor": true}}

• status es enabled, not_enabled o quota_exceeded.
• warning es true cuando las horas de navegador o la salida llegan al 80 % de la cuota.
• capacity es la capacidad compartida del servicio, o null si no se conoce.
• requirements dice si cada propietario y cada administrador tiene el email verificado y la verificación en dos pasos, que la aprobación exige.

#Ajustes

{"egress_mode": "allowlist", "allow": ["example.com", "*.example.com"], "web_bot_auth": true}

#Claves

{"id": "6f1c…", "name": "ci-agent", "prefix": "bdk_AbC1", "disabled": false,
 "created_at": "2026-10-29T10:00:00Z", "created_by": "…", "rotated_at": null}

El nombre cumple ^[a-z0-9][a-z0-9-]{0,62}$ y es único en la organización. disabled es true mientras la organización supera la cuota o no está activada. El secret de una respuesta de creación o rotación se enseña una sola vez, con Cache-Control: no-store.

#Uso

GET /browsers/usage?from=RFC3339&to=RFC3339&step=day|hour. Sin parámetros: el mes en curso, por día.

{"from": "…", "to": "…", "step": "day",
 "series": [{"t": "2026-10-29T00:00:00Z", "browser_seconds": 1800, "egress_bytes": 52428800, "sessions": 6, "denied_requests": 1}],
 "by_key": [{"key_id": "6f1c…", "name": "ci-agent", "browser_seconds": 1800, "egress_bytes": 52428800, "sessions": 6, "denied_requests": 1}],
 "totals": {"browser_seconds": 1800, "egress_bytes": 52428800, "sessions": 6, "denied_requests": 1},
 "quota": {…}, "period": {"start": "…", "end": "…"}, "usage": {…}}

usage es lo que va de mes, la cifra con la que se compara la cuota. El uso se recoge cada minuto, así que las cifras van con hasta unos dos minutos de retraso.

#Sesiones

GET /browsers/sessions?status=running:

{"items": [{"id": "bs_…", "key_id": "6f1c…", "key_name": "ci-agent", "status": "running",
            "created_at": "…", "started_at": "…", "stopped_at": null, "stop_reason": null,
            "live_url": "https://browsers.openwaf.dev/…", "metadata": {"task": "quickstart"}}]}

status es running, idle o stopped. live_url es un enlace firmado de solo lectura, presente solo mientras el navegador está en marcha y válido 1 hora.

#Registro de salida

GET /browsers/egress?key=<id>&since=RFC3339&decision=deny&limit=200. Del más reciente al más antiguo; limit hasta 1000, por defecto 200.

{"items": [{"ts": "…", "key_id": "6f1c…", "key_name": "ci-agent", "session": "bs_…",
            "method": "CONNECT", "host": "example.com", "port": 443, "decision": "allow", "reason": "",
            "status": 200, "bytes_up": 1830, "bytes_down": 48211, "ms": 412}]}

decision es allow, deny o error; reason dice por qué se denegó una petición.

#Errores de la API de gestión

#Acceso por operador

La aprobación la hace un operador, no es una ruta para clientes: un operador activa OpenWAF Browsers para la organización con un motivo y, si hace falta, otra cuota. Falla mientras algún propietario o administrador no tenga el email verificado o la verificación en dos pasos. Para pedirlo, mira pedir acceso.

#CLI

openwaf-cloud ctl browsers … llama a la API de gestión. Cada cambio lleva --reason "…", enseña lo que va a hacer y pregunta antes de aplicarlo. --yes aplica sin preguntar (obligatorio sin terminal, como en CI); --dry-run solo lo enseña. Las lecturas aceptan --json para la respuesta de la API tal cual. Mira empezar con la CLI y cambios.

#Herramientas MCP

El servidor MCP de OpenWAF tiene 10 herramientas para OpenWAF Browsers. Las escrituras necesitan un reason y siguen los dos pasos de las demás herramientas no versionadas: confirm=false solo comprueba, confirm=true aplica, sin expected_version.

Las herramientas MCP gestionan la organización. Para manejar un navegador desde un asistente, usa el servidor MCP de Playwright con el cdpUrl del navegador, como en el inicio rápido.