Hier steht, was die API annimmt und zurückgibt. Wie du vom API-Schlüssel zum laufenden Playwright-Skript kommst, zeigt die Anleitung zur eigenen Integration. Einen KI-Assistenten bindest du stattdessen über MCP an.

Grundlagen

Basis-URL

https://api.guard.ch/v7

Authentifizierung

Ein API-Schlüssel im Authorization-Header

Format

JSON über HTTPS

Zugang

Enterprise

Die Pfade in dieser Referenz beziehen sich auf die Basis-URL. Schick einen Body immer als JSON mit Content-Type: application/json. Antworten können weitere Felder enthalten, die hier fehlen; ignorier einfach, was du nicht brauchst.

API-Schlüssel erstellst du im Reiter «Agenten» deines Dashboards, unter «Erweitert». Ein Schlüssel handelt für dein Konto: Die Sessions, die er startet, gehören dir, zählen zu deinen Limits und stehen in deiner Session-Liste.

API-Schlüssel erstellen

Authentifizierung

Schick den Schlüssel bei jeder Anfrage mit:

Authorization: Bearer YOUR_API_KEY

Schlüssel beginnen mit brl_k_ (früher erstellte mit brl-k-v7-). Die API liest sie nur aus diesem Header, nie aus der URL. GET /image ist die einzige Route auf dieser Seite, die ohne Schlüssel funktioniert. Ein Schlüssel gilt, bis du ihn widerrufst, oder bis zu dem festen Datum, das du beim Erstellen gewählt hast.

Antworten und Fehler

Jede Route antwortet mit HTTP 200 und einem JSON-Body. Ob es geklappt hat, steht im Feld status. Prüf also dieses Feld und nicht den HTTP-Code:

Werte jeden anderen Status als ok als Fehler. message nennt den Grund in einem Satz, den du einer Person zeigen kannst. Die Sprache folgt dem Header Accept-Language und ist ohne ihn Englisch. Werte den Text deshalb nicht aus, sondern verzweige nach status und, falls vorhanden, nach code oder reason.

{
  "status": "denied",
  "message": "This browser session could not be found. Check the session ID and try again."
}

Fehlt der Schlüssel oder ist er ungültig, widerrufen oder abgelaufen, lautet die Antwort denied mit loggedIn: false. Ist deine E-Mail-Adresse noch nicht bestätigt, kommt denied mit verified: false. Einzige Ausnahme von HTTP 200 sind Datei-Downloads, siehe Datei herunterladen.

Endpunkte

Sessions

Eine Session ist ein Cloud-Browser. Dein Code steuert ihn über CDP, und eine Person kann in der Live-Ansicht zuschauen oder übernehmen. Diese Routen erreichen nur Sessions deines eigenen Kontos, nie die deiner Kolleginnen und Kollegen.

Session starten

POST https://api.guard.ch/v7/web/sessions

Startet einen Browser und antwortet sofort, während er im Hintergrund weiter hochfährt: status ist erst starting, dann running. Verbinde Playwright über connectOverCDP oder Puppeteer über browserWSEndpoint mit der connectUrl. Wird die Verbindung anfangs abgelehnt, warte, bis GET /web/sessions/:id running meldet.

Alle Felder im Body sind optional:

Zum Beispiel:

curl -X POST https://api.guard.ch/v7/web/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "triage-4821",
    "url": "https://example.com",
    "extensions": [
      { "id": "network.location", "settings": { "country": "DE" } },
      { "id": "security.reputation" }
    ],
    "screen": { "width": 1440, "height": 900 },
    "idempotencyKey": "ticket-4821"
  }'

{
  "status": "ok",
  "id": "brl-v-v7-q8m2r7k4d1",
  "name": "triage-4821",
  "image": "chrome",
  "connectUrl": "wss://api.guard.ch/web/brl-v-v7-q8m2r7k4d1/cdp?token=3f9c2a7d",
  "liveViewUrl": "https://guard.ch/en/viewer?id=brl-v-v7-q8m2r7k4d1",
  "createdAt": "2026-09-26T08:14:03.512Z",
  "screen": { "width": 1440, "height": 900 },
  "analysisEnabled": true,
  "location_applied": true,
  "quota": {
    "running_session_limit": 3,
    "running_sessions_used": 1,
    "running_sessions_remaining": 2
  }
}

Eine erfolgreiche Antwort enthält:

Ein abgelehnter Start enthält zusätzlich einen maschinenlesbaren code:

Sessions auflisten

GET https://api.guard.ch/v7/web/sessions

