GatherSurf App Development Guide

Every API in these docs has runnable code in the example project “Sourcing Assistant”. Pick “📘 Example project” when you create an app and you get it — a complete, working app you can edit and publish.
The project also ships an AGENTS.md that you can feed straight to an AI and have it changed to fit your needs (see Build with AI).

What this is

You can build your own apps inside the GatherSurf client, and they run on exactly the same path as the apps we publish ourselves — there is no “developer-mode privilege”, and no “restriction that only appears after listing”. That constraint is deliberate: otherwise you get “works on my machine, breaks once listed”, and that kind of problem is the hardest to track down.

🔎 I want to…

These docs are organised by API, but what you have in mind is usually one task. Match it here first, then jump straight to the part you need.

Running in five minutes

Two paths — pick one. Neither needs you to install anything — the client itself is the development environment.

Path A: let AI write it (no JS required)

1. Left sidebar → “✨ AI Dev” → “+ New app” at the top right
2. Give it a name, and fill in only the second half of the identifier — the prefix is added for you
3. Say what you want in plain language:
   “Build a proxy speed-test board: list all my proxies, test them all on one click, show latency and whether they work, allow sorting by latency, and mark the dead ones red”
4. It will first ask which UI framework to use — just pick one (take the recommended one if unsure)
5. When it is generated, click “▶ Preview” to run it and see the result
6. Not happy? Keep talking: “add a region column”, “test 5 at a time”
7. Happy? Click “📦 Add to My apps” and it becomes a real app you can publish

Path B: write it yourself

1. “Apps” → “🛠 My apps” → “+ New app”
2. Choose “📘 Example project” — that is a complete, working app with a clickable button for every API
3. Click “Open” and run through it to see which API you actually need
4. “📂 Open dev folder”, then edit with your usual editor main.js
5. Save, go back to the client — it reloads automatically, no restart needed

main.js                                 // backend
  exports.register = function (host) {
    host.ipc.handle('hello', async () => ({ ok: true, msg: 'hello' }));
  };

ui/index.html                           // UI (a fragment — no html/body)
  <button id="ab-go">Click me</button><div id="ab-out"></div>

ui/app.js                               // UI logic (must be an IIFE)
  (function () {
    document.getElementById('ab-go').onclick = async () => {
      const r = await gsApp.invoke('hello', {});
      document.getElementById('ab-out').textContent = r.msg;
    };
  })();

Build with AI

The example project ships an AGENTS.md that is written specifically for an AI to read: every API signature, the hard constraints, the common mistakes, and how to change and publish — all in one file.

Three steps

1. Pick “📘 Example project” when creating an app, and you get a complete, working codebase
2. Click “📂 Open dev folder” and hand the whole folder (including AGENTS.md) to your AI
3. Just say what you want — “swap 1688 for Taobao”, “add an automatic price-drop alert”, “export to Excel instead”

An opening prompt you can paste as-is

This is an app project for the GatherSurf client.
Read AGENTS.md first — it states every API, the hard constraints and the common mistakes.
Then change it to match my requirements. Note:
  - do not require('electron') / require('fs')
  - every CSS selector must carry the prefix already used in this project
  - ui/app.js must stay an IIFE
  - schema changes may only append a new version inside ensureSchema(); existing ones must not be edited
My requirement is: ______

Folder layout

your-app/
├─ manifest.json     who you are, what permissions you need, where the entry points are
├─ main.js           backend logic (main process)
├─ README.md         mandatory — the spec check looks for it
└─ ui/
   ├─ index.html     UI fragment (not a complete document)
   ├─ style.css      styles (every selector carries the prefix)
   └─ app.js         UI logic (must be an IIFE)

manifest.json

{
  "key": "abc12-erp-sync",        // your app key — cannot be changed once created
  "name": "ERP Sync",
  "icon": "🚀",                   // emoji, or a path to an image inside the package
  "version": "1.0.0",             // must be x.y.z
  "description": "one-line description",
  "apiVersion": 1,
  "minClientVersion": "0.3.10",   // clients older than this cannot install it
  "permissions": ["storage", "db", "http"],
  "http": { "allow": ["api.mycompany.com"] },   // optional; if the target domain is fixed, declare it truthfully
  "entry": { "main": "main.js", "ui": "ui/index.html" }
}

