Referência da API v8

Inicia uma sessão, partilha-a, acompanha o estado, termina-a e consulta a tua utilização.

Cria a tua chave API em Avançado, na página Agentes. A tua conta precisa de acesso programático.

Envia pedidos HTTPS autenticados para iniciar sessões. Cada sessão é aceite de imediato e arranca em segundo plano: acompanha o estado até estar em execução, partilha a ligação com quem a deve ver e termina-a quando acabares.

URL base

Todos os caminhos desta página são relativos a este endereço.

https://api.browser.lol/v8

Autenticação

Envia a tua chave API como token Bearer no cabeçalho Authorization.

Authorization: Bearer YOUR_API_KEY
Importante: Mantém a chave API em segredo. Envia os pedidos a partir do teu servidor e nunca exponhas a chave em código executado no navegador.

Respostas

Os endpoints respondem com HTTP 200 e um corpo JSON cujo status diz como correu o pedido. Decide com base em status, não no código HTTP, e mostra message quando não for ok. Só as verificações de autenticação e de limitação de pedidos podem responder com outro código HTTP.

ok
O pedido foi concluído.
denied
O pedido foi recusado, por exemplo por uma chave inválida, uma sessão desconhecida ou um campo inválido.
upgrade
O teu plano não inclui o que o pedido exige, ou foi atingido um dos seus limites. Um plano que o inclua resolve a situação.
insecure
Falhou uma verificação de segurança ou de frequência. reason indica qual.
error
Algo correu mal do nosso lado. Tenta novamente mais tarde.

Exemplos

{"status": "denied", "message": "Unsupported VPN location"}
{"status": "upgrade", "message": "..."}
{"status": "insecure", "reason": "rate_limited", "message": "..."}
{"status": "error", "message": "..."}

Navegadores e localizações

GET/v8/image

Lista os navegadores que podes iniciar e as localizações de saída que podes escolher. Este endpoint não precisa de chave API.

  • images[].id é o valor de browser quando inicias uma sessão; enabled indica se o navegador pode arrancar agora.
  • vpnLocations[] lista cada país pelo code com as suas cidades em cities[].code. Qualquer um dos códigos serve como country.
  • residential.countries lista os países que uma ligação residencial pode usar; null significa todos.

Pedido de exemplo

curl https://api.browser.lol/v8/image

Resposta (resumida)

{
  "status": "ok",
  "images": [
    { "id": "chrome", "name": "Chrome", "enabled": true, ... }
  ],
  "vpnLocations": [
    {
      "code": "uk",
      "name": "United Kingdom",
      "default": "uk-lon",
      "cities": [{ "code": "uk-lon", "location": "London" }, ...]
    }
  ],
  "residential": { "configured": true, "countries": null }
}

Iniciar uma sessão

POST/v8/vm/create

Aceita uma nova sessão e devolve o respetivo ID de imediato. A sessão é preparada em segundo plano.

Campos JSON do pedido

browserobrigatório
ID do navegador obtido em GET /image.
urlopcional
Página a abrir primeiro, até 10 000 caracteres.
languageopcional
Idioma da interface do navegador, por exemplo en ou de. Por predefinição, a definição da tua conta ou, na falta dela, en.
layoutopcional
Esquema de teclado, por exemplo us ou de. Por predefinição, a definição da tua conta ou, na falta dela, us.
countryopcional
Localização de saída: um código de país como us, de ou uk, ou um código de cidade como us-dal, tal como GET /image os lista. Com auto, o serviço escolhe. Requer acesso a localizações.
egressopcional
Define residential para navegar através de uma ligação residencial. Requer dados residenciais no teu plano; de country só conta o país.
shareLanguageopcional
Idioma do visualizador na ligação de partilha: en, de, fr, es, it, pt ou ja. Por predefinição, en.
callbackUrlopcional
Endereço HTTP ou HTTPS que o visualizador abre quando alguém sai da sessão ou do ecrã final, até 2 000 caracteres. Sem ele, o visualizador regressa à página de início.
idempotencyKeyopcional
Uma chave tua com 1 a 128 caracteres. Se repetires o pedido com a mesma chave, recebes a primeira resposta bem-sucedida em vez de iniciar uma segunda sessão.

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", "country": "uk"}'

Resposta

{
  "status": "ok",
  "vmId": "brl-v-v7-abc123...",
  "shareUrl": "https://browser.lol/en/s?LINK_ID",
  "shareUrlPath": "/en/s?LINK_ID",
  "quota": {
    "running_session_limit": 2,
    "running_sessions_used": 1,
    "running_sessions_remaining": 1,
    "cycle_session_limit": null,
    "cycle_sessions_used": 42,
    "cycle_sessions_remaining": null,
    "cycle_start": "2026-10-01"
  }
}
A resposta chega assim que a sessão é aceite. A sessão começa no estado starting e passa a running quando está pronta, ou a error se não conseguir arrancar. shareUrl está presente quando foi possível criar a ligação de partilha.