Gibt deine Sessions in data zurück, die neuste zuerst. Aufgelistet werden nur Sessions, die über die API oder MCP gestartet wurden. Sessions, die du in Guard.ch von Hand startest, fehlen hier; mit GET /web/sessions/:id findest du sie trotzdem über ihre ID.

curl "https://api.guard.ch/v7/web/sessions?status=all&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "status": "ok",
  "data": [
    {
      "id": "brl-v-v7-q8m2r7k4d1",
      "name": "triage-4821",
      "image": "chrome",
      "status": "running",
      "createdAt": "2026-09-26T08:14:03.512Z",
      "endedAt": null,
      "endedReason": null,
      "startRefusal": null,
      "expiresAt": "2026-09-27T02:14:03.512Z",
      "lastseen": "2026-09-26T08:31:40.087Z",
      "url": "https://example.com",
      "country": "de",
      "location_applied": true,
      "connectUrl": "wss://api.guard.ch/web/brl-v-v7-q8m2r7k4d1/cdp?token=3f9c2a7d",
      "liveViewUrl": "https://guard.ch/en/viewer?id=brl-v-v7-q8m2r7k4d1",
      "startedByKind": "agent",
      "analysisEnabled": false,
      "startedBy": { "id": 4821, "email": "ana@example.com", "firstname": "Ana", "lastname": "Meier" }
    }
  ]
}

Jede Session hat diese Felder:

Session abrufen

GET https://api.guard.ch/v7/web/sessions/:id

Gibt eine Session in data zurück, mit denselben Feldern wie die Liste. So findest du auch Sessions, die du in Guard.ch von Hand gestartet hast, und ein Skript kann sich über ihre connectUrl damit verbinden. Eine unbekannte ID oder die Session einer anderen Person ergibt denied.

Session beenden

DELETE https://api.guard.ch/v7/web/sessions/:id

Beendet die Session sofort und entfernt ihren Browser; sie zählt dann nicht mehr zu deinen gleichzeitigen Sessions. Die Antwort ist ok, auch wenn die Session schon beendet war. endedReason wird zu stopped, ausser die Session endete vorher aus einem anderen Grund. Das beendet auch Sessions, die du von Hand gestartet hast; beende also nur, was dein Skript gestartet hat.

curl -X DELETE https://api.guard.ch/v7/web/sessions/brl-v-v7-q8m2r7k4d1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Datei herunterladen

GET https://api.guard.ch/v7/web/sessions/:id/downloads/:downloadId

Gibt die Bytes einer Datei zurück, die der Browser während der Session heruntergeladen hat, mit Inhaltstyp und Dateiname. Das MCP-Tool browser_downloads liefert diese URL mit einem signierten Parameter token. Der Link selbst ist die Berechtigung: Er öffnet genau diese Datei 15 Minuten lang ohne Authorization-Header, du kannst ihn also im Browser öffnen oder weitergeben. Für einen neuen Link listest du die Downloads nochmals auf.

Anders als alle anderen Routen antwortet diese mit echten HTTP-Statuscodes: 200 mit der Datei, 403 mit Status denied, wenn der Link abgelaufen oder ungültig ist, oder 404 mit Status denied, wenn die Datei nicht verfügbar ist. Die Datei wird mit den Cookies der Seite nochmals angefordert; ein einmaliger oder abgelaufener Download-Link ergibt deshalb 404.

Apps

Alles Optionale an einer Session ist eine App aus dem App Store: ihr Ausgang, die Anonyme Mail, Dateien, die Agent-Steuerung und die Sicherheits-Apps. Eine Session startet mit denen, die du in extensions nennst, oder mit deinen immer aktiven, und du kannst sie schalten, solange sie läuft. Dein Workspace kann eine App sperren oder erzwingen; die API hält sich daran und nennt die App, an der es scheitert.

Die Apps und ihre Einstellungen:

Apps auflisten

GET https://api.guard.ch/v7/extensions

Mit image (einer Image-ID) siehst du, was eine neue Session auf diesem Browser nutzen könnte; mit vm (einer Session-ID) den aktuellen Stand dieser Session. Schick genau einen der beiden Parameter.

curl "https://api.guard.ch/v7/extensions?image=chrome" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "status": "ok",
  "extensions": [
    { "id": "network.location", "state": "available", "alwaysOn": true },
    { "id": "mail", "state": "available", "alwaysOn": false },
    { "id": "security.ai", "state": "locked", "reason": "policy", "alwaysOn": false }
  ],
  "packs": [
    {
      "id": "pack.security",
      "extensions": ["security.reputation", "security.domain", "security.privacy", "security.page", "security.ai"]
    }
  ],
  "alwaysOn": ["network.location"]
}

Apps einschalten

POST https://api.guard.ch/v7/vm/:vmId/extensions