Permissions

if (!host.db) return { ok: false, error: 'no db permission' };

API cheat sheet

This table is generated directly by platform code — it is the same one the AI assistant is given. A method that is not in it does not exist: writing it gets you undefined, and at runtime is not a function.

Backend: host.ipc

The platform calls exactly one export of yours:

exports.register = function register(host) {
  const { ipc, storage, db, log } = host;

  ipc.handle('hello', async (payload) => {
    log('received', payload);        // written to the client log, for debugging
    return { ok: true, msg: 'hello' }; // goes straight back to the UI
  });
};

// optional, but strongly recommended
exports.deactivate = function () { /* stop your timers */ };

UI: gsApp

const r = await gsApp.invoke('hello', { name: 'Alice' });
if (r.ok) console.log(r.msg);
else gsApp.toast(r.error, true);

Progress events

A long task must not stay silent until it finishes — the user will assume it has frozen.

// backend
ipc.send('progress', { i: 3, total: 10, msg: 'step 3 done' });

// UI
gsApp.on('progress', (p) => {
  bar.style.width = (p.i / p.total * 100) + '%';
});

File storage storage

Everything is synchronous — do not add await.

storage.dir()                      // absolute path of your data folder
storage.list()                     // which files you have stored (array of names)
storage.read(name)                 // text; null if it cannot be read
storage.write(name, text)          // atomic write (.tmp first, then rename)
storage.readJson(name, fallback)   // returns the fallback if missing or corrupt
storage.writeJson(name, obj)
storage.remove(name)               // delete; returns true / false

Database db Requires a paid plan

API

db.query(sql, params)      // read; returns an array of rows (subject to a row cap)
db.exec(sql, params)       // write; returns { changes, lastId }
db.tx(fn)                  // transaction; a throw inside fn rolls everything back
db.migrate(list)           // versioned table creation / alteration
db.path                    // path to the database file

Creating tables: use migrate, don't run CREATE TABLE by hand

db.migrate([
  { v: 1, name: 'create_customers', up: [
      `CREATE TABLE IF NOT EXISTS customers(
         id     INTEGER PRIMARY KEY AUTOINCREMENT,
         name   TEXT    NOT NULL,
         amount INTEGER NOT NULL DEFAULT 0,   -- amounts as integer cents
         created_at_ms INTEGER NOT NULL       -- milliseconds; store Date.now() directly
       )`,
      `CREATE INDEX IF NOT EXISTS idx_customers_at ON customers(at)`,
  ]},
  { v: 2, name: 'add_remark', up: [`ALTER TABLE customers ADD COLUMN remark TEXT`] },
]);

CRUD

// Always use ? placeholders; never build the string yourself.
// The problem is not only injection — one apostrophe in a name breaks your SQL.
const r = db.exec('INSERT INTO customers(name,amount,at) VALUES(?,?,?)',
                  ['Alice', 12800, Math.floor(Date.now()/1000)]);
// r.lastId is the autoincrement id

const rows = db.query('SELECT * FROM customers WHERE amount > ? ORDER BY id DESC LIMIT 50',
                      [10000]);   // ★ always LIMIT

db.exec('UPDATE customers SET amount=? WHERE id=?', [20000, r.lastId]);
db.exec('DELETE FROM customers WHERE id=?', [r.lastId]);

Hard limits

Aggregation: let SQL do it

const byCity = db.query(`
  SELECT city, COUNT(*) AS n, SUM(amount) AS total
  FROM customers GROUP BY city ORDER BY total DESC LIMIT 20`);

Transactions

try {
  db.tx(() => {
    const a = db.query('SELECT amount FROM customers WHERE id=?', [from])[0];
    if (a.amount < amt) throw new Error('insufficient balance');   // throwing = full rollback
    db.exec('UPDATE customers SET amount=amount-? WHERE id=?', [amt, from]);
    db.exec('UPDATE customers SET amount=amount+? WHERE id=?', [amt, to]);
  });
} catch (e) {
  // on arriving here the data is exactly as it was before the transfer
}

