API V7-Dokumentation

Browser-VMs mit einem einzigen serverseitigen Aufruf anlegen und einen teilbaren Link zurückbekommen

Erstelle deinen API-Schlüssel im Dashboard von browser.lol. Dein Konto braucht dafür API-Zugriff.

Mit der V7-API legst du einen Workspace mit einem einzigen serverseitigen Aufruf an. Du authentifizierst dich mit deinem API-Schlüssel, kriegst den Workspace samt Share-Link in der Antwort, und der Endnutzer öffnet den Link einfach in seinem Browser. Damit ist er direkt im Workspace.

Authentifizierung

Schick deinen API-Schlüssel als Bearer-Token im Authorization-Header mit. Der API-Schlüssel ist die Sitzungs-ID deines Kontos (mit aktiviertem API-Zugriff).

Authorization: Bearer YOUR_API_KEY

Wichtig: Halt deinen API-Schlüssel geheim. Alle API-Aufrufe müssen von deinem Server kommen, nie aus clientseitigem Code.

POST/v8/vm/create

Legt eine neue virtuelle Browser-VM an und gibt dir einen Share-Link zurück, den du an Endnutzer weitergibst.

Anfrage-Body (JSON):

browser (erforderlich): Das Browser-Image, das genutzt werden soll.

url (optional): Die URL, die im virtuellen Browser geöffnet wird. Bis zu 10.000 Zeichen.

language (optional): Browsersprachcode (z. B. en, de). Fällt auf den Kontostandard oder en.

layout (optional): Tastaturlayout-Code (z. B. us, de). Fällt auf den Kontostandard oder us.

country (optional): Zweistelliger ISO-Ländercode für den VPN-Standort (z. B. us, de, gb).

shareLanguage (optional): Sprachsegment im zurückgegebenen Share-URL-Pfad. Unterstützte Werte: en, de, fr, es, it, pt, ja. Standard ist en.

callbackUrl (optional): HTTP- oder HTTPS-URL, die der Viewer nach Sitzungsende öffnet. Höchstens 2000 Zeichen. Ohne diese Angabe geht es zurück zu /create.

Antwort-Body bei Erfolg:

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

Die Antwort kommt zurück, sobald die Session angenommen ist. Die zurückgegebene vmId startet im Status starting, während der Browser im Hintergrund vorbereitet wird, und wechselt danach zu running, meist innert weniger Sekunden. Der Share-Link zeigt bis dahin einen Ladebildschirm; schlägt die Vorbereitung auf allen Servern fehl, endet die Session im Status "error".

Beispielanfrage:

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

Auf den Workspace zugreifen

Teil den shareUrl aus der Antwort mit dem Endnutzer. Sobald er den Link in seinem Browser öffnet, ist er automatisch mit der virtuellen Browser-Sitzung verbunden. Weitere Schritte braucht es nicht.

Share-Links hängen an der VM. Löschst du die VM, wird der Share-Link ungültig.

Die Share-URL enthält ein Sprachsegment (en), das die Sprache der Viewer-Seite steuert. Ersetze es durch eine der unterstützten Sprachen: de, fr, es, it, pt, ja. Du kannst auch shareLanguage im Request-Body übergeben, damit die API die URL direkt mit der gewünschten Sprache zurückgibt.

GET/v8/user/api

Gibt für den angemeldeten Nutzer den Status des programmatischen Zugriffs und die Sitzungsnutzung zurück.

Antwort-Body bei Erfolg:

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

Kontingentfelder:

cycle_session_limit: Sitzungen pro Abrechnungszyklus oder null bei unbegrenzten Tarifen.

cycle_sessions_used: Im aktuellen Zyklus genutzte Sitzungen.

cycle_sessions_remaining: Verbleibende Sitzungen (cycle_session_limit - cycle_sessions_used) oder null bei unbegrenzten Tarifen.

running_session_limit: Wie viele Sitzungen maximal gleichzeitig laufen dürfen.

running_sessions_used: Anzahl der gerade laufenden Sitzungen.

running_sessions_remaining: Anzahl der Sitzungen, die jetzt zusätzlich gestartet werden können.

cycle_start: Startdatum des Abrechnungszyklus (JJJJ-MM-TT).

Beispielanfrage:

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

GET/v8/user/quota

Gibt nur die Sitzungslimits und deren Nutzung zurück. Ein schlanker Endpunkt ohne die zusätzlichen API-Metadaten.

Antwort-Body bei Erfolg:

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

Beispielanfrage:

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

Bei unbegrenzten Tarifen sind cycle_session_limit und cycle_sessions_remaining jeweils null, es gilt also keine Obergrenze.

Mögliche Fehler/v7/*

Alle Fehlerantworten haben dasselbe Format: ein status-Feld und eine lesbare message.

Zugriff verweigert (ungültiger API-Schlüssel, API nicht aktiviert oder Kontingent überschritten):

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

Sicherheitsprüfung fehlgeschlagen (zu viele Anfragen oder unsichere Anfrage):

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

Serverfehler:

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