Integrating Guard.ch into your own tools

Every path uses the same isolated browser platform. A session your code creates also has a live view for a person; on an analysis-capable image, that person can switch live analysis on from the viewer when it is needed.

Which one you want depends on who acts on the result. If a person reads it, hand them a launcher link. If your code reads it, take the API; the API reference documents every endpoint and field. If an AI assistant is doing the work, connect it over MCP instead.

Three paths

• The API. Create a session over REST, drive it with Playwright, Puppeteer or any CDP client, and stop it when you are done. Authentication is an app key. Every session has a live-view URL.
• The launcher link. Build a guard.ch/start link carrying the address and let a person open it. The investigation runs in their own signed-in Guard.ch. The browser extensions use exactly this mechanism.
• MCP. An AI assistant connects to the hosted MCP endpoint and drives the same browsers with its own tool calls, without you writing a client at all. That path has its own guide; this one covers the other two.

Before you start

API base

https://api.guard.ch/v8

Authentication

An app key in an Authorization: Bearer header

Plan

A paid plan with programmatic access; the 30-day trial carries it

Concurrency

Up to three running sessions per person; creation is refused, not queued

Launcher link

guard.ch/start, opened like any URL: no key, no SDK

Session history

The session list keeps 30 days of entries; the pages themselves are never stored

There is no SDK to adopt. The API is plain HTTP and JSON, and the browser side is standard CDP, so the clients you already use work unchanged.

App keys

Create and manage keys in the browser.lol dashboard using your shared account.

• Up to twenty per account. One per pipeline, host or tool keeps revocation surgical: pulling a key stops that integration and nothing else.
• Expiry is a choice. Never, 30 days, 90 days or one year, set at creation. Anything running unattended is safer with a date on it.
• Shown once. The key is displayed a single time, at creation. A lost key is replaced, not recovered: revoke it and mint another.
• Sent as a header. The API reads it from Authorization: Bearer. Keep it out of query strings, where a key leaks into browser history, proxy logs and analytics.

Creating a session

One POST starts an isolated browser and returns everything needed to drive it and to watch it:

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","timeout":900,"country":"us","screen":{"width":1440,"height":900},"idempotencyKey":"ticket-4821"}'

• country Exit location as a country or city code (us, de, us-dal). Omit it to use the assigned edge node's normal datacenter egress.
• egress Set to residential to leave through hosted residential egress instead of a datacenter exit, on plans that include it. Combines with country and is metered against the workspace's allowance for the cycle.
• proxy Your own proxy URL, for egress you control yourself. Mutually exclusive with country and with residential egress.
• screen Viewport as width and height.
• url An http or https address to open immediately.
• name Display name for the dashboard's session list. One is generated when you omit it.
• idempotencyKey Retry key. Reusing it with the same credential replays the successful create instead of opening a second browser, which is what you want behind a queue or a retrying job.

The response carries the session id, connectUrl (the CDP websocket), liveViewUrl (the human view), the resolved screen, and the concurrency you have left.

Driving the browser

connectUrl is an ordinary CDP websocket carrying its own per-session token, so the standard clients attach to it directly:

const browser = await chromium.connectOverCDP(session.connectUrl);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example-shop.test/login");

const browser = await puppeteer.connect({
  browserWSEndpoint: session.connectUrl,
});

From there it is your usual automation: navigation, selectors, evaluation, downloads and tracing. A colleague can open the live view while your code drives the browser. On an analysis-capable image, they can switch live analysis on in that viewer.

Listing, stopping, usage

• GET /web/sessions lists running sessions; status=all adds the ended ones from the last 30 days, limit caps the page
• GET /web/sessions/:id returns one session, including its connectUrl while it is running
• DELETE /web/sessions/:id stops a session and frees its slot for the workspace
• GET /web/usage returns current concurrency, the plan's session limit and the totals for the last 30 days

Stop what you no longer need. A seat has one slot, and an abandoned session holds it for 4 hours after its last connection before it ends on its own.

Live view and takeover

Every session also returns a live-view URL. Open it while your code runs to watch the page in real time; take the mouse and keyboard to get past a login, a captcha or a decision you would rather make yourself, then let the automation continue.

A person can step in at any point without restarting the work. On an analysis-capable image they can also start live analysis from the viewer. The analysis is live only: nothing is recorded, and what the lane showed is gone once the session ends.

The launcher link

The launcher lives at guard.ch/start. Opening it with a target hands over to the person's own browser: they sign in if needed, and the investigation starts and lands on the live view. Your tool holds no account, no token and no Guard.ch state; the link is the entire integration.

Three query parameters, and only the first is required:

• url The target. Our extensions wrap it in a small hex scheme: the prefix ENCODED- followed by the address as uppercase hex bytes, so the suspect URL travels as an opaque token instead of a nested link. A plain URL-encoded value works as well.
• location The exit location, as a country (us) or a city (us-dal). Omitted, Guard.ch chooses.
• workspace Your workspace's SSO slug. With it, a visitor who is not signed in is routed through your own single sign-on instead of the generic form. It is a routing hint, never a credential: a wrong value falls back to the normal sign-in.

A link without a language prefix redirects to the English launcher with the query preserved; build guard.ch/de/start for a German-speaking team.

Deploying to a fleet

To give every employee the interactive path without building anything, deploy the browser extensions: they are the launcher link with a right-click menu, toolbar popup and keyboard shortcut on top, and IT can push them company-wide. Managed installs read the workspace slug from browser enterprise policy, so every install routes staff through your single sign-on by itself.

The same slug goes into the launcher links your own tools build, so a custom integration and the managed extensions sign people in identically. The integrations page lists everything prebuilt.

Limits

• Concurrency is the unit: up to three per person. Up to three sessions running at once for each person on the plan, refused rather than queued while all three are busy. Parallel automation scales by running up to three browsers side by side, not by paying per call.
• Calls are not metered. Neither requests nor sessions are billed by volume. Residential egress is the exception, metered against the workspace's allowance for the billing cycle.
• Creation is rate-limited. Per-minute, per-hour and per-day creation limits protect the platform. Ordinary automation never meets them; a runaway loop does.
• The launcher link carries no entitlement. It grants nothing by itself: whatever runs, runs on the account of the person who opens it, and a forwarded link simply meets their sign-in.

Security

• App keys belong in the Authorization header. Keep them out of URLs, where they would land in browser history, proxy logs and analytics.
• Each session's CDP endpoint carries its own token and dies with the session.
• A launcher link contains no credentials and grants nothing; sign-in happens on guard.ch, or through your own SSO.
• The suspect page loads in our infrastructure, never on the machine that called the API.
• Everything runs over TLS, and account and session metadata stay in the EU under the same DPA as the rest of the product.

Next steps

Mint a key under Apps, create a session, attach your CDP client. For anything this surface does not cover, contact us.