When you must use one: several writes that are one thing in business terms. The classic case is “subtract on one side, add on the other” — a crash in between makes money vanish. The example app has a “fail on purpose (verify rollback)” button so you can see it for yourself.

Outbound HTTP http

In the manifest, declaring the "http" permission is all you need. The domain allowlist is optional (see “The domain allowlist is optional” below):

"permissions": ["http"]

// to tell users where you will connect, add this line as well (optional)
"http": { "allow": ["api.mycompany.com", "192.168.1.10:8080"] }

Three entry points — pick by what you want:

// ① fetch JSON — the common case
const r = await http.json('https://api.mycompany.com/orders');
r.data          // ← the parsed object is here
r.status        // 200

// ② when you need the status code / headers, or the other side may not return JSON
const r2 = await http.request('https://api.mycompany.com/ping');
r2.status  r2.ok  r2.headers  r2.text

// ③ same signature as standard fetch — for streaming or special uses
const r3 = await http.fetch('https://api.mycompany.com/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(data),
});
const text = await r3.text();

http.allowed()   // which domains are on the allowlist — you can show this to users
http.mode()      // the current allowlist enforcement mode

Hard limits

★ This is written down because if you only learn the number by hitting it, your first reaction to the error is “my code is wrong”, not “I went over a limit”.

The domain allowlist is optional

Profiles profiles:read profiles:control profiles:write

// profiles:read — reading
await profiles.list()      // [{ id, customNo, name, group, platform, lastOpenedAt, locked }]
                           //   lastOpenedAt = a second-level timestamp; null if never opened (×1000 before new Date in JS)
                           //   locked = true means over the plan quota — this profile cannot be opened (the data is still there)
await profiles.get(id)
await profiles.running()   // an array of id strings: ["p1","p2"], not objects

// profiles:control — acting on existing profiles
await profiles.open(id)
await profiles.close(id)

// profiles:write — changing what the account contains
await profiles.create({ name, group, platform, proxyId, proxyLine, remark })
await profiles.update(id, { name, group, remark, proxyId })
await profiles.remove(id)                    // irreversible
await profiles.proxies()                     // proxy library — only needs :read (it merely lists)
await profiles.addProxy({ name, line })       // line = socks5://user:pass@ip:port
await profiles.checkProxy(id)             // → { ok, ip, country, ms, error }; reachability + latency
                                          //   ★ only needs profiles:read (it changes nothing)
await profiles.groups()                      // [{ id, name, count, builtin?, orphan? }] — only needs :read
                                          //   ★ it contains two kinds of row that are not real groups — see below

Use the one-line proxy string; don't parse it yourself

await profiles.addProxy({ name: 'HK node', line: 'socks5://user:[email protected]:1080' });

The cloud parses it into type/host/port/user/pass. If you parse it yourself, one change on either side and the two disagree — and disagreement shows up as “the proxy is configured and has no effect”, which is painful to track down.

Page actions automation A key focus of review

The first argument is always the profile id. You must profiles.open(id).

await automation.newTab(id, url)          // → { id, url }; http/https only
await automation.tabs(id)                 // → [{ id, url, title }]
await automation.closeTab(id, tabId)      // → { ok, closed } / { ok:false, why }; close it when done
await automation.evaluate(id, 'document.title')   // → the value of the expression itself (no return)
await automation.realClick(id, '#su')     // pass the selector directly
await automation.realType(id, '#kw', 'text')
await automation.realClick(id, x, y)      // coordinates also work (rarely needed — see below)
await automation.realKey(id, 'Enter')
await automation.screenshot(id, {})       // → { ok:true, base64:'…' }
await automation.dwell(id, { scrolls: 4 })        // → { dwelled, scrolls, wander }; human-like dwell

