Guard.ch API reference

This page lists what the API accepts and returns. For a walkthrough from app key to a running Playwright script, see the custom integration guide. To connect an AI assistant, use MCP instead.

Basics

Base URL

https://api.guard.ch/v8

Authentication

An app key in the Authorization header

Format

JSON over HTTPS

Access

Guard Analyst or Guard Team, also during the trial

Paths in this reference are relative to the base URL. Send request bodies as JSON with Content-Type: application/json. Responses can contain fields not listed here; ignore any you don't use.

Create app keys under Apps in your dashboard. A key acts for your account: the sessions it starts are yours, count toward your limits and appear in your session list.

Create an app key

Authentication

Send the key with every request:

Authorization: Bearer YOUR_API_KEY

Keys start with brl-k-v7-. The API reads them only from this header, never from the URL. GET /image is the only endpoint on this page that works without a key. A key expires after one year without use, or on the fixed date chosen when it was created, whichever comes first.

Responses and errors

Every endpoint answers with HTTP 200 and a JSON body. The body's status field tells you the outcome, so check it instead of the HTTP code:

Treat any status other than ok as a failure. message gives the reason in a sentence you can show to a person. Its language follows the Accept-Language header and defaults to English, so don't parse it: branch on status and, where present, code.

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

If the key is missing, invalid, revoked or expired, the answer is denied with loggedIn: false. If your email address isn't confirmed yet, it's denied with verified: false. File downloads are the only exception to HTTP 200, see Download a file.

Endpoints

Sessions

A session is one isolated browser. Your code drives it over CDP, and a person can watch or take over in the live view. These endpoints only reach sessions of your own account, never a colleague's.

Start a session

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

Starts a browser and answers immediately while the browser keeps starting in the background: its status is starting, then running. Connect Playwright's connectOverCDP or Puppeteer's browserWSEndpoint to connectUrl. If the connection is refused at first, wait until GET /web/sessions/:id reports running.

All body fields are optional:

For example:

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

A successful response contains:

A refused start also carries a machine-readable code:

List sessions

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

Returns your sessions in data, newest first. Only sessions started through the API or MCP are listed. Investigations you start by hand in Guard.ch are left out, but GET /web/sessions/:id still finds them by 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" }
    }
  ]
}

Each session has these fields:

Read a session

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

Returns one session in data, with the same fields as the list. It also finds an investigation you started by hand in Guard.ch, so a script can attach to it through its connectUrl. An unknown ID or another person's session answers denied.

Stop a session

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

Ends the session, removes its browser and frees the slot immediately. The answer is ok even if the session had already ended. endedReason becomes stopped unless the session ended earlier for another reason. This also ends investigations you started by hand, so only stop what your script started.

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

Download a file

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

Returns the bytes of a file the browser downloaded during the session, with its content type and file name. The download ID (d1, d2, ...) comes from the MCP tool browser_downloads, which hands out this URL.

Unlike every other endpoint, this one answers with real HTTP status codes: 200 with the file, or 404 with status denied if the file isn't available. The file is requested again from the page with its cookies, so a one-time or expired download link answers 404.

Usage and quota

API usage

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

Totals for the sessions your account started through the API or MCP:

Plan limits

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

The meters your plan enforces, across every session of your account, whether started by hand or through the API:

Images and locations

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

The catalog behind the image, country and egress fields. It needs no key.

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

Limits

• Three concurrent sessions per person. That is the limit on Guard Analyst and Guard Team, and sessions you start by hand count too. When every slot is taken, a new session is refused, not queued.
• Sessions end on their own. A session ends about five minutes after the last client disconnects, and at expiresAt at the latest: 18 hours after it started. Stop sessions you no longer need to free their slot right away.
• Starting sessions is rate-limited. Limits per minute, hour and day apply to each app key and each account. A refusal carries code: rate_limited and retryAfterMs.
• Requests are rate-limited too. The API host accepts about two requests per second from one IP address, with short bursts above that. Beyond it, the answer is denied; wait a moment and try again.
• Calls aren't billed. Neither requests nor sessions are charged by volume. Residential traffic counts toward your plan's allowance for the billing cycle.

Security

• An app key has the same rights as your account on these endpoints. Keep it in a secret store and revoke it under Apps if it ever leaks.
• Send keys only in the Authorization header, never in URLs, where they end up in logs and browser history.
• Every connectUrl carries its own token and stops working when the session ends. Don't log or share it.
• Target pages load in our infrastructure, never on the machine that calls the API.

Need help?

Questions about an endpoint, or missing something for your integration? Get in touch.