Integrating Guard.ch into your own tools
Connect your code to a Guard.ch cloud browser over REST and CDP, or hand a URL to a person with a launcher link.
Two ways to integrate
- The API. Start a session over REST with the apps it needs, drive it with Playwright, Puppeteer or any CDP client, and stop it when you are done. You authenticate with an API key. Every session has a live view. Go to API setup
- The launcher link. Build a link to the Guard.ch launcher with the target address and have someone open it. The session runs in their own signed-in Guard.ch account. The browser add-ons use this route too. Go to launcher link
Every route and field is in the API reference. For AI assistants, see the MCP guide.
What you need for the API
- API base
- https://api.guard.ch/v7
- Authentication
- An API key in an Authorization: Bearer header
- Plan
- Enterprise, which includes API access
The API speaks HTTP and JSON, the browser speaks CDP. You need no other SDK.
API keys
Create and manage API keys on the Agents tab of your dashboard, under Advanced.
- Up to twenty per account. A separate key for each pipeline, host or tool makes revoking precise: you stop one integration without interrupting the others.
- Unused keys expire. A key works until you revoke it. When you create it, you can also set a fixed expiry of 30 days, 90 days or one year to match your 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.
Creating a session
One POST starts a cloud browser and returns what you need to drive and watch it:
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",
"extensions": [
{ "id": "network.location", "settings": { "country": "US" } },
{ "id": "mail" }
],
"screen": { "width": 1440, "height": 900 },
"idempotencyKey": "ticket-4821"
}'extensionsThe apps the session starts with, as a list of entries with an id and optional settings, for example Location Switch, Anonymous Mail or the security apps. Leave the field out and the session starts with the apps you set to always activate. Your workspace's enforced apps come on either way.countryExit location as a country or city code (us, de, us-dal). The older way of naming the Location Switch app; it still works.egressSet to residential to leave through a residential connection, on plans that include it. Combines with country and counts towards the workspace's allowance for the cycle. Stands for the Home IP app.proxyYour own proxy URL, for an exit you control. Stands for the Proxy Connect app and cannot be combined with country or residential.screenViewport as width and height.urlAn http or https address to open straight away.nameDisplay name in the session list. One is generated when you leave it out.idempotencyKeyRetry key. Send it again with the same credentials and you get the successful response back instead of a second session. Useful for queues and retried jobs.
The response holds the session ID, connectUrl for CDP, liveViewUrl for the live view, the screen size and your free session slots.
Driving the browser
In the examples below, session is the JSON response to the POST. Attach your CDP client to its connectUrl:
Playwright
const browser = await chromium.connectOverCDP(session.connectUrl);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example-shop.test/login");Puppeteer
const browser = await puppeteer.connect({
browserWSEndpoint: session.connectUrl,
});From there it is your usual automation: navigation, selectors, evaluation, downloads and tracing. You can open the live view while your code drives the browser, and switch apps there, the security apps included.
Manage sessions and usage
GET /web/sessionslists running sessions; status=all adds the ended ones of the last 30 days, limit caps the pageGET /web/sessions/:idreturns one session, with its connectUrl while it runsPOST /vm/:vmId/extensionsswitches apps on in a running session; PATCH and DELETE on /vm/:vmId/extensions/:id change or end oneDELETE /web/sessions/:idstops a session and frees its slotGET /web/usagereturns your sessions running now, the plan's limit and the totals of the last 30 days
Stop sessions you no longer need. Each running session holds a slot; after the last connection closes, it keeps the slot for a few minutes until it ends on its own.
Live view and takeover
Every session has a live view. Open it while your code runs to follow the page in real time. Take over mouse and keyboard for a sign-in, a captcha or another decision, then let the automation carry on.
With the security apps on, the live view shows what the page is and does while the session runs. The findings are live only: nothing is kept once the session ends.
The launcher link
The launcher is at guard.ch/start. Whoever opens a link with a target address signs in if needed and lands in the live view of a new session. Your tool needs no Guard.ch credentials or token.
https://guard.ch/en/start?url=https%3A%2F%2Fexample.comThe link takes three query parameters; only url is required:
urlThe URL-encoded target address. Links from our browser add-ons can also use ENCODED- followed by the address as uppercase hex bytes.locationThe exit location, as a country (us) or a city (us-dal). Without it, the session starts on the person's usual exit.workspaceYour workspace's sign-in name. With it, a visitor who is not signed in goes through your own single sign-on instead of the general 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 and keeps the query; build guard.ch/de/start for a German-speaking team.
Rolling out to many devices
For launches on many devices, roll out the browser add-on centrally. It adds a right-click menu, a toolbar field and a keyboard shortcut that open the launcher link. Managed installs read the workspace sign-in name from browser policy and send people through your single sign-on.
Put the same name into the launcher links your own tools build, so people sign in the same way on both routes. The integrations page lists everything ready-made.
Limits
- 3 sessions at once per seat. The whole team shares the sessions of all its seats, and a workspace manager can limit individual members. When every session is in use, Guard.ch refuses new ones instead of queueing them.
- Calls are not metered. Neither requests nor sessions are billed by volume. Residential traffic is the exception: it counts towards the workspace's allowance for the billing cycle.
- Starting sessions is rate-limited. Limits per minute, hour and day protect the platform from too many new sessions. Check the response status and wait before trying again when you reach one.
- The launcher link carries no access. Whoever opens it signs in with their own Guard.ch account. Passing the link on does not pass on your access.
Security
- API keys belong in the Authorization header. Keep them out of URLs, where they land in browser history, proxy logs and analytics.
- Each session's CDP endpoint carries its own token and ends with the session.
- A launcher link holds no credentials and grants nothing; signing 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, workspace and billing data is stored in the EU.
Need help?
If you need help with either route, get in touch.