GekkoLogin
Đăng nhậpĐăng ký

API reference v2

Tai lieu API cuc bo

GekkoLogin cung cap API HTTP cuc bo co xac thuc tren lop dieu khien trinh duyet native, voi trang thai trang co cau truc ma khong can remote debugging port.

Ket noi cuc boRESTful JSONDieu khien trang native

Base URL va cong

Sau khi desktop client khoi dong, API cuc bo mac dinh lang nghe dia chi sau.

BASE URL
http://127.0.0.1:47891
API cuc bo chi hoat dong khi desktop client dang chay va quyen truy cap local API duoc bat.

Xac thuc

Gui API key trong header Authorization va giu khoa nay rieng tu.

HTTP HEADER
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Trang thai dich vu

Kiem tra dich vu san sang truoc cac request nghiep vu.

GET/health
Response, 200
{ "ok": true, "status": { "running": true, "host": "127.0.0.1", "port": 47891 } }

MCP

Standard MCP integration

The Desktop Agent serves stateful Streamable HTTP at /mcp. Sessions, permissions, audit, and all 18 tools are driven by the same automation contract. REST operations use /v2 exclusively.

Streamable HTTP
{
  "mcpServers": {
    "gekkologin-local": {
      "url": "http://127.0.0.1:47891/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_LOCAL_TOKEN"
      }
    }
  }
}
stdio bridge
{
  "mcpServers": {
    "gekkologin-local": {
      "command": "<path-to-gekkologin-executable>",
      "args": ["--mcp-stdio"]
    }
  }
}
GET/v2/profiles

List profiles

List local browser profile summaries and runtime status.

Path parameters

FieldTypeDescription
Response, 200
{
  "ok": true,
  "operationId": "profiles.list",
  "requestId": "<request-id>",
  "data": {
    "profiles": []
  }
}
POST/v2/profiles

Create profile

Create a new local browser environment; the server allocates its hardware template and fingerprint seed. Each environment gets its own seed, so its canvas/text-render fingerprint differs from every other environment on the same hardware. Returns the new profile id, which profiles_launch then opens.

Request fields

FieldTypeDescription
name*stringRequired.
accountPlatformstringOptional.
notesstringOptional.
tagsarrayOptional.
osstringOptional.
templateIdstringOptional.
proxyobjectOptional.
Request body
{
  "name": "<name>"
}
Response, 200
{
  "ok": true,
  "operationId": "profiles.create",
  "requestId": "<request-id>",
  "data": {
    "profileId": "<profileId>",
    "name": "<name>"
  }
}
POST/v2/profiles/{profileId}/launch

Launch profile

Launch a browser profile and optionally navigate its active tab.

Request fields

FieldTypeDescription
profileId*stringRequired.
startUrlstringOptional.
Request body
{
  "startUrl": "<startUrl>"
}
Response, 200
{
  "ok": true,
  "operationId": "profiles.launch",
  "requestId": "<request-id>",
  "data": {
    "ok": false,
    "pid": 1,
    "error": "<error>"
  }
}
POST/v2/profiles/{profileId}/stop

Stop profile

Stop a running browser profile and release its local control session.

Request fields

FieldTypeDescription
profileId*stringRequired.
Response, 200
{
  "ok": true,
  "operationId": "profiles.stop",
  "requestId": "<request-id>",
  "data": {
    "ok": false,
    "error": "<error>"
  }
}
GET/v2/profiles/{profileId}/environment-state/device

Get environment-state device status

Registers this device public key if needed and returns its non-secret pairing status for an environment.

Path parameters

FieldTypeDescription
profileId*stringRequired.
Response, 200
{
  "ok": true,
  "operationId": "environmentState.device.status",
  "requestId": "<request-id>",
  "data": {
    "deviceId": "<deviceId>",
    "keyRegistered": true,
    "approved": false,
    "revision": 1,
    "checkpointAvailable": false
  }
}
POST/v2/profiles/{profileId}/environment-state/checkpoint/retry

Retry environment state upload

