This page lists what the API accepts and returns. For a walkthrough from API 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/v7

Authentication

An API key in the Authorization header

Format

JSON over HTTPS

Access

Enterprise

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 API keys on the Agents tab of your dashboard, under Advanced. A key acts for your account: the sessions it starts are yours, count towards your limits and appear in your session list.

Create an API key

Authentication

Send the key with every request:

Authorization: Bearer YOUR_API_KEY

Keys start with brl_k_ (keys created earlier with brl-k-v7-). The API reads them only from this header, never from the URL. GET /image is the only route on this page that works without a key. A key works until you revoke it, or until the fixed date chosen when it was created.

Responses and errors

Every route 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 or reason.

{
  "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 cloud browser. Your code drives it over CDP, and a person can watch or take over in the live view. These routes only reach sessions of your own account, never a colleague's.

Start a session

POST https://api.guard.ch/v7/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/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
  }
}

A successful response contains:

A refused start also carries a machine-readable code:

List sessions

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

Returns your sessions in data, newest first. Only sessions started through the API or MCP are listed. Sessions 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/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" }
    }
  ]
}

Each session has these fields:

Read a session

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

Returns one session in data, with the same fields as the list. It also finds a session 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/v7/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 sessions you started by hand, so only stop what your script started.

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

Download a file

GET https://api.guard.ch/v7/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 MCP tool browser_downloads hands out this URL with a signed token parameter. The link itself is the credential: it opens this one file for 15 minutes without an Authorization header, so you can open it in a browser or pass it on. List the downloads again for a fresh link.

Unlike every other route, this one answers with real HTTP status codes: 200 with the file, 403 with status denied if the link has expired or isn't valid, 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.

Apps

Everything optional in a session is an app from the App Store: its exit, anonymous mail, files, agent control and the security apps. A session starts with the ones you name in extensions, or with your always-activate set, and you can switch them while it runs. Your workspace can lock an app or enforce it; the API follows those rules and names the one that refused.

The apps and their settings:

List apps

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

With image (a browser image ID) the answer is what a new session on that browser could use; with vm (a session ID) it is that session's current state. Send exactly one of the two.

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

Switch apps on

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

Switches apps on in a running session, or changes the settings of ones already on. The session keeps its tabs and state, and a network app replaces the active one. The answer comes once the change is applied. The body is extensions, one or more { id, settings? } from the list above.

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

A refused change names the extension and a reason:

A new exit can also be refused for its own reason, such as residential_limit_reached, invalid_proxy or egress_not_found.

Change an app's settings

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

Changes the settings of an active app, for example the city of the server location. Send the new settings as the body; an app that is off answers reason: inactive. The answer is the same as for switching on.

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

Switch an app off

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

Switches one app off, or every security app at once with pack.security. Switching the network app off moves the session to the data centre's own connection; an app your workspace enforces stays on (reason: enforced).

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

Usage and quota

API usage

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

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

Plan limits

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

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

Images and locations

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

The catalogue behind image, the location codes and the residential exits. It needs no key.

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

Limits

• 3 sessions at once per seat. Sessions you start by hand count too. The whole team shares them, and a workspace manager can limit individual members. When every slot is taken, a new session is refused, not queued.
• Sessions end on their own. A session ends a few 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 API 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 towards your plan's allowance for the billing cycle.

Security

• An API key has the same rights as your account on these routes. Keep it in a secret store and revoke it on the Agents tab 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 a route, or missing something for your integration? Get in touch.