const tab = await automation.newTab(id, url);
await automation.evaluate(id, expr, { tabId: tab.id });
await automation.realType(id, '#kw', 'text', { tabId: tab.id });

// probe once and use what you found
const sel = await automation.evaluate(id, `(() => {
  for (const el of document.querySelectorAll('input,textarea')) {
    const b = el.getBoundingClientRect();
    if (b.width > 60 && b.height > 16 && el.id) return '#' + el.id;
  }
  return '';
})()`);
await automation.realType(id, sel, 'fingerprint browser');

const r = await automation.runSteps(id, [
  { op: 'goto', url: 'https://example.com' },
  { op: 'waitForSelector', selector: 'h1' },
  { op: 'evaluate', code: 'return document.title' },
]);
if (!r.ok) return { ok: false, error: r.error };   // ← failure does not throw — you must check .ok yourself
r.results     // one object per step: [{ op, ok, value, error }, ...]
r.vars        // variables stored by saveTo during the flow

{ op:'evaluate', code:'return document.querySelectorAll(".result").length' }

Walkthrough: open a window → go to 1688 → search → store results

The previous sections cover how each API is used; this one shows what they look like strung together — this is the shape of the code you actually write for real work.

Seven steps

1. Pick a profile — the first one if none is given. A real app should let the user choose, or rotate by group; blindly using the first one keeps hitting the same profile in a multi-account setup
2. Make sure it is open — skip if it already is; opening again runs a full startup and wastes several seconds
3. Build the search URL directly Open a tab instead of going to the home page and clicking the search box — never express with a click what a URL can express; one step fewer is one thing fewer that can break
4. Poll until the products render (see below)
5. evaluate Scrape the data inside the page
6. Save a screenshot as evidence
7. one transaction Bulk-write into the database

let found = 0;
for (let i = 0; i < 20; i++) {
  found = await automation.evaluate(pid,
    `document.querySelectorAll('[class*="offer"]').length`);
  if (found > 0) break;
  await new Promise(r => setTimeout(r, 700));
}
if (!found) return { ok:false, error:'no products found on the page — it may need a login, be rate-limited, or have been redesigned' };

try {
  tabId = (await automation.newTab(pid, url)).id;
  // …any early return in between…
} finally {
  if (tabId) await automation.closeTab(pid, tabId);
}

Code inside evaluate runs in the page

const items = await automation.evaluate(pid, `
  (function () {
    var out = [];
    document.querySelectorAll('[class*="offer-item"]').forEach(function (c) {
      var t = c.querySelector('[class*="title"]');
      if (t) out.push({ title: t.innerText.trim() });
    });
    return out;      // ★ must be JSON-serialisable
  })()`);

Use one transaction for bulk writes

db.tx(() => {
  for (const it of items) db.exec('INSERT INTO offers(...) VALUES(?,?,?)', [...]);
});

Ten rows in ten commits means ten disk syncs — an order of magnitude slower.

File picker files:pick

const f = await files.pickOpen({
  title: 'Pick a CSV',
  filters: [{ name: 'Spreadsheet', extensions: ['csv', 'xlsx'] }],
});
if (!f) return;                       // the user cancelled — not an error
f.name; f.size; f.path; f.bytes;      // bytes is a Buffer

await files.pickSave({ title: 'Export', defaultPath: 'out.csv' }, buffer);

Three constraints when writing the UI

0. Use the platform components first; don't write styles from scratch

The platform provides a set of component classes prefixed with gs- -prefixed component classes; just use the class names — you do not write those styles yourself. They follow the client theme and match the host UI naturally.

Class reference

Buttons

Layout

Data display

Forms

Marks and notices

1. The HTML is a fragment, not a complete document

Do not write <html> / <head> / <body>. It is mounted straight into the host UI.

2. Every CSS selector needs the prefix

One rule only: in ui/style.css, every rule and every comma-separated part of it must start with .your-prefix-.

.abc-wrap { }                ✅
.abc-wrap .title { }         ✅ descendant selector — already fenced inside its own subtree by the prefix
.abc-btn:hover { }           ✅ pseudo-class
@media (max-width:600px){ .abc-wrap { } }   ✅ still required inside media queries
@keyframes abc-fade { }      ✅ prefix animation names too (avoids clashing with others)

