Référence de l'API v8

Lance une session, partage-la, suis son état, termine-la et consulte ton utilisation.

Crée ta clé API dans la section Avancé de la page Agents. Ton compte doit disposer de l'accès programmatique.

Envoie des requêtes HTTPS authentifiées pour lancer des sessions. Une session est acceptée immédiatement et démarre en arrière-plan : suis son état jusqu'à ce qu'elle tourne, partage son lien avec la personne qui doit la voir, puis termine-la quand tu as fini.

URL de base

Tous les chemins de cette page sont relatifs à cette adresse.

https://api.browser.lol/v8

Authentification

Transmets ta clé API comme jeton Bearer dans l'en-tête Authorization.

Authorization: Bearer YOUR_API_KEY

Important : Garde ta clé API secrète. Envoie les requêtes depuis ton serveur et n'expose jamais la clé dans du code exécuté par le navigateur.

Réponses

Les points d'accès répondent avec HTTP 200 et un corps JSON dont le champ status indique l'issue de la requête. Décide en fonction de status, pas du code HTTP, et affiche message quand il ne vaut pas ok. Seules les vérifications d'authentification et de limitation du débit peuvent répondre avec un autre code HTTP.

ok: La requête a abouti.
denied: La requête a été refusée, par exemple à cause d'une clé invalide, d'une session inconnue ou d'un champ invalide.
upgrade: Ton offre n'inclut pas ce que demande la requête, ou l'une de ses limites est atteinte. Une offre qui l'inclut règle le problème.
insecure: Une vérification de sécurité ou de débit a échoué. reason indique laquelle.
error: Un problème est survenu de notre côté. Réessaie plus tard.

Exemples

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

Navigateurs et emplacements

GET/v8/image

Liste les navigateurs que tu peux lancer et les emplacements de sortie que tu peux choisir. Ce point d'accès ne demande pas de clé API.

images[].id est la valeur de browser au lancement d'une session ; enabled indique si le navigateur peut démarrer maintenant.
vpnLocations[] liste chaque pays par code avec ses villes dans cities[].code. Les deux codes fonctionnent pour country.
residential.countries liste les pays qu'une connexion résidentielle peut utiliser ; null signifie tous les pays.

Exemple de requête

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

Réponse (abrégée)

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

Lancer une session

POST/v8/vm/create

Accepte une nouvelle session et renvoie aussitôt son identifiant. La session est préparée en arrière-plan.

Champs JSON de la requête

browserobligatoire: Identifiant du navigateur issu de GET /image.
urlfacultatif: Page à ouvrir en premier, 10 000 caractères au maximum.
languagefacultatif: Langue de l'interface du navigateur, par exemple en ou de. Par défaut, le réglage de ton compte, sinon en.
layoutfacultatif: Disposition du clavier, par exemple us ou de. Par défaut, le réglage de ton compte, sinon us.
countryfacultatif: Emplacement de sortie : un code pays comme us, de ou uk, ou un code ville comme us-dal, tels que GET /image les liste. Avec auto, le service choisit. Nécessite l'accès aux emplacements.
egressfacultatif: Indique residential pour naviguer via une connexion résidentielle. Nécessite des données résidentielles dans ton offre ; seule la partie pays de country est utilisée.
shareLanguagefacultatif: Langue de la visionneuse dans le lien de partage : en, de, fr, es, it, pt ou ja. Par défaut en.
callbackUrlfacultatif: Adresse HTTP ou HTTPS que la visionneuse ouvre quand quelqu'un quitte la session ou son écran de fin, 2 000 caractères au maximum. Sans elle, la visionneuse revient à la page de lancement.
idempotencyKeyfacultatif: Ta propre clé de 1 à 128 caractères. Si tu renvoies la même requête avec la même clé, tu reçois la première réponse réussie au lieu de lancer une deuxième session.

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

Réponse

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

La réponse arrive dès que la session est acceptée. La session démarre à l'état starting et passe à running quand elle est prête, ou à error si elle ne peut pas démarrer. shareUrl est présent quand le lien de partage a pu être créé.

État d'une session

GET/v8/vm/data?id=VM_ID

Renvoie tes sessions du dernier mois, de la plus récente à la plus ancienne. Passe le vmId reçu au lancement comme id pour n'obtenir que cette session.

Exemple de requête

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

Réponse (abrégée)

{
  "status": "ok",
  "data": [
    {
      "id": "brl-v-v7-*******...abc123",
      "status": "running",
      "name": "Chrome",
      "created": "2026-10-01T12:00:00.000Z",
      ...
    }
  ]
}

Interroge toutes les quelques secondes jusqu'à ce que data[0].status vaille running. error signifie que la session n'a pas pu démarrer ; stopping, suspended et deleted signifient qu'elle est terminée. Une liste data vide signifie que cette session n'existe pas. L<code>id</code> de la réponse est partiellement masqué.

Terminer une session

POST/v8/vm/remove

Termine une session. Passe son vmId comme id. Une session déjà terminée répond aussi ok.

Exemple de requête

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

Réponse

{"status": "ok"}

Compte et utilisation

GET/v8/user/api

Renvoie ton adresse de contact, l'état de l'accès programmatique et ton utilisation des sessions et des données résidentielles.

Exemple de requête

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

Réponse

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

Champs d'utilisation

cycle_session_limit: Nombre maximal de sessions dans le cycle en cours, ou null sans plafond.
cycle_sessions_used: Sessions lancées dans le cycle en cours.
cycle_sessions_remaining: Sessions restantes dans le cycle en cours, ou null sans plafond.
running_session_limit: Nombre maximal de sessions simultanées.
running_sessions_used: Sessions actuellement comptées comme en cours.
running_sessions_remaining: Places restantes sous cette limite. D'autres vérifications s'appliquent toujours au lancement.
cycle_start: Date de début du cycle en cours (AAAA-MM-JJ).
residential_cycle_mb_limit: Données résidentielles incluses par cycle, en Mo, ou null quand aucun quota ne s'applique.
residential_bytes_used_cycle: Données résidentielles utilisées dans le cycle en cours, en octets.
pools: Les mêmes compteurs pour chaque abonnement derrière les totaux, avec subscription_id, plan_id et plan_name.

Utilisation seule

GET/v8/user/quota

Renvoie les mêmes champs d'utilisation que GET /user/api, sans l'adresse de contact ni l'indicateur d'accès programmatique.

Exemple de requête

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

Réponse

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

URL de base

Authentification

Réponses

Exemples

Navigateurs et emplacements

Exemple de requête

Réponse (abrégée)

Lancer une session

Champs JSON de la requête

Exemple de requête

Réponse

État d'une session

Exemple de requête

Réponse (abrégée)

Partager la session

Terminer une session

Exemple de requête

Réponse

Compte et utilisation

Exemple de requête

Réponse

Champs d'utilisation

Utilisation seule

Exemple de requête

Réponse