Schaltet Apps in einer laufenden Session ein oder ändert die Einstellungen von bereits aktiven. Die Session behält ihre Tabs und ihren Zustand, und eine Netzwerk-App ersetzt die aktive. Die Antwort kommt, sobald die Änderung greift. Der Body ist extensions, eine oder mehrere { id, settings? } aus der Liste oben.

curl -X POST https://api.guard.ch/v7/vm/brl-v-v7-q8m2r7k4d1/extensions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "extensions": [{ "id": "mail" }, { "id": "network.residential", "settings": { "country": "DE" } }] }'

Eine abgelehnte Änderung nennt die extension und einen reason:

Ein neuer Ausgang kann auch aus eigenem Grund scheitern, etwa residential_limit_reached, invalid_proxy oder egress_not_found.

Einstellungen einer App ändern

PATCH https://api.guard.ch/v7/vm/:vmId/extensions/:id

Ändert die Einstellungen einer aktiven App, etwa die Stadt des Serverstandorts. Schick die neuen settings als Body; ist die App aus, lautet die Antwort reason: inactive. Die Antwort ist dieselbe wie beim Einschalten.

curl -X PATCH https://api.guard.ch/v7/vm/brl-v-v7-q8m2r7k4d1/extensions/network.location \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "settings": { "country": "US", "location": "us-dal" } }'

Eine App ausschalten

DELETE https://api.guard.ch/v7/vm/:vmId/extensions/:id

Schaltet eine App aus, oder mit pack.security alle Sicherheits-Apps auf einmal. Schaltest du die Netzwerk-App aus, geht die Session über den eigenen Anschluss des Rechenzentrums; eine App, die dein Workspace erzwingt, bleibt an (reason: enforced).

curl -X DELETE https://api.guard.ch/v7/vm/brl-v-v7-q8m2r7k4d1/extensions/pack.security \
  -H "Authorization: Bearer YOUR_API_KEY"

Nutzung und Kontingent

API-Nutzung

GET https://api.guard.ch/v7/web/usage

Summen über die Sessions, die dein Konto über die API oder MCP gestartet hat:

Limits des Plans

GET https://api.guard.ch/v7/user/quota

Die Zähler, die dein Plan durchsetzt, über alle Sessions deines Workspace, egal ob von Hand oder über die API gestartet:

Images und Standorte

GET https://api.guard.ch/v7/image

Der Katalog hinter image, den Standortcodes und den Residential-Ausgängen. Dafür brauchst du keinen Schlüssel.

curl https://api.guard.ch/v7/image

Limits

• 3 Sessions gleichzeitig pro Platz. Sessions, die du von Hand startest, zählen mit. Das ganze Team teilt sich diese Sessions, und Workspace-Manager können einzelnen Mitgliedern ein Limit setzen. Sind alle belegt, wird eine neue Session abgelehnt und nicht eingereiht.
• Sessions enden von selbst. Eine Session endet wenige Minuten, nachdem sich der letzte Client getrennt hat, spätestens aber bei expiresAt: 18 Stunden nach dem Start. Beende Sessions, die du nicht mehr brauchst, damit sie sofort nicht mehr zu deinem Limit zählen.
• Das Starten von Sessions ist begrenzt. Pro Minute, Stunde und Tag gelten Limits, je API-Schlüssel und je Konto. Eine Ablehnung enthält code: rate_limited und retryAfterMs.
• Auch Anfragen sind begrenzt. Der API-Host nimmt von einer IP-Adresse etwa zwei Anfragen pro Sekunde an, kurze Spitzen darüber sind möglich. Wird das überschritten, lautet die Antwort denied; warte kurz und versuch es nochmals.
• Aufrufe kosten nichts extra. Weder Anfragen noch Sessions werden nach Menge abgerechnet. Residential-Verkehr zählt zum Kontingent deines Plans im Abrechnungszeitraum.

Sicherheit

• Ein API-Schlüssel hat auf diesen Routen dieselben Rechte wie dein Konto. Bewahr ihn in einem Secret Store auf und widerruf ihn im Reiter «Agenten», falls er je nach aussen gelangt.
• Schick Schlüssel nur im Authorization-Header, nie in URLs, wo sie in Logs und im Browserverlauf landen.
• Jede connectUrl hat einen eigenen Token und funktioniert nicht mehr, sobald die Session endet. Schreib sie nicht in Logs und gib sie nicht weiter.
• Zielseiten laden in unserer Infrastruktur, nie auf dem Rechner, der die API aufruft.

Fragen zur API?

Unklarheiten bei einer Route, oder fehlt dir etwas für deine Integration? Schreib uns.