Profile recipes

Use profile IDs from the actual response. Names need not be unique, and the displayed profile number is not the UUID.

Create and read back

Save this fictional payload as profile.json. It creates configuration; it does not install a kernel or start a browser. profiles:write is required for creation and profiles:read for reading back.

JSON

{
  "name": "Documentation example",
  "engine": "chromium",
  "os": "windows",
  "notes": "Example profile"
}

Node.js CLI

node tabgecko.mjs request POST /api/v1/profiles profile.json
node tabgecko.mjs request GET /api/v1/profiles/PROFILE_ID

Replace PROFILE_ID with the returned id. The OS field is a profile setting, not a promise that every engine/OS combination is available on the host. Query /api/v1/kernels before launch.

Start, inspect, stop

Node.js CLI

node tabgecko.mjs start PROFILE_ID
node tabgecko.mjs request GET /api/v1/profiles/PROFILE_ID/runtime
node tabgecko.mjs stop PROFILE_ID

Native routes are POST /api/v1/profiles/{id}/start with a JSON object and POST /api/v1/profiles/{id}/stop. Both require runtime:control. A start response includes profile_id, session_id, ws_endpoint and kernel information. Use the runtime endpoint to resolve uncertain outcomes. Do not repeatedly start a profile that is already starting. /stop requests a normal shutdown; /kill is a different forceful operation.

POST /api/v1/profiles/{id}/start

{"urls":["https://example.com"]}

Leave proxy checks enabled. The optional skip_proxy_check flag deliberately changes that behavior and should not be used to hide a failed proxy test. Debugging endpoints belong to the local running session; do not publish them.

Update only intended fields

PATCH /api/v1/profiles/{id}

{"notes":"Updated documentation example"}

Read the profile first, patch only changed fields, then read it back. An omitted field and explicit null are not interchangeable. Do not copy an entire read response into PATCH: it contains generated fields. Batch operations have their own schemas and per-item results. Deleting profiles, clearing storage and regenerating fingerprints are separate mutations, not prerequisites for ordinary start/stop.