.wrap { }                    ❌ bare class
button { }                   ❌ every button in the client would change
#panel { }                   ❌ ids are global
* { margin:0 }               ❌ one reset line can wreck the entire client UI
.abc-a, .navbar { }          ❌ the part after the comma needs it too
.gs-btn { background:red }   ❌ platform components may be used, not modified

Third-party frameworks: three are already bundled

One line in manifest.json enables it, and the app carries no framework files:

{
  "key": "abc-demo",
  "ui": { "framework": "bootstrap5" },
  ...
}

<!-- once bootstrap5 is declared, just write this -->
<div class="card"><div class="card-body">
  <button class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#m1">Open</button>
</div></div>

<!-- class-free frameworks (milligram / daft) need no class at all -->
<h2>Heading</h2>
<form><input type="text"><button>Submit</button></form>
<table>…</table>

{ "key": "abc-bulk-run", "uiPrefix": "abrun", … }

To use a framework other than the bundled three

You can, but you must scope-wrap it first. Importing it as-is is rejected by the spec check — the first thing frameworks like this do is reset the global: *{box-sizing:border-box}, body{margin:0}, h1~h6 font size… The app UI and the client share one document, so those rules hit host elements and change the whole client's typography — for everyone who installed the app.

How: prefix every rule of the framework with a container class of your own, then wrap the HTML in that container.

/* ❌ as-is — the spec check rejects this */
*,::before,::after { box-sizing: border-box }
body { margin: 0 }
.btn-primary { ... }

/* ✅ prefix every rule with .abc-bs */
.abc-bs *, .abc-bs ::before, .abc-bs ::after { box-sizing: border-box }
.abc-bs body { margin: 0 }        /* matches nothing — harmless */
.abc-bs .btn-primary { ... }

<!-- wrap one layer in the HTML; inside, use the framework classes as usual -->
<div class="abc-bs">
  <div class="card"><div class="card-body">
    <button class="btn btn-primary">OK</button>
  </div></div>
</div>

Wrapping can be done by a tool; you do not edit thousands of lines by hand:

# Sass: one line
.abc-bs { @import "bootstrap/scss/bootstrap"; }

# PostCSS
postcss bootstrap.css --use postcss-prefix-selector \
  --postcss-prefix-selector.prefix ".abc-bs" -o scoped.css

The prefix is derived from the key (first letter of each segment). A CSS identifier cannot start with a digit, so one starting with a digit automatically gets a a: 8d7dk-example → a8e prepended. The spec check tells you which prefix to use.

3. app.js must be an IIFE

(function () {
  'use strict';
  // your code
})();

Without a wrapper your let out = ... lands on window and collides with the host or another app — and a collision shows up as “another app's variable inexplicably changed”, the hardest kind to track down.

Developer ID and app_key

Before publishing your first app, register a developer ID under Apps → 🛠 My apps (the API field name is devHandle). It becomes the prefix of all your apps — the same thing as npm's @scope, a Docker username, or a VS Code publisher.

developer ID you registered    smartmob
second half of the app key     sourcing        ← lowercase letters / digits / hyphens only
                     ↓
resulting app_key              smartmob-sourcing

Why a prefix is required

app_key is not just a name; it is simultaneously three things:

So two developers who each create an app called report would overwrite each other, and silently — B's client installs A's code with no error at all. The prefix exists to prevent exactly this.

Naming suggestions

Rules: 3–20 characters, starts with a lowercase letter, lowercase letters, digits and hyphens only; no consecutive hyphens and no trailing hyphen. official gathersurf admin Reserved words like these cannot be registered — they would be used to impersonate the platform.

Naming variables and endpoints

Inside your app, write it however you like — we do not check. But the set below is what the platform itself uses, and following it means your code, the docs, the example project and whatever AI writes for you later all look like one codebase.

The rules in one line

Why IPC channel names are module:action

