All integrations

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.

Create an API key

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"
  }'
  • extensions The 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.
  • country Exit location as a country or city code (us, de, us-dal). The older way of naming the Location Switch app; it still works.
  • egress Set 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.
  • proxy Your own proxy URL, for an exit you control. Stands for the Proxy Connect app and cannot be combined with country or residential.
  • screen Viewport as width and height.
  • url An http or https address to open straight away.
  • name Display name in the session list. One is generated when you leave it out.
  • idempotencyKey Retry 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/sessions lists running sessions; status=all adds the ended ones of the last 30 days, limit caps the page
  • GET /web/sessions/:id returns one session, with its connectUrl while it runs
  • POST /vm/:vmId/extensions switches apps on in a running session; PATCH and DELETE on /vm/:vmId/extensions/:id change or end one
  • DELETE /web/sessions/:id stops a session and frees its slot
  • GET /web/usage returns 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.com

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

  • url The URL-encoded target address. Links from our browser add-ons 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). Without it, the session starts on the person's usual exit.
  • workspace Your 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.

Open the launcher

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.

Try Guard.ch for 30 days.

Business starts with a {days}-day trial: you add a card and pay nothing until it ends.

Start 30-day trial