WebSocket API v1

Endpoints:

ws://127.0.0.1:25548/api/v1/ws
wss://<remote-endpoint>/api/v1/ws

Protocol version v=1. All communication occurs over JSON text frames.

Protocol Envelopes

Request

{
  "v": 1,
  "type": "request",
  "id": "req-001",
  "method": "instances.list",
  "params": {}
}

Field	Constraint
v	Must equal 1
type	request
id	1–100 characters; must be unique within the active session
method	Registered method name
params	Strictly validated parameter object

Successful Response

{ "v": 1, "type": "response", "id": "req-001", "ok": true, "result": [] }

Error Response

{
  "v": 1,
  "type": "response",
  "id": "req-001",
  "ok": false,
  "error": { "code": "INVALID_PARAMS", "message": "Invalid request parameters", "details": [] }
}

Event Broadcast

{ "v": 1, "type": "event", "topic": "overview", "data": {} }

Session Lifecycle

Upon connection, the server pushes an initial session descriptor:

{
  "v": 1,
  "type": "event",
  "topic": "session",
  "data": { "authRequired": true, "protocolVersion": 1 }
}

• authRequired: false indicates connection over loopback without a configured password; calls are permitted immediately.
• Unauthenticated sessions time out after 30 seconds; authenticated sessions time out after 60 seconds of silence.

Authentication

{
  "v": 1, "type": "request", "id": "a1", "method": "auth.login",
  "params": { "password": "<WebUI Password>" }
}

Remote pairing clients supply pairing tokens instead of the master password. Revoked tokens immediately return UNAUTHORIZED on subsequent calls or 15s heartbeats.

Subscriptions

{
  "v": 1, "type": "request", "id": "s1", "method": "events.subscribe",
  "params": { "instance": "ap", "topics": ["overview", "logs", "statistics"] }
}

Topic	Data Streamed	Sampling Cadence
instances	Instance lists and status	2 seconds
overview	Active tasks and resources	1 second
logs	Incremental log streams	On write
preview	Live screen capture	On write
statistics	Aggregated telemetry	1 second
notifications	System notification alerts	Event-driven
stock	Stock exchange ledger	Event-driven

Subscriptions Follow Replacement Semantics

Subscribing replaces all existing topics for that session. The Android host enforces a single global subscriber; custom integrations must avoid conflicting subscriptions with active frontends.

Rate Limits & Error Codes

Property	Constraint
Message Size Cap	≤ 8 MiB
Standard Request Cap	≤ 1 MiB
Request Cap Exemptions	mind.import, mind.recognize, mind.save, mind.calculate
Request Rate Limit	30 requests per second

Error Code	Meaning
INVALID_REQUEST	Corrupted envelope or size limit exceeded
INVALID_PARAMS	Parameter validation failure
UNAUTHORIZED	Missing authentication or revoked token
TLS_REQUIRED	Remote account operation attempted over unencrypted connection
RATE_LIMITED	Request limit exceeded
DUPLICATE_REQUEST	Request ID reused
INTERNAL_ERROR	Internal unhandled server exception

Validation errors report property paths and expected types only, scrubbing input values to prevent credential leakage.

Common Workflows

List Instances & Fetch Overview

{"v":1,"type":"request","id":"1","method":"instances.list","params":{}}
{"v":1,"type":"request","id":"2","method":"overview.get","params":{"instance":"ap"}}

Start & Stop Schedulers

{"v":1,"type":"request","id":"3","method":"scheduler.start","params":{"instance":"ap"}}
{"v":1,"type":"request","id":"4","method":"scheduler.stop","params":{"instance":"ap"}}

Modify Configuration

{
  "v": 1, "type": "request", "id": "5", "method": "config.patch",
  "params": {
    "instance": "ap",
    "revision": "<revision-from-last-read>",
    "changes": [{ "path": "Research.Scheduler.Enable", "value": true }]
  }
}

Trigger Immediate Task

{"v":1,"type":"request","id":"6","method":"tasks.run","params":{"instance":"ap","task":"Research"}}

Stream Logs

{"v":1,"type":"request","id":"7","method":"logs.get","params":{"instance":"ap","after":128}}

Method Catalog

The interactive table below is generated from contract.json. Expand rows to view parameter schemas and constraints:

72 / 72 个方法 · 契约版本 1 · 7de6bb9

Client Implementation Guidelines

1. Wait for the session handshake event before issuing authentication calls.
2. Use monotonically increasing integers or UUIDs for request IDs.
3. Reconnect with exponential backoff and re-subscribe following disconnections.
4. Issue an initial overview.get call before subscribing to event topics.
5. Verify mutation results by reading back state rather than assuming success.
6. Avoid appending credentials to query parameters.