Documentação da API V7

Cria VMs de navegador com uma única chamada do lado do servidor e recebe uma ligação partilhável

Cria a tua chave API no painel de browser.lol. A tua conta precisa de acesso à API.

A API reduz a criação de workspaces a uma única chamada no servidor. Autenticas-te com a tua chave de API, crias o workspace e recebes uma ligação partilhável na resposta. O utilizador final só tem de abrir a ligação partilhável no navegador e fica logo ligado ao workspace.

Autenticação

Passa a tua chave de API como Bearer token no cabeçalho Authorization. A chave de API é o ID de sessão associado à tua conta (com acesso à API ativado).

Authorization: Bearer YOUR_API_KEY

Importante: Mantém a tua chave de API em segredo. Todas as chamadas à API devem ser feitas a partir do teu servidor, nunca a partir de código do lado do cliente.

POST/v8/vm/create

Cria uma nova VM de navegador virtual e devolve uma ligação partilhável que podes dar aos utilizadores finais.

Corpo do pedido (JSON):

browser (obrigatório): A imagem de navegador a usar.

url (opcional): O URL a abrir no navegador virtual. Até 10 000 caracteres.

language (opcional): Código do idioma do navegador (ex.: en, de). Recorre ao valor predefinido da conta ou a en.

layout (opcional): Código da disposição de teclado (ex.: us, de). Recorre ao valor predefinido da conta ou a us.

country (opcional): Código ISO do país em duas letras para a localização VPN (ex.: us, de, gb).

shareLanguage (opcional): Segmento de idioma usado no caminho do URL de partilha devolvido. Valores suportados: en, de, fr, es, it, pt, ja. Predefinição: en.

callbackUrl (opcional): URL HTTP ou HTTPS aberto quando a sessão termina. Máximo de 2000 caracteres. Se não o indicares, regressas a /create.

Corpo da resposta em caso de sucesso:

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

A resposta volta assim que a sessão é aceite. O vmId devolvido começa no estado starting enquanto o navegador é preparado em segundo plano e depois passa a running, normalmente em poucos segundos. A ligação partilhável mostra um ecrã de carregamento até a sessão estar pronta; se a preparação falhar em todos os servidores, a sessão termina no estado "error".

Pedido de exemplo:

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

Aceder ao workspace

Partilha o shareUrl da resposta com o utilizador final. Quando ele abre a ligação no navegador, fica logo ligado à sessão de navegador virtual. Não são precisos passos adicionais.

As ligações de partilha estão associadas à VM. Quando a VM é apagada, a ligação de partilha fica inválida.

O URL de partilha contém um segmento de idioma (en) que controla o idioma da página do visualizador. Substitui-o por qualquer idioma suportado: de, fr, es, it, pt, ja. Também podes enviar shareLanguage no corpo do pedido para que a API devolva o URL já com esse idioma aplicado.

GET/v8/user/api

Devolve o estado do acesso programático e a utilização das sessões do utilizador autenticado.

Corpo da resposta em caso de sucesso:

{
  "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 quota:

cycle_session_limit: Total de sessões permitidas por ciclo de faturação, ou null em planos ilimitados.

cycle_sessions_used: Sessões utilizadas no ciclo atual.

cycle_sessions_remaining: Sessões restantes (cycle_session_limit - cycle_sessions_used), ou null em planos ilimitados.

running_session_limit: Número máximo de sessões que podem estar em execução ao mesmo tempo.

running_sessions_used: Número de sessões atualmente em execução.

running_sessions_remaining: Número de sessões adicionais que podem ser iniciadas de imediato.

cycle_start: Data de início do ciclo de faturação (AAAA-MM-DD).

Pedido de exemplo:

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

GET/v8/user/quota

Devolve apenas os limites e a utilização das sessões do utilizador autenticado. É um endpoint leve, sem os metadados adicionais da API.

Corpo da resposta em caso de sucesso:

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

Pedido de exemplo:

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

Em planos ilimitados, cycle_session_limit e cycle_sessions_remaining serão null, o que significa que não é aplicado nenhum limite.

Erros possíveis/v7/*

Todas as respostas de erro seguem o mesmo formato, com um campo status e uma message legível.

Acesso negado (chave de API inválida, API não ativada ou quota excedida):

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

Verificação de segurança falhou (limite de pedidos atingido ou pedido inseguro):

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

Erro no servidor:

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