Estado de uma sessão

GET/v8/vm/data?id=VM_ID

Devolve as tuas sessões do último mês, da mais recente para a mais antiga. Passa o vmId recebido no início como id para obteres só essa sessão.

Pedido de exemplo

curl "https://api.browser.lol/v8/vm/data?id=VM_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Resposta (resumida)

{
  "status": "ok",
  "data": [
    {
      "id": "brl-v-v7-*******...abc123",
      "status": "running",
      "name": "Chrome",
      "created": "2026-10-01T12:00:00.000Z",
      ...
    }
  ]
}
Consulta de poucos em poucos segundos até data[0].status ser running. error significa que a sessão não conseguiu arrancar; stopping, suspended e deleted significam que terminou. Uma lista data vazia significa que essa sessão não existe. O id na resposta está parcialmente ocultado.

Partilhar a sessão

Dá o shareUrl recebido no início a quem deve abrir o visualizador. A página espera até a sessão estar pronta. Trata esta ligação como uma palavra-passe da sessão.

Uma ligação de partilha pertence a uma única sessão e deixa de funcionar quando a sessão é eliminada.
A ligação de partilha inclui um segmento de idioma (en) para o visualizador. Podes substituí-lo por de, fr, es, it, pt ou ja, ou definir shareLanguage ao iniciar a sessão.

Terminar uma sessão

POST/v8/vm/remove

Termina uma sessão. Passa o respetivo vmId como id. Uma sessão que já terminou também responde ok.

Pedido de exemplo

curl -X POST https://api.browser.lol/v8/vm/remove \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "VM_ID"}'

Resposta

{"status": "ok"}

Conta e utilização

GET/v8/user/api

Devolve o teu endereço de contacto, se o acesso programático está ativo e a tua utilização de sessões e de dados residenciais.

Pedido de exemplo

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

Resposta

{
  "status": "ok",
  "contact": "[email protected]",
  "feature_programmatic_access": true,
  "has_plan": true,
  "cycle_start": "2026-10-01",
  "cycle_session_limit": null,
  "cycle_sessions_used": 42,
  "cycle_sessions_remaining": null,
  "running_session_limit": 2,
  "running_sessions_used": 1,
  "running_sessions_remaining": 1,
  "residential_cycle_mb_limit": 6000,
  "residential_bytes_used_cycle": 104857600,
  "pools": [
    {
      "subscription_id": "brl-s-v7-abc123...",
      "plan_id": "browser-premium",
      "plan_name": "Premium",
      "cycle_start": "2026-10-01",
      "cycle_session_limit": null,
      "cycle_sessions_used": 42,
      "cycle_sessions_remaining": null,
      "running_session_limit": 2,
      "running_sessions_used": 1,
      "running_sessions_remaining": 1,
      "residential_cycle_mb_limit": 6000,
      "residential_bytes_used_cycle": 104857600
    }
  ]
}

Campos de utilização

cycle_session_limit
Número máximo de sessões no ciclo atual, ou null sem limite.
cycle_sessions_used
Sessões iniciadas no ciclo atual.
cycle_sessions_remaining
Sessões que restam no ciclo atual, ou null sem limite.
running_session_limit
Número máximo de sessões em simultâneo.
running_sessions_used
Sessões que contam neste momento como em execução.
running_sessions_remaining
Vagas livres dentro desse limite. Continuam a aplicar-se outras verificações no início.
cycle_start
Data de início do ciclo atual (AAAA-MM-DD).
residential_cycle_mb_limit
Dados residenciais incluídos por ciclo, em MB, ou null quando não se aplica nenhuma franquia.
residential_bytes_used_cycle
Dados residenciais usados no ciclo atual, em bytes.
pools
Os mesmos contadores para cada subscrição por trás dos totais, com subscription_id, plan_id e plan_name.

Só a utilização

GET/v8/user/quota

Devolve os mesmos campos de utilização que GET /user/api, sem o endereço de contacto nem o indicador de acesso programático.

Pedido de exemplo

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

Resposta

{
  "status": "ok",
  "has_plan": true,
  "cycle_start": "2026-10-01",
  "cycle_session_limit": null,
  "cycle_sessions_used": 42,
  "cycle_sessions_remaining": null,
  "running_session_limit": 2,
  "running_sessions_used": 1,
  "running_sessions_remaining": 1,
  "residential_cycle_mb_limit": 6000,
  "residential_bytes_used_cycle": 104857600,
  "pools": [
    {
      "subscription_id": "brl-s-v7-abc123...",
      "plan_id": "browser-premium",
      "plan_name": "Premium",
      "cycle_start": "2026-10-01",
      "cycle_session_limit": null,
      "cycle_sessions_used": 42,
      "cycle_sessions_remaining": null,
      "running_session_limit": 2,
      "running_sessions_used": 1,
      "running_sessions_remaining": 1,
      "residential_cycle_mb_limit": 6000,
      "residential_bytes_used_cycle": 104857600
    }
  ]
}