goods:list      goods:star     goods:remove
collect:start   collect:stop   collect:state
win:create      win:remove     win:proxies

The benefit is that a module prefix shows you every action of one feature at a glance, whereas names like listGoods / starGoods / removeGoods scatter through a long list. The thirty-odd handlers in the example project main.js are ordered this way — skim it and the intent is obvious.

A name should say what it is, not how short it is

Database tables and columns

The conventions for host.db when creating tables. This is not fastidiousness — SQL has its own rules, and writing it the JS way gets you bitten by the language itself.

Why not camelCase in the database

SQL case-folds unquoted identifiers. You write createdAt, and what gets stored may be createdat; to preserve the case you must quote it everywhere, and one missed spot is a runtime error. So:

database column   snake_case     created_at_ms, goods_id, price_cents
    ↓ converted once, at the moment it is read out
JS code           camelCase      createdAt,  goodsId,  priceCents

Keep the conversion point in exactly one place — the object your query function returns. Outside that function the whole app is camelCase.

// ✓ hand-written projection — one conversion point
function listGoods() {
  // host.db is synchronous — do not add await
  const rows = host.db.query(
    'SELECT id, title, price_cents, created_at_ms FROM goods ORDER BY id DESC LIMIT 200');
  return rows.map(r => ({
    id: r.id, title: r.title,
    priceCents: r.price_cents,      // ← the conversion happens only here
    createdAtMs: r.created_at_ms,
  }));
}

// ✗ returning database rows directly — underscores then leak throughout the app
function listGoods() {
  return host.db.query('SELECT * FROM goods');   // and there is no LIMIT
}

Timestamps: your database uses milliseconds, our cloud uses seconds

You may notice the inconsistency, so to be clear —these are not two standards but one principle: Do zero conversion on the writing side.

Date.now() gives milliseconds; time.time() gives seconds. Each stores directly, so there is no conversion and therefore no chance of converting wrongly.

And the two databases never meet — an app cannot obtain our cloud timestamps (profiles.list() returns only id / profile number / name / group / platform), so there is no risk of two units landing in one column. That was always the fatal part, not which unit you pick.

Column conventions

Create tables through migrate(), not a direct exec

Put both table creation and column additions in migrate(). It keeps a ledger by version number: a version that has run is skipped entirely on the next start, so you can call it unconditionally in register() without checking whether the table exists.

host.db.migrate([
  {
    v: 1,
    name: 'create_goods',
    up: [`
      CREATE TABLE IF NOT EXISTS goods (
        id            INTEGER PRIMARY KEY AUTOINCREMENT,
        keyword       TEXT    NOT NULL,
        title         TEXT    NOT NULL,
        shop_name     TEXT,
        price_cents   INTEGER NOT NULL DEFAULT 0,   -- integer cents, never floats
        is_starred    INTEGER NOT NULL DEFAULT 0,   -- boolean: 0/1
        source_url    TEXT,
        created_at_ms INTEGER NOT NULL,             -- Date.now(), milliseconds
        updated_at_ms INTEGER NOT NULL
      )`,
      // index the columns you query most — past a few thousand rows, an unindexed fuzzy search visibly stalls
      `CREATE INDEX IF NOT EXISTS idx_goods_keyword ON goods(keyword)`,
    ],
  },
  // to add a column later, add a new version; do not edit the contents of v:1
  { v: 2, name: 'goods_add_note', up: [`ALTER TABLE goods ADD COLUMN note TEXT`] },
]);

returns { from, to } — the two values being equal means nothing ran this time.

Use exec(sql, params) for insert, update and delete; query(sql, params) for queries; and wrap a batch of writes in tx(fn).

External API: what it is and how to enable it

Besides developing an app inside the client, there is a second path: drive GatherSurf from your own language, in your own process. The client runs an HTTP service on the local machine, and you can use Python, Node, Go, curl — anything.

How to enable

1. Client → Settings →Local Automation API→ turn on
2. The same page shows your token (the account-level API token)
3. The address is fixed at http://127.0.0.1:48090 and listens on the local machine only

