Integrating Guard.ch into your own tools

Two ways to integrate

• The API. Create a session over REST, drive it with Playwright, Puppeteer or any CDP client, and stop it when you are done. Use an app key to authenticate. Every session has a live-view URL. Go to API setup
• The launcher link. Build a guard.ch/start link with the target address and have someone open it. The investigation runs in their signed-in Guard.ch account. The browser extensions use this route too. Go to launcher link

Find every endpoint and field in the API reference. For AI assistants, see the separate MCP guide.

What you need for the API

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 includes it

The API uses HTTP and JSON, and the browser uses CDP. You do not need another SDK.

App keys

Create and manage app keys under Apps in your Guard.ch dashboard.

• Up to twenty per account. A separate key for each pipeline, host or tool makes revocation precise. You can stop one integration without interrupting the others.
• Expiry is a choice. Choose no expiry, 30 days, 90 days or one year when creating a key. Pick an expiry that fits your key rotation schedule.
• Shown once. The key is shown only when you create it. If you lose it, revoke it and create a new one.
• 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.

Create an app key

Creating a session

One POST starts an isolated browser and returns the details you need to control and watch it:

curl -X POST https://api.beta.browser.lol/v8/web/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"triage-4821","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. Reuse it with the same credentials to get the successful response again instead of opening a second browser. This helps with queues and retried jobs.

The response includes the session ID, connectUrl for CDP, liveViewUrl for the live view, the screen size and your remaining session capacity.

Driving the browser

In the examples below, session is the JSON response to the POST request. Use its connectUrl to attach your CDP client:

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.

Manage sessions and 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 sessions you no longer need. Each running session occupies a slot; after the last connection closes, it remains occupied for a few minutes until the session ends automatically.

Live view and takeover

Every session includes a live view. Open it while your code runs to follow the page in real time. You can take over the mouse and keyboard for a sign-in, a captcha or another decision, then resume the automation.

If the browser image supports analysis, you can turn it on in the live view. It shows findings during the session; the view is no longer available once the session ends.

The launcher link

The launcher is at guard.ch/start. When someone opens a link with a target address, they sign in if needed and reach the investigation’s live view. Your tool needs no Guard.ch credentials or token.

https://guard.ch/en/start?url=https%3A%2F%2Fexample.com

The link accepts three query parameters; only url is required:

• url The URL-encoded target address. Links from our browser extensions can also use ENCODED- followed by the address as uppercase hex bytes.
• location The exit location, as a country (us) or a city (us-dal). If you omit it, Guard.ch chooses the location.
• 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.

Open the launcher

Deploying to a fleet

For interactive launches across many devices, deploy the browser extensions centrally. They add a right-click menu, toolbar popup and keyboard shortcut to the launcher link. Managed installations read the workspace sign-in slug from browser policy and route staff through your single sign-on.

The same slug can go in launcher links built by your own tools, so people use the same workspace sign-in with both routes. The integrations page lists everything prebuilt.

Limits

• Up to three sessions per person. When all three slots are in use, Guard.ch rejects new sessions instead of queueing them.
• 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, hourly and daily limits protect the platform from excessive session creation. Check the response status and delay further attempts if you reach a limit.
• The launcher link carries no entitlement. The person who opens the link signs in with their own Guard.ch account. Sharing the link does not share your access.

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 target page loads in our infrastructure, never on the device 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.

Need help?

If you need help with either approach, get in touch.