Documentation API V7

Crée des VM de navigateur en un seul appel côté serveur et récupère un lien partageable

Crée ta clé API depuis le tableau de bord browser.lol. Ton compte doit disposer de l’accès API.

L'API simplifie la création de workspaces en un seul appel côté serveur. Tu t'authentifies avec ta clé API, tu crées le workspace et tu récupères un lien partageable dans la réponse. L'utilisateur final ouvre simplement le lien dans son navigateur et est automatiquement connecté au workspace.

Authentification

Passe ta clé API en token Bearer dans l'en-tête Authorization. La clé API est l'ID de session associé à ton compte (avec l'accès API activé).

Authorization: Bearer YOUR_API_KEY

Important : Garde ta clé API secrète. Tous les appels API doivent être faits depuis ton serveur, jamais depuis du code côté client.

POST/v8/vm/create

Crée une nouvelle VM de navigateur virtuel et renvoie un lien partageable à transmettre aux utilisateurs finaux.

Corps de la requête (JSON) :

browser (requis) : l'image de navigateur à utiliser.

url (facultatif) : l'URL à ouvrir dans le navigateur virtuel. Jusqu'à 10 000 caractères.

language (facultatif) : code de langue du navigateur (ex. en, de). Repli sur la valeur par défaut du compte ou en.

layout (facultatif) : code de disposition clavier (ex. us, de). Repli sur la valeur par défaut du compte ou us.

country (facultatif) : code pays ISO à deux lettres pour la localisation du VPN (ex. us, de, gb).

shareLanguage (facultatif) : segment de locale utilisé dans le chemin de l'URL de partage renvoyée. Valeurs prises en charge : en, de, fr, es, it, pt, ja. Par défaut en.

callbackUrl (facultatif): URL HTTP ou HTTPS ouverte à la fin de la session. 2 000 caractères maximum. Sans cette URL, le navigateur revient à /create.

Corps de réponse en cas de succès :

{
  "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 réponse revient dès que la session est acceptée. Le vmId renvoyé démarre au statut starting pendant que le navigateur se prépare en arrière-plan, puis passe à running, généralement en quelques secondes. Le lien partageable affiche un écran de chargement tant que la session n'est pas prête. Si la préparation échoue sur tous les serveurs, la session se termine au statut "error".

Exemple de requête :

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

Accéder au workspace

Partage le shareUrl de la réponse avec l'utilisateur final. Dès qu'il ouvre le lien dans son navigateur, il rejoint automatiquement la session de navigateur virtuel. Il n'a rien d'autre à faire.

Les liens de partage sont liés à la VM. Quand la VM est supprimée, le lien devient invalide.

L'URL de partage contient un code de langue (en) qui détermine la langue de la page de consultation. Tu peux le remplacer par l'un des codes pris en charge : de, fr, es, it, pt, ja. Tu peux aussi passer shareLanguage dans le corps de la requête pour que l'API renvoie directement l'URL dans la langue choisie.

GET/v8/user/api

Indique si l'utilisateur authentifié a accès à l'API et renvoie le nombre de sessions utilisées.

Corps de réponse en cas de succès :

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

Champs du quota :

cycle_session_limit : nombre total de sessions autorisées par cycle de facturation, ou null pour les forfaits illimités.

cycle_sessions_used : nombre de sessions utilisées sur le cycle en cours.

cycle_sessions_remaining : sessions restantes (cycle_session_limit - cycle_sessions_used), ou null pour les forfaits illimités.

running_session_limit : nombre maximal de sessions pouvant tourner en même temps.

running_sessions_used : nombre de sessions en cours d'exécution.

running_sessions_remaining : nombre de sessions supplémentaires pouvant être lancées immédiatement.

cycle_start : date de début du cycle de facturation (AAAA-MM-JJ).

Exemple de requête :

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

GET/v8/user/quota

Renvoie uniquement les limites et l'utilisation des sessions de l'utilisateur authentifié. Ce point d'accès léger n'inclut pas les autres métadonnées de l'API.

Corps de réponse en cas de succès :

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

Exemple de requête :

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

Pour les forfaits illimités, cycle_session_limit et cycle_sessions_remaining seront null, ce qui veut dire qu'aucun plafond n'est appliqué.

Erreurs possibles/v7/*

Toutes les réponses d'erreur suivent le même format avec un champ status et un message lisible par un humain.

Accès refusé (clé API invalide, API non activée ou quota dépassé) :

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

Échec du contrôle de sécurité (trop de requêtes ou requête non sécurisée) :

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

Erreur serveur :

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