Up and running in 30 seconds

Liveness first (this one needs no token)

curl http://127.0.0.1:48090/gs/v1/health

Python

import os, requests

BASE  = "http://127.0.0.1:48090/gs/v1"
TOKEN = os.environ["GS_TOKEN"]          # ★ never hard-code it
H = {"X-GS-Token": TOKEN}

# 1. create a profile
r = requests.post(f"{BASE}/profiles", headers=H, json={
    "name": "test profile",
    "group": "Default",
    "proxyLine": "socks5://user:[email protected]:1080",   # optional
}).json()
pid = r["data"]["id"]

# 2. open the window — returns a CDP address for playwright/puppeteer to take over
r = requests.post(f"{BASE}/profiles/{pid}/launch", headers=H, json={}).json()
cdp = r["data"]["automation"]["cdpWs"]
print("CDP:", cdp)

# 3. attach with playwright
from playwright.sync_api import sync_playwright
with sync_playwright() as pw:
    browser = pw.chromium.connect_over_cdp(cdp)
    page = browser.contexts[0].new_page()
    page.goto("https://httpbin.org/ip")
    print(page.content()[:200])

# 4. close it
requests.post(f"{BASE}/profiles/{pid}/shutdown", headers=H, json={})

Node

const BASE = 'http://127.0.0.1:48090/gs/v1';
const H = { 'X-GS-Token': process.env.GS_TOKEN, 'Content-Type': 'application/json' };
const api = async (method, path, body) => {
  const r = await fetch(BASE + path, { method, headers: H,
    body: body ? JSON.stringify(body) : undefined });
  const j = await r.json();
  if (!j.ok) throw new Error(`${path} failed: ${j.error?.message || r.status}`);
  return j.data;
};

const { id } = await api('POST', '/profiles', { name: 'test profile' });
const { automation } = await api('POST', `/profiles/${id}/launch`, {});
console.log('CDP:', automation.cdpWs);

// take over with puppeteer
const puppeteer = require('puppeteer-core');
const b = await puppeteer.connect({ browserWSEndpoint: automation.cdpWs });
const p = await b.newPage();
await p.goto('https://httpbin.org/ip');
console.log((await p.content()).slice(0, 200));

await api('POST', `/profiles/${id}/shutdown`, {});

success:  { "ok": true,  "data": { … } }
failure:  { "ok": false, "error": { "code": "forbidden", "message": "plain language" } }

Test console: download and usage

The Local API test console is an external tool — zero-dependency Node, with a UI, full source included. It is written from a third-party developer’s point of view: it uses only the public endpoints on this page and relies on no internal conventions. Two uses: run everything once to see what works, and a calling example you can copy straight out.

What it can do

Download

https://api.gathersurf.com/download/tool/gs-api-test  ·  Version and checksum: /manifest

This URL always points at the newest release (it 302-redirects to the nearest download node), so there is no version number to remember. After downloading, check that sha256 matches the manifest — this tool asks you to paste your token into it, which makes those 5 seconds worth spending:

shasum -a 256 gs-api-test.zip                # macOS / Linux
certutil -hashfile gs-api-test.zip SHA256    # Windows

How to run it

Requires Node 18 or newer (check with node -v). Unzip, then in that directory:

node gs-api-test.js      # starts the UI; open http://127.0.0.1:48099
node e2e.js              # or skip the UI and run the end-to-end scenarios

Once the UI is open, paste your token in and start clicking. ★ the token lives only in this Node process’s memory — never written to a file, never logged. Kill the process and it is gone, so you paste it again every time you start it.

Endpoint reference

The service itself

Profiles

Fingerprints

Cookie

Batch

Batch endpoints always return per-item results: { total, succeeded, results:[{id, ok, error?}] }—— a partial failure does not fail the batch, and you know exactly which ones did not succeed.

Proxies

Groups / tags / recycle bin

Kernels

Common recipes

Auto-check a proxy pool and tag the bad ones