Retry a durable encrypted environment checkpoint after a previous upload failure without rebuilding browser state.

Request fields

FieldTypeDescription
profileId*stringRequired.
Response, 200
{
  "ok": true,
  "operationId": "environmentState.checkpoint.retry",
  "requestId": "<request-id>",
  "data": {
    "ok": true,
    "profileId": "<profileId>",
    "revision": 1
  }
}
GET/v2/automation/agents

List automation agents

List saved RPA automation agent definitions.

Path parameters

FieldTypeDescription
Response, 200
{
  "ok": true,
  "operationId": "automation.agents.list",
  "requestId": "<request-id>",
  "data": {
    "agents": []
  }
}
POST/v2/automation/run

Run automation agent

Run a saved RPA agent against a local browser profile.

Request fields

FieldTypeDescription
agentId*stringRequired.
profileId*stringRequired.
Request body
{
  "agentId": "<agentId>",
  "profileId": "<profileId>"
}
Response, 200
{
  "ok": true,
  "operationId": "automation.run",
  "requestId": "<request-id>",
  "data": {
    "ok": false,
    "runId": "<runId>",
    "steps": [],
    "error": "<error>"
  }
}
GET/v2/profiles/{profileId}/tabs

List browser tabs

Return browser windows and tabs from the native control plane.

Path parameters

FieldTypeDescription
profileId*stringRequired.
Response, 200
{
  "ok": true,
  "operationId": "browser.tabs.list",
  "requestId": "<request-id>",
  "data": {
    "browsers": []
  }
}
POST/v2/profiles/{profileId}/page/navigate

Navigate page

Navigate a selected or active tab through native browser control.

Request fields

FieldTypeDescription
profileId*stringRequired.
tabIdstringOptional.
url*stringRequired.
Request body
{
  "url": "<url>"
}
Response, 200
{
  "ok": true,
  "operationId": "page.navigate",
  "requestId": "<request-id>",
  "data": {
    "tabId": "<tabId>"
  }
}
POST/v2/profiles/{profileId}/page/snapshot

Get semantic page snapshot

Return structured semantic page state with opaque node references and sensitive values redacted.

Request fields

FieldTypeDescription
profileId*stringRequired.
tabIdstringOptional.
maxNodesintegerOptional.
Request body
{
  "maxNodes": 1
}
Response, 200
{
  "ok": true,
  "operationId": "page.snapshot",
  "requestId": "<request-id>",
  "data": {
    "snapshotId": "<snapshotId>",
    "url": "<url>",
    "title": "<title>",
    "nodes": [],
    "nodeCount": 1,
    "truncated": false
  }
}
POST/v2/profiles/{profileId}/page/screenshot

Capture page screenshot

Capture the selected or active tab as a PNG without enabling remote debugging.

Request fields

FieldTypeDescription
profileId*stringRequired.
tabIdstringOptional.
maxDimensionintegerOptional.
Request body
{
  "maxDimension": 1
}
Response, 200
{
  "ok": true,
  "operationId": "page.screenshot",
  "requestId": "<request-id>",
  "data": {
    "mimeType": "image/png",
    "width": 1,
    "height": 1,
    "data": "<data>"
  }
}
POST/v2/profiles/{profileId}/page/query

Query page element

Resolve a CSS selector and return element interaction state without executing page script.

Request fields

FieldTypeDescription
profileId*stringRequired.
tabIdstringOptional.
selector*stringRequired.
Request body
{
  "selector": "<selector>"
}
Response, 200
{
  "ok": true,
  "operationId": "page.query",
  "requestId": "<request-id>",
  "data": {
    "found": false,
    "visible": false,
    "editable": false,
    "tagName": "<tagName>"
  }
}
POST/v2/profiles/{profileId}/page/click

Click page element

Click an element by CSS selector or semantic snapshot node reference.

Request fields

