API Reference

The GoUndetected API lets you manage browser profiles, folders, proxies, notes and folder permissions programmatically — for teams and agencies running their own or their clients' social-media accounts. It is one API with two credentials: classic API keys on /v1, and Connect tokens (Preview) on Tools v2 (/v2/tools/*) for agents and batch work — see Tools & Connect. Each job (create profiles, folders, cookies, …) is documented once; where both surfaces cover it, the endpoint names the other in one line.

Classic requests go to https://api.goundetected.io; Tools Preview uses the base in your Connect setup. Classic API keys only see or change data in their organization. Tools Preview can read shared-in folders within their grants. Successful classic deletes return 204 with no body; other responses return JSON.

Authenticate every request with an API key in the Authorization header as a Bearer token:

Authorization: Bearer gou_live_xxxxxxxxxxxxxxxxxxxx

Create and manage keys in the desktop app under Settings → API Keys (owner only). The full key is shown once at creation — store it securely; it can't be retrieved later. Each key is granted scopes that gate which endpoints it can call.

Scopes: profiles:read, profiles:write, folders:read, folders:write, proxies:read, sessions:read, sessions:write.

Connect tokens (groot_pat_…, Preview) are the credential for Tools v2 (/v2/tools/* only — they are refused on /v1, and gou_live_… keys are refused on /v2/tools). An organization owner or admin creates one in the desktop app under Settings → Integrations (Connect), picks its permissions and expiry, and copies the token once — it is never shown again (lifecycle: Agent connections). Send it as Authorization: Bearer <token> to the API base shown in the Connect setup block.

Connect scopes (granular — the classic profiles:write / folders:write are not accepted as aliases):

*:delete scopes never delete directly: they only let the token request a deletion that an owner or admin confirms in Activity (see Confirmations). Plans and limits: Pricing.

Preview. Tools v2 is available through Connect on supported desktop builds (Settings → Integrations (Connect)). The production public base for classic automation remains https://api.goundetected.io (/v1). Treat Tools paths as Preview until general availability is announced — shapes may still change. After release Tools v2 is intended to be served from the same host (/v2/tools/*, not under /v1); until then use the API base shown in your Connect setup block.

GoUndetected exposes two complementary surfaces. The classic REST API (/v1, gou_live_… keys) manages profiles, folders, cookies and cloud browser sessions. Tools v2 via Connect is the agent-friendly batch surface: create folders and profiles in groups, assign proxies, add notes and discover capabilities — always scoped to one organization, with dry-run previews and human confirmation for destructive work.

Credentials and scopes for both surfaces are in Authentication — one section, two credential types (gou_live_… API keys for /v1, groot_pat_… Connect tokens for /v2/tools/*).

Mutations. Send an Idempotency-Key header (8–200 printable characters, e.g. a UUID) on every real mutation. Reuse the same key only to retry the same body; a different body with a used key returns 409 idempotency_conflict. With "dryRun": true nothing is written and no key is needed. For cURL examples, set GOU_IDEMPOTENCY_KEY once for the operation (for example with uuidgen) and keep that value for retries.

Limits (Preview). Lists return 100 items by default (max 200). A single mutation touches at most 250 profiles and is atomic — oversized batches are rejected, never truncated. 60 requests per minute per credential. Idempotent replays are kept for at least 7 days.

Where the endpoints live. Tools v2 is not a separate product surface: its commands are documented inline with each resource — Profiles (one Create profiles — with or without a proxy — and Assign proxies), Profile notes and Folders. Each operation appears once; where classic /v1 covers the same job, the endpoint names its /v1 equivalent in one line.

What Tools v2 is not. It does not launch cloud browsers over CDP (use @goundetected/sdk and the /v1 sessions API), and it has no cookie endpoints — cookie list (JSON) / import / clear are classic /v1 only, see Cookies. Folder permissions are also /v1 only (Folder permissions).

Call GET /v2/tools/capabilities first. It tells an agent exactly what this token may do: its organization, scopes, every read and command with allowed / missingScopes, which commands need human confirmation, supported proxy sources, limits, and the organization-isolation policy. Calling it with a new Connect token also marks the connection Verified in Settings → Integrations (Connect).

A profile is an isolated browser identity (fingerprint, viewport, and an optional proxy). Profiles live inside folders — new profiles are placed in an existing folder or a new one at creation.

Choose one compound request for onboarding. POST /v2/tools/profiles/create can create the destination folder, all profile groups and their proxy bindings together. Set destination.createFolder with each group's proxySource; preview that same body with dryRun: true, then submit it with dryRun: false and an Idempotency-Key. The backend commits the folder, profiles and bindings atomically. Notes can then be added in one Create notes call using the returned profile ids; notes are a separate operation.

Batch changes to existing profiles. Put up to 250 changes in updates[] for one Update profiles call, send one profileIds[] list to Move profiles, or bind proxies in order with Assign proxies. Each call is its own atomic operation; preview and retry it with its own idempotency key.

Create profiles is one endpoint: 1–10 groups per atomic request, into a new or existing folder. Every group must carry proxySource: { "kind": "none" } for profiles without a proxy, inline (alias raw, your own proxies) or folder_profiles (reuse proxies already bound in another folder). There is no implicit default — a missing or non-object proxySource returns 400 invalid_input (proxySource is required). Groups can differ by OS (macos / windows) and by proxy source. Profiles are auto-named "Profile N" (naming continues across groups) unless you set names.

Always dry-run first. If a folder_profiles group asks for more proxies than are available, the request fails with 409 insufficient_reusable_proxies and nothing is created — no partial batches and no silent proxy cycling. That refusal is recorded and consumes the Idempotency-Key, so retry with a new key after adding proxies.

Inline / raw proxies. One proxy per profile in items (alias proxies): host:port, host:port:user:pass, user:pass@host:port, scheme://user:pass@host:port (http, https, socks5), or { host, port, username?, password?, type?, country?, timezone? }. Bound 1:1 in order — the group count (optional for inline) must equal the number of items. An unreadable item returns 400 invalid_input with its path (e.g. $.groups[0].proxySource.items[1]); error messages never echo the item. Passwords never appear in responses, Activity or stored results — inline sources are echoed as { kind: "inline", count }.

Classic API keys. The endpoints below use a Connect token (Preview). With a classic gou_live_… key, use the /v1 equivalent noted on each endpoint — e.g. POST /v1/profiles/create creates a single profile with { folderId, name?, userAgent?, viewportWidth?, viewportHeight?, proxy? } (the proxy is optional there too).

Assign proxies (existing profiles). Assign or replace proxies on profiles that already exist — either copied from profiles in another folder (folder_profiles) or supplied inline. Targets must not be running (409 profiles_running). Responses return safe references only (proxyRef, protocol, host, port, country, hasAuth) — never logins or passwords.

Scopes: profiles:update + proxies:use for inline; folder_profiles additionally needs proxies:read. A folder_profiles shortage returns 409 insufficient_reusable_proxies with nothing changed.

Read, create and update notes on profiles — up to 250 per call, atomic, max 10,000 characters per note. An empty note is refused (clearing is a separate, confirmed action). Note bodies are never written to Activity — only note ids and lengths.

Read and write a profile's cookies without launching the browser. Cookies use the common Cookie-Editor / EditThisCookie JSON shape, so exports from those extensions import directly.

The profile must not be running while you import or clear its cookies — mutating a live profile returns 409 Conflict.

Export: GET /v1/profiles/{id}/cookies returns the profile's cookies as JSON (data[]) in the same shape POST accepts — save that array to move cookies to another profile or tool.

Classic API key (`/v1`) only. Tools v2 / Connect has no cookie endpoints (no list, import, export or clear), and Connect tokens are not accepted here — use an API key with profiles:read / profiles:write. The SDK wraps these routes (gg.profiles cookies helpers).

Folders group profiles and are the unit of access control. Deleting a folder removes its profile assignments and permissions; the profiles themselves are kept unless you choose otherwise.

With a Connect token, folder lists include folders shared into your organization by default: every item carries folderType (owned | shared_in), sharedFrom for shared-in folders, and your access (view / run / edit / full). Filter with scope=all (default) | owned | shared_in.

Shared-in folders are read-only. Any write that names a shared-in folder or a profile inside one — create into, use as a proxy source, move in or out, assign proxies, notes, rename, delete requests (dry-run included) — returns 403 permission_denied with details.reason: "shared_in_read_only". Request changes from the owning organization.

Member tokens act with the issuing member's folder permissions (see Folder permissions); owners and admins see every folder in the organization.

Control which members of your organization can view, run, or edit a folder. Permissions are per-member.

Destructive Tools commands — delete profiles, clear notes, delete folders — never execute on the token alone. They return 202 with state: "awaiting_confirmation", a proposal.digest and a reviewPath. An organization owner or admin reviews it in the desktop app under Settings → Activity and clicks Confirm or Decline. A Connect token cannot confirm its own proposals.

Confirmation re-checks the targets: if they changed since the proposal (different digest), the operation fails with 409 source_changed and nothing is executed; running profiles return 409 profiles_running and the proposal stays pending. Proposals expire after 72 hours (410 confirmation_expired).

Preview note: approval execution ships with the Tools v2 release. Until then a confirm may answer 503 unavailable and the proposal stays pending — nothing is deleted.

Track any operation with GET /v2/tools/operations/{id} — state is one of awaiting_confirmation, queued, running, succeeded, failed, declined, expired; decided operations include decidedAt and decidedByUserId.

Agent connections are the Connect tokens listed under Settings → Integrations (Connect). Only organization owners and admins can create, edit or revoke them, and only from a signed-in desktop session — a Connect token or API key can never issue, edit or revoke tokens (including itself). The routes below are what the desktop app calls; they are documented for transparency.

Create: name, permissions (all selected by default) and expiry (30 / 90 default / 180 / 365 days, or Never). The token is returned once. Up to 25 active connections per organization. Revoke takes effect on the next request; the row stays for audit.

Edit permissions replaces the connection's scopes. The token string does not change and is never returned again; new scopes apply on the token's next request.

One token = one organization. Every API key and Connect token is issued in exactly one organization. Classic API keys read or change only that organization's data. Connect tokens can also read folders shared into it within their grants; shared-in writes are denied. There is no "switch organization" with the same token: to work in another organization, create a connection there.

GET /v2/tools/capabilities reports this as orgIsolation (patScopedToSingleOrg: true, crossOrgReads: false, crossOrgWrites: false, shareTransfer: "secure_form_human_confirm", sharedIn: "read_only_within_grants") plus plain-language policies an agent should follow.

Share & transfer — not enabled. Sharing, unsharing and transferring folders between organizations are hard denied for Connect tokens today. The endpoints exist only so agents get a clear, safe answer; they never write anything (no operation, no Activity entry).

Never from chat. A target organization id is accepted only together with a confirmation from the desktop Secure Form, where an owner or admin picks the target organization and confirms. An organization id typed into a chat or prompt is never enough.

Paths (stub): POST /v2/tools/folders/share-requests, /unshare-requests, /transfer-requests. GET /v2/tools/capabilities reports shareTransfer.execute: "hard_denied" and lists these commands under policy.hardDenied.

The official `@goundetected/sdk` lets you drive GoUndetected from code — manage profiles, folders and cookies, and, the headline feature, launch a profile as a live cloud browser you control with Puppeteer or Playwright. Same account, same profiles, same proxies as the desktop app — now scriptable. npm: npmjs.com/package/@goundetected/sdk

Install

npm install @goundetected/sdk puppeteer-core

You control the cloud browser over CDP, so you need a CDP client — puppeteer-core (no bundled Chromium, it just connects) or Playwright (chromium.connectOverCDP). Works in Node 18+, ships ESM + CommonJS, with TypeScript types included.

Get an API key

In the desktop app go to Settings → API Keys and create a key with the scopes you need. For automation you almost always want profiles:read + sessions:write (add profiles:write to also create profiles from code). Treat the key like a password — put it in an env var, never in git.

Quick start

import { Goundetected } from "@goundetected/sdk";
import puppeteer from "puppeteer-core";

const gg = new Goundetected({ apiKey: process.env.GOU_API_KEY });

// 1. launch a profile as a cloud browser
const session = await gg.launch("<profileId>");

// 2. connect Puppeteer over CDP
const browser = await puppeteer.connect({ browserWSEndpoint: session.browserWSEndpoint });
const page = (await browser.pages())[0] ?? (await browser.newPage());

// 3. drive it — you're on the profile's fingerprint + proxy
await page.goto("https://ipinfo.io/json", { waitUntil: "domcontentloaded" });
console.log(await page.evaluate(() => document.body.innerText));

// 4. always stop when done (frees the browser + syncs the profile)
await browser.disconnect();
await session.stop();

That's the whole loop: launch → connect → drive → stop.

The client

const gg = new Goundetected({
  apiKey: "gou_live_…",                    // required
  baseUrl: "https://api.goundetected.io",  // optional (this is the default)
});

It exposes three resource groups plus launch(): gg.profiles (list / get / create / update / delete + cookies), gg.folders (list / get / create / update / delete), gg.sessions (list / get / heartbeat / stop), and gg.launch(profileId, opts?) which starts a cloud browser and returns a Session.

Launching a cloud browser

const session = await gg.launch(profileId, {
  region: "us-east-1",     // optional — omit to let the server pick
  ttlSeconds: 900,          // optional — auto-stop horizon (see below)
  readyTimeoutMs: 120000,   // optional — wait for the browser (default 120s)
});

launch() resolves once the browser is connectable and returns a Session: pass session.browserWSEndpoint to puppeteer.connect({ browserWSEndpoint }) or chromium.connectOverCDP(url). It also carries session.sessionId, session.region, session.heartbeat() and session.stop(). Cold start is ~30–60s — a fresh browser is provisioned on demand.

TTL, heartbeat & auto-stop

Every cloud session has an auto-stop horizon. A background reaper stops any session whose horizon lapses, so a crashed or forgotten script can't leave a browser — and your bill — running forever. Default TTL is 5 minutes: untouched for ~5 min → stopped. Each session.heartbeat() pushes the horizon 5 minutes into the future. Prefer a fixed window instead? Pass ttlSeconds at launch (60–43200, up to 12h).

For anything longer than a few minutes, heartbeat on a timer:

const hb = setInterval(() => session.heartbeat().catch(() => {}), 2 * 60 * 1000);
try {
  // … your long automation …
} finally {
  clearInterval(hb);
  await browser.disconnect();
  await session.stop();
}

Rule of thumb: heartbeat every 2 minutes while working, and stop the moment you finish — prompt stops are what keep your cloud-hours low.

Concurrency & cloud-hours limits

Cloud sessions use real compute, so every plan includes a monthly cloud-hours pool and a cap on simultaneous sessions. launch() throws before starting anything if you're over a limit — 403 for cloud-hours reached / not on your plan, 409 for concurrency. Local desktop launches are free and never counted. Watch usage in the app under Billing → Cloud browser usage.

Requirements & gotchas

Logged-in profiles — for sites behind a login (LinkedIn, etc.) the profile must already be signed in: do it once in the desktop app (cookies persist) or import them with setCookies. Heavy SPAs load async — after page.goto, await page.waitForSelector(...) for the element you need, don't rely on domcontentloaded alone. Cold starts (~30–60s) are normal (on-demand provisioning). Acceptable use — proxies + cloud are for managing your own or clients' social-media accounts; no scraping, spam, or abuse.

Both surfaces return one error envelope with the right HTTP status. Tools v2 adds a retryable flag and optional details (e.g. path, reason, operationId):

{ "error": { "code": "invalid_input", "message": "…", "retryable": false, "details": { "path": "$.groups[0].proxySource" } } }