API-Referenz von Guard.ch

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

Grundlagen

Basis-URL

https://api.guard.ch/v8

Authentifizierung

Ein App-Schlüssel im Authorization-Header

Format

JSON über HTTPS

Zugang

Guard Analyst oder Guard Team, auch in der Testphase

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; ignoriere einfach, was du nicht brauchst.

App-Schlüssel erstellst du unter Apps im Dashboard. Ein Schlüssel handelt für dein Konto: Die Sitzungen, die er startet, gehören dir, zählen gegen deine Limits und stehen in deiner Sitzungsliste.

App-Schlüssel erstellen

Authentifizierung

Schick den Schlüssel bei jeder Anfrage mit:

Authorization: Bearer YOUR_API_KEY

Schlüssel beginnen mit brl-k-v7-. Die API liest sie nur aus diesem Header, nie aus der URL. GET /image ist der einzige Endpunkt auf dieser Seite, der ohne Schlüssel funktioniert. Ein Schlüssel läuft nach einem Jahr ohne Nutzung ab oder an dem festen Datum, das du beim Erstellen gewählt hast, je nachdem, was früher eintritt.

Antworten und Fehler

Jeder Endpunkt 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.

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

Sitzungen

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

Sitzung starten

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

Startet einen Browser und antwortet sofort, während der Browser im Hintergrund weiter hochfährt: status ist erst starting, dann running. Verbinde Playwright mit connectOverCDP oder Puppeteer mit browserWSEndpoint auf die 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/v8/web/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "triage-4821",
    "url": "https://example.com",
    "country": "de",
    "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 },
  "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:

Sitzungen auflisten

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

Gibt deine Sitzungen in data zurück, die neuste zuerst. Aufgelistet werden nur Sitzungen, die über die API oder MCP gestartet wurden. Untersuchungen, 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/v8/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,
      "expiresAt": "2026-09-27T02:14:03.512Z",
      "lastseen": "2026-09-26T08:31:40.087Z",
      "url": "https://example.com",
      "country": "de",
      "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": "[email protected]", "firstname": "Ana", "lastname": "Meier" }
    }
  ]
}

Jede Sitzung hat diese Felder:

Sitzung abrufen

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

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

Sitzung beenden

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

Beendet die Sitzung, entfernt ihren Browser und gibt den Platz sofort frei. Die Antwort ist ok, auch wenn die Sitzung schon beendet war. endedReason wird zu stopped, ausser die Sitzung endete vorher aus einem anderen Grund. Das beendet auch Untersuchungen, die du von Hand gestartet hast; beende also nur, was dein Skript gestartet hat.

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

Datei herunterladen

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

Gibt die Bytes einer Datei zurück, die der Browser während der Sitzung heruntergeladen hat, mit Inhaltstyp und Dateiname. Die Download-ID (d1, d2, ...) liefert das MCP-Tool browser_downloads zusammen mit dieser URL.

Anders als alle anderen Endpunkte antwortet dieser mit echten HTTP-Statuscodes: 200 mit der Datei oder 404 mit Status denied, wenn die Datei nicht verfügbar ist. Die Datei wird mit den Cookies der Seite noch einmal angefordert; ein einmaliger oder abgelaufener Download-Link ergibt deshalb 404.

Nutzung und Kontingent

API-Nutzung

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

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

Limits des Plans

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

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

Images und Standorte

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

Der Katalog hinter den Feldern image, country und egress. Dafür brauchst du keinen Schlüssel.

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

Limits

• Drei gleichzeitige Sitzungen pro Person. Das gilt für Guard Analyst und Guard Team, und Sitzungen, die du von Hand startest, zählen mit. Sind alle Plätze belegt, wird eine neue Sitzung abgelehnt und nicht eingereiht.
• Sitzungen enden von selbst. Eine Sitzung endet etwa fünf Minuten, nachdem sich der letzte Client getrennt hat, spätestens aber bei expiresAt: 18 Stunden nach dem Start. Beende Sitzungen, die du nicht mehr brauchst, dann ist ihr Platz sofort wieder frei.
• Das Starten ist begrenzt. Pro Minute, Stunde und Tag gelten Limits, je App-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. Darüber hinaus lautet die Antwort denied; warte kurz und versuch es noch einmal.
• Aufrufe kosten nichts extra. Weder Anfragen noch Sitzungen werden nach Menge abgerechnet. Residential-Verkehr zählt gegen das Kontingent deines Plans im Abrechnungszyklus.

Sicherheit

• Ein App-Schlüssel hat auf diesen Endpunkten dieselben Rechte wie dein Konto. Bewahr ihn in einem Secret Store auf und widerrufe ihn unter Apps, 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 ein eigenes Token und funktioniert nicht mehr, sobald die Sitzung endet. Logge oder teile sie nicht.
• Zielseiten laden in unserer Infrastruktur, nie auf dem Rechner, der die API aufruft.

Fragen zur API?

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