proxies = requests.get(f"{BASE}/proxies", headers=H).json()["data"]["proxies"]
for px in proxies:
    r = requests.post(f"{BASE}/proxies/{px['id']}/check", headers=H,
                      json={"timeoutMs": 8000}).json()["data"]
    if not r["alive"]:
        # tag it for a human to look at
        requests.patch(f"{BASE}/proxies/{px['id']}", headers=H,
                       json={"tags": px.get("tags", []) + ["dead"]})
    print(px["id"], "✓" if r["alive"] else "✗", r.get("ip", r.get("error")))

One proxy per profile, created in bulk

lines = open("proxies.txt").read().split()
for i, line in enumerate(lines, 1):
    chk = requests.post(f"{BASE}/proxies/check", headers=H, json={"line": line}).json()["data"]
    if not chk["alive"]:
        print(f"skipping line {i}: {chk['error']}"); continue   # ★ verify first, don't create a pile of dead profiles
    requests.post(f"{BASE}/profiles", headers=H, json={
        "name": f"p-{i}-{chk['country']}", "proxyLine": line,
        "basedOnIP": True,     # align language/timezone to the exit IP, avoiding geographic contradictions
    })

Copy one profile's fingerprint into another account

# export from account A
fp = requests.get(f"{BASE}/profiles/{pid}/export", headers=H).json()["data"]
json.dump(fp, open("fp.json", "w"))

# import into account B (different token) — restores the same fingerprint
fp = json.load(open("fp.json"))
requests.post(f"{BASE}/profiles/import", headers=H2, json={"fingerprint": fp, "name": "restored"})

Open profiles in bulk to run a task, with bounded concurrency

ids = [p["id"] for p in profiles[:10]]
r = requests.post(f"{BASE}/profiles/batch/launch", headers=H,
                  json={"ids": ids, "intervalMs": 2000}).json()["data"]
print(f"{r['succeeded']}/{r['total']} launched")
for x in r["results"]:
    if not x["ok"]: print("  failed:", x["id"], x.get("error"))
    else:           print("  CDP:", x["automation"]["cdpWs"])

# … run your task …

requests.post(f"{BASE}/profiles/batch/shutdown", headers=H, json={"ids": ids})

Spec check

⚙ Settings → Spec check. A failing check blocks packaging — not to obstruct you, but because these same problems get rejected after upload, when the reason was knowable locally all along.

The spec check covers only what a machine can decide. Whether the permissions are minimal and the error handling adequate needs a human — passing the check does not guarantee approval.

Three ways to publish

The code you ship is encrypted

As soon as it goes through cloud distribution (team / public listing), the package the user installs locally is .js .html .css .json .md .txt, on disk, ciphertext. A member who opens the app folder sees binary, and copying it away does not make it run.

✗ const tpl = fs.readFileSync(path.join(__dirname,'tpl.html'),'utf8')
✓ const tpl = require('./tpl.js').html        ← goes through require
✓ const cfg = require('./config.json')        ← require understands .json

Authorisation — who may install your app

After publishing to the team, go to My apps → ⚙ Settings → 🔑 Authorisation and grant access by the other party's registered email. An authorised account does not have to be a member of your team — it can be any GatherSurf account.

Listing review

Submissions go into a queue and are read by a person. The version you already have listed is unaffected during review — users carry on with the old version while the new one queues separately.

What we look at

• Whether the permissions are minimal — you requested automation but never actually use it?
• Whether the outbound allowlist is reasonable — any wildcards? where is data being sent?
• The code itself — the review UI shows every file in the package, and a mismatch between declaration and implementation gets noticed
  (we review the plaintext original you uploaded; encryption happens after review passes, so it neither hinders review nor slows it down)

How you are notified of the result

• The client raises a notification and puts a badge on Apps in the sidebar
• A status line stays on the card; clicking “Details” shows the full review history — how many times it was submitted and the reason for each rejection
• You may leave a contact email on submission, and the reviewer sends the result there

⚠ Pitfalls at a glance

These have all actually caused problems, and what they share is that they raise no error — which makes them very hard to diagnose afterwards, while avoiding them as you write costs almost nothing.