Documentazione API V7

Crea VM browser con una singola chiamata lato server e ricevi un link condivisibile

Crea la tua chiave API nella dashboard di browser.lol. Il tuo account deve avere accesso all’API.

L'API semplifica la creazione del workspace riducendola a una singola chiamata lato server. Ti autentichi con la tua chiave API, crei il workspace e ricevi nella risposta un link da condividere. L'utente finale apre il link nel proprio browser e viene connesso automaticamente al workspace.

Autenticazione

Passa la tua chiave API come Bearer token nell'header Authorization. La chiave API è il session ID associato al tuo account (con accesso API abilitato).

Authorization: Bearer YOUR_API_KEY

Importante: Mantieni segreta la tua chiave API. Tutte le chiamate API vanno effettuate dal tuo server, mai da codice lato client.

POST/v8/vm/create

Crea una nuova VM di browser virtuale e restituisce un link da condividere con gli utenti finali.

Corpo della richiesta (JSON):

browser (obbligatorio): L'immagine di browser da usare.

url (facoltativo): L'URL da aprire nel browser virtuale. Fino a 10.000 caratteri.

language (facoltativo): Codice lingua del browser (es. en, de). Ricade sul default dell'account oppure en.

layout (facoltativo): Codice del layout di tastiera (es. us, de). Ricade sul default dell'account oppure us.

country (facoltativo): Codice paese ISO a due lettere per la posizione VPN (es. us, de, gb).

shareLanguage (facoltativo): Segmento di lingua usato nel percorso dell'URL di condivisione restituito. Valori supportati: en, de, fr, es, it, pt, ja. Valore predefinito: en.

callbackUrl (facoltativo): URL HTTP o HTTPS da aprire al termine della sessione. Massimo 2000 caratteri. Se omesso, si torna a /create.

Corpo della risposta in caso di successo:

{
  "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 risposta torna non appena la sessione viene accettata. Il vmId restituito parte nello stato starting mentre il browser viene preparato in background, poi passa a running, di solito in pochi secondi. Il link da condividere mostra una schermata di caricamento finché la sessione non è pronta; se la preparazione fallisce su tutti i server, la sessione termina nello stato "error".

Richiesta di esempio:

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

Accedere al workspace

Condividi il shareUrl restituito dalla risposta con l'utente finale. Quando apre il link nel proprio browser, viene collegato automaticamente alla sessione del browser virtuale. Non servono ulteriori passaggi.

I link di condivisione sono legati alla VM. Quando la VM viene eliminata, il link diventa non valido.

L'URL di condivisione contiene un segmento di lingua (en) che controlla la lingua della pagina del viewer. Sostituiscilo con una qualsiasi lingua supportata: de, fr, es, it, pt, ja. Puoi anche passare shareLanguage nel corpo della richiesta per ricevere l'URL già con la lingua applicata.

GET/v8/user/api

Restituisce lo stato dell'accesso programmatico e l'utilizzo delle sessioni per l'utente autenticato.

Corpo della risposta in caso di successo:

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

Campi della quota:

cycle_session_limit: Sessioni totali consentite per ciclo di fatturazione, oppure null per i piani illimitati.

cycle_sessions_used: Sessioni utilizzate nel ciclo in corso.

cycle_sessions_remaining: Sessioni rimanenti (cycle_session_limit - cycle_sessions_used), oppure null per i piani illimitati.

running_session_limit: Numero massimo di sessioni eseguibili in parallelo.

running_sessions_used: Numero di sessioni attualmente in esecuzione.

running_sessions_remaining: Numero di sessioni aggiuntive che possono essere avviate subito.

cycle_start: Data di inizio del ciclo di fatturazione (YYYY-MM-DD).

Richiesta di esempio:

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

GET/v8/user/quota

Restituisce solo i limiti e l'utilizzo delle sessioni per l'utente autenticato. È un endpoint leggero, senza metadati API aggiuntivi.

Corpo della risposta in caso di successo:

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

Richiesta di esempio:

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

Per i piani illimitati, cycle_session_limit e cycle_sessions_remaining saranno null, cioè non viene applicato alcun limite.

Possibili errori/v7/*

Tutte le risposte di errore seguono lo stesso formato con un campo status e un message leggibile.

Accesso negato (chiave API non valida, API non abilitata o quota superata):

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

Controllo di sicurezza fallito (rate limiting o richiesta insicura):

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

Errore del server:

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