Documentación de la API V7

Crea VMs de navegador con una sola llamada desde el servidor y recibe un enlace para compartir

Crea tu clave API en el panel de browser.lol. Tu cuenta debe tener acceso a la API.

La API reduce la creación de un workspace a una sola llamada desde el servidor. Te autenticas con tu clave de API, creas el workspace y recibes un enlace para compartir en la respuesta. El usuario final solo tiene que abrir ese enlace en su navegador y se conecta automáticamente al workspace.

Autenticación

Pasa tu clave de API como token Bearer en la cabecera Authorization. La clave de API es el ID de sesión asociado a tu cuenta (con acceso a la API habilitado).

Authorization: Bearer YOUR_API_KEY

Importante: Mantén tu clave de API en secreto. Todas las llamadas a la API deben hacerse desde tu servidor, nunca desde código del cliente.

POST/v8/vm/create

Crea una nueva VM de navegador virtual y devuelve un enlace para compartir que puedes entregar a los usuarios finales.

Cuerpo de la petición (JSON):

browser (obligatorio): La imagen de navegador a usar.

url (opcional): La URL a abrir en el navegador virtual. Hasta 10.000 caracteres.

language (opcional): Código de idioma del navegador (p. ej. en, de). Si no se indica, se usa el valor por defecto de la cuenta o en.

layout (opcional): Código de distribución de teclado (p. ej. us, de). Si no se indica, se usa el valor por defecto de la cuenta o us.

country (opcional): Código de país ISO de dos letras para la ubicación de la VPN (p. ej. us, de, gb).

shareLanguage (opcional): Segmento de idioma que se usa en la ruta de la URL para compartir devuelta. Valores admitidos: en, de, fr, es, it, pt, ja. Por defecto en.

callbackUrl (opcional): URL HTTP o HTTPS que se abre al finalizar la sesión. Máximo de 2000 caracteres. Si se omite, se vuelve a /create.

Cuerpo de la respuesta en caso de éxito:

{
  "status": "ok",
  "vmId": "brl-v-v7-abc123...",
  "shareUrl": "https://browser.lol/en/s?LINK_ID",
  "shareUrlPath": "/en/s?LINK_ID",
  "quota": {
    "running_session_limit": 10,
    "running_sessions_used": 4,
    "running_sessions_remaining": 6,
    "cycle_session_limit": 1000,
    "cycle_sessions_used": 143,
    "cycle_sessions_remaining": 857,
    "cycle_start": "2026-03-01"
  }
}

La respuesta vuelve en cuanto la sesión queda aceptada. El vmId devuelto empieza en el estado starting mientras el navegador se prepara en segundo plano y después pasa a running, normalmente en unos segundos. El enlace para compartir muestra una pantalla de carga hasta que la sesión está lista; si la preparación falla en todos los servidores, la sesión termina en el estado "error".

Ejemplo de petición:

curl -X POST https://api.browser.lol/v8/vm/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"browser": "chrome", "url": "https://example.com", "callbackUrl": "https://your-app.example.com/done"}'

Acceder al workspace

Comparte el shareUrl de la respuesta con el usuario final. Cuando abra el enlace en su navegador, se conectará automáticamente a la sesión del navegador virtual. No hace falta ningún paso adicional.

Los enlaces para compartir están ligados a la VM. Cuando la VM se elimina, el enlace deja de ser válido.

La URL para compartir contiene un segmento de idioma (en) que controla el idioma de la página del visor. Reemplázalo por cualquier idioma admitido: de, fr, es, it, pt, ja. También puedes enviar shareLanguage en el cuerpo de la petición para que la API devuelva la URL ya con ese idioma.

GET/v8/user/api

Devuelve el estado del acceso programático y el uso de sesiones del usuario autenticado.

Cuerpo de la respuesta en caso de éxito:

{
  "status": "ok",
  "contact": "[email protected]",
  "feature_programmatic_access": true,
  "running_session_limit": 10,
  "running_sessions_used": 3,
  "running_sessions_remaining": 7,
  "cycle_session_limit": 1000,
  "cycle_sessions_used": 142,
  "cycle_sessions_remaining": 858,
  "cycle_start": "2026-03-01",
  "has_plan": true
}

Campos de cuota:

cycle_session_limit: Sesiones totales permitidas por ciclo de facturación, o null para planes ilimitados.

cycle_sessions_used: Sesiones utilizadas en el ciclo actual.

cycle_sessions_remaining: Sesiones restantes (cycle_session_limit - cycle_sessions_used), o null para planes ilimitados.

running_session_limit: Número máximo de sesiones que pueden ejecutarse a la vez.

running_sessions_used: Número de sesiones que se están ejecutando.

running_sessions_remaining: Número de sesiones adicionales que pueden iniciarse de inmediato.

cycle_start: Fecha de inicio del ciclo de facturación (YYYY-MM-DD).

Ejemplo de petición:

curl https://api.browser.lol/v8/user/api \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v8/user/quota

Devuelve solo los límites y el uso de sesiones del usuario autenticado. Es un endpoint ligero, sin los metadatos adicionales de la API.

Cuerpo de la respuesta en caso de éxito:

{
  "status": "ok",
  "has_plan": true,
  "running_session_limit": 10,
  "running_sessions_used": 3,
  "running_sessions_remaining": 7,
  "cycle_session_limit": 1000,
  "cycle_sessions_used": 142,
  "cycle_sessions_remaining": 858,
  "cycle_start": "2026-03-01"
}

Ejemplo de petición:

curl https://api.browser.lol/v8/user/quota \
  -H "Authorization: Bearer YOUR_API_KEY"

Para planes ilimitados, cycle_session_limit y cycle_sessions_remaining serán null, lo que significa que no se aplica ningún límite.

Posibles errores/v7/*

Todas las respuestas de error siguen el mismo formato, con un campo status y un message legible.

Acceso denegado (clave de API no válida, API no habilitada o cuota superada):

{"status": "denied", "message": "The API key you provided is invalid..."}

Comprobación de seguridad fallida (límite de peticiones superado o petición insegura):

{"status": "insecure", "message": "..."}

Error del servidor:

{"status": "error", "message": "Something went wrong..."}