FieldTypeDescription
profileId*stringRequired.
tabIdstringOptional.
selectorstringOptional.
snapshotIdstringOptional.
nodeRefstringOptional.
Request body
{
  "selector": "<selector>"
}
Response, 200
{
  "ok": true,
  "operationId": "page.click",
  "requestId": "<request-id>",
  "data": {
    "ok": false,
    "message": "<message>"
  }
}
POST/v2/profiles/{profileId}/page/type

Type into page element

Type text into an editable element using native actor actions.

Request fields

FieldTypeDescription
profileId*stringRequired.
tabIdstringOptional.
selectorstringOptional.
snapshotIdstringOptional.
nodeRefstringOptional.
text*stringRequired.
modereplace | prepend | appendOptional.
pressEnterbooleanOptional.
Request body
{
  "selector": "<selector>",
  "text": "<text>"
}
Response, 200
{
  "ok": true,
  "operationId": "page.type",
  "requestId": "<request-id>",
  "data": {
    "ok": false,
    "message": "<message>"
  }
}
POST/v2/profiles/{profileId}/page/select

Select page option

Select an option from a page control by selector or semantic node reference.

Request fields

FieldTypeDescription
profileId*stringRequired.
tabIdstringOptional.
selectorstringOptional.
snapshotIdstringOptional.
nodeRefstringOptional.
value*stringRequired.
Request body
{
  "selector": "<selector>",
  "value": "<value>"
}
Response, 200
{
  "ok": true,
  "operationId": "page.select",
  "requestId": "<request-id>",
  "data": {
    "ok": false,
    "message": "<message>"
  }
}
POST/v2/profiles/{profileId}/page/scroll

Scroll page

Scroll the page or an element by a deterministic distance.

Request fields

FieldTypeDescription
profileId*stringRequired.
tabIdstringOptional.
selectorstringOptional.
direction*up | down | left | rightRequired.
distance*numberRequired.
Request body
{
  "selector": "<selector>",
  "direction": "up",
  "distance": 1
}
Response, 200
{
  "ok": true,
  "operationId": "page.scroll",
  "requestId": "<request-id>",
  "data": {
    "ok": false,
    "message": "<message>"
  }
}
POST/v2/profiles/{profileId}/page/scroll-to

Scroll element into view

Scroll a selected semantic node or CSS selector into view.

Request fields

FieldTypeDescription
profileId*stringRequired.
tabIdstringOptional.
selectorstringOptional.
snapshotIdstringOptional.
nodeRefstringOptional.
Request body
{
  "selector": "<selector>"
}
Response, 200
{
  "ok": true,
  "operationId": "page.scrollTo",
  "requestId": "<request-id>",
  "data": {
    "ok": false,
    "message": "<message>"
  }
}

Appendix

Vi du script

Liet ke ho so va doc trang thai ngu nghia cua trang qua API cuc bo.

Python, requests
import requests

base = "http://127.0.0.1:47891"
headers = {"Authorization": "Bearer YOUR_LOCAL_TOKEN"}

profiles = requests.get(f"{base}/v2/profiles", headers=headers).json()
profile_id = profiles["data"]["profiles"][0]["id"]

snapshot = requests.post(
    f"{base}/v2/profiles/{profile_id}/page/snapshot",
    headers=headers,
    json={"maxNodes": 1000},
).json()

print(snapshot["data"]["url"], snapshot["data"]["nodeCount"])

Ma loi

Errors use a stable machine-readable code and include requestId for audit correlation.

CodeDescriptionAction
400 / invalid_requestThe input does not match the operation contract.Fix the fields reported in error.message.
401 / unauthorizedThe bearer token is missing or invalid.Use the current local token from the desktop client.
403 / forbiddenThe token lacks the operation permission.Grant the permission or use an authorized token.
404 / operation_not_foundThe route or operation is not available.Check the generated OpenAPI contract and Desktop Agent version.
500 / operation_failedThe native operation failed.Use requestId to correlate the desktop audit log.
Prefer no code?Try visual RPA

Build repeated browser workflows with a visual automation layer.

Need help?Visit the help center

Read setup guides, troubleshooting notes, and rollout guidance.