WebSocket Connection
Connect to ws://127.0.0.1:8080/ws for real-time browser control and events.
Connection Flow
- Connect to the WebSocket endpoint
- Receive welcome message from server
- Send authentication message with your API key
- Receive authentication confirmation
- Subscribe to events and send commands
Welcome Message (Server → Client)JSON
{
"type": "welcome",
"message": "MetaDock WebSocket API - Authentication required",
"version": "1.0"
}WebSocket Authentication
Authentication RequestJSON
{
"type": "auth",
"api_key": "your-api-key-here",
"client_id": "optional-client-identifier",
"id": 1
}import asyncio
import websockets
import json
async def connect():
async with websockets.connect("ws://127.0.0.1:8080/ws") as ws:
# Receive welcome
welcome = await ws.recv()
print(f"Server: {welcome}")
# Authenticate
await ws.send(json.dumps({
"type": "auth",
"api_key": "your-api-key",
"id": 1
}))
auth_response = await ws.recv()
print(f"Auth response: {auth_response}")
# Now ready to send commands
await ws.send(json.dumps({
"type": "browser",
"action": "get_all_browsers",
"id": 2
}))
response = await ws.recv()
print(f"Browsers: {response}")
asyncio.run(connect())Heartbeat
- Server sends keepalive every 30 seconds
- Connection times out after 60 seconds of inactivity
- Standard WebSocket ping/pong is supported
WebSocket Browser Actions
Send browser commands via WebSocket. All actions use this format:
JSON
{
"type": "browser",
"action": "action_name",
"browser_uuid": "uuid-here", // Required for most actions
"params": { ... }, // Action-specific parameters
"id": 1 // Request ID for matching responses
}Actions Without Browser UUID
create_browser — params: url, layout_uuid, profilecreate_multiple — params: browsers (array)create_from_urls — params: urls, layout_uuidget_all_browsers — no paramsexecute_all — params: scriptnavigate_all — params: urlreload_all — no paramsclose_all — no paramsActions Requiring Browser UUID
navigatego_backgo_forwardreloadstopget_urlget_titleget_browser_stateexecute_jsclicktype_textset_valueclear_inputsubmit_formscroll_toscroll_bytake_screenshotprint_pdfset_cookieget_cookieclear_cookiesset_user_agentset_viewportset_zoomclose_browserWebSocket Layout Actions
JSON
{
"type": "layout",
"action": "action_name",
"layout_uuid": "uuid-here",
"params": { ... },
"id": 1
}Available Layout Actions
get_browsers — Get all browsers in the layoutrename — params: nameWebSocket Subscriptions
Subscribe to real-time events from browsers, layouts, or the system.
Subscribe RequestJSON
{
"type": "subscribe",
"target": "browser:uuid-here",
"subscribe": true,
"id": 1
}Subscription Targets
browser:{uuid} — Events for a specific browserlayout:{uuid} — Events for a specific layoutsystem — System-wide eventsWebSocket Events
Events are pushed from the server when subscribed.
Event FormatJSON
{
"type": "browser_event",
"browser_uuid": "uuid-here",
"event": "navigation_completed",
"data": {
"url": "https://example.com",
"success": true,
"timestamp": "2025-01-04T12:00:00Z"
},
"timestamp": "2025-01-04T12:00:00Z"
}Browser Events
navigation_startingFired when navigation begins. Data: url, timestamp
navigation_completedFired when navigation finishes. Data: url, success, timestamp
title_changedFired when page title updates. Data: title, url, timestamp
source_changedFired when URL changes. Data: url, timestamp
download_startingFired when a download begins. Data: url, filename, profile, timestamp
zoom_changedFired when zoom level changes. Data: zoom_factor, zoom_percent, timestamp
audio_state_changedFired when audio state changes. Data: is_playing_audio, is_muted, url, timestamp