GekkoLogin
ВойтиРегистрация

API reference v2

Документация локального API

GekkoLogin предоставляет аутентифицированный локальный HTTP API поверх нативного управления браузером, со структурированным состоянием страницы без remote debugging port.

Локальная связьRESTful JSONНативное управление страницей

Base URL и порт

После запуска desktop client локальный API по умолчанию слушает следующий адрес.

BASE URL
http://127.0.0.1:47891
Локальный API доступен только когда desktop client запущен и local API включен.

Аутентификация

Передавайте API key в header Authorization и храните ключ приватно.

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

Статус сервиса

Проверяйте готовность сервиса перед бизнес-запросами.

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

Пример скрипта

Получите список профилей и семантическое состояние страницы через локальный API.

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"])

Коды ошибок

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.