Browser Creation
Create browser instances in MetaDock. Each browser appears in the visual grid and can be controlled via any API.
POST
/api/browsers/createCreate a single browser instance with specified configuration.
Parameters
url(string)required— Initial URL to navigate tolayout_uuid(string)required— UUID of the layout to create browser inprofile(string)— Browser profile name (default: 'default')proxy(string)— Proxy URL (http://host:port or socks5://host:port)customTitle(string)— Custom title for the browser tabmute(boolean)— Mute audio (default: false)lock(boolean)— Lock browser position (default: false)toolbarVisible(boolean)— Show toolbar (default: true)disableJavascript(boolean)— Disable JavaScript (default: false)zoomFactor(number)— Zoom factor (1.0 = 100%)autoRefreshInterval(number)— Auto-refresh interval in secondshide(boolean)— Start hidden (default: false)Returns
Browser object with uuid, url, title
import requests
response = requests.post(
"http://127.0.0.1:8080/api/browsers/create",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"url": "https://example.com",
"layout_uuid": "layout-abc-123",
"profile": "default",
"proxy": "http://proxy.example.com:8080",
"mute": True,
"zoomFactor": 1.25
}
)
browser = response.json()
print(f"Created browser: {browser['data']['uuid']}")POST
/api/browsers/create-multipleCreate multiple browsers with different configurations in a single request.
Parameters
browsers(array)required— Array of browser configuration objects (same params as /create)Returns
Array of created browser objects
response = requests.post(
"http://127.0.0.1:8080/api/browsers/create-multiple",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"browsers": [
{"url": "https://google.com", "layout_uuid": "layout-123", "profile": "work"},
{"url": "https://github.com", "layout_uuid": "layout-123", "profile": "personal"},
{"url": "https://twitter.com", "layout_uuid": "layout-123", "profile": "social"}
]
}
)
browsers = response.json()["data"]["browsers"]
print(f"Created {len(browsers)} browsers")POST
/api/browsers/create-from-urlsCreate multiple browsers from a list of URLs, all sharing the same profile and layout.
Parameters
urls(string[])required— Array of URLs to openlayout_uuid(string)required— Layout UUID for all browsersprofile(string)— Profile name for all browsersproxy(string)— Proxy for all browsersReturns
Array of created browser objects
response = requests.post(
"http://127.0.0.1:8080/api/browsers/create-from-urls",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"urls": [
"https://google.com",
"https://github.com",
"https://stackoverflow.com",
"https://reddit.com",
"https://news.ycombinator.com"
],
"layout_uuid": "layout-abc-123",
"profile": "default"
}
)
print(f"Created {len(response.json()['data']['browsers'])} browsers")POST
/api/browsers/create-with-profilesCreate browsers with specific profile assignments for each URL.
Parameters
urls(string[])required— Array of URLs (same length as profiles)profiles(string[])required— Array of profile names (matched by index)layout_uuid(string)required— Layout UUID for all browsersproxy(string)— Proxy for all browsersReturns
Array of created browser objects
Browser Navigation
Control browser navigation — go to URLs, navigate history, reload pages.
POST
/api/browsers/{uuid}/navigateNavigate a browser to a new URL.
Parameters
uuid(string)required— Browser UUID (path parameter)url(string)required— URL to navigate torequests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/navigate",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"url": "https://example.com/page"}
)GET
/api/browsers/{uuid}/urlGet the current URL of a browser.
Parameters
uuid(string)required— Browser UUID (path parameter)Returns
{ url: string }
response = requests.get(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/url",
headers={"Authorization": f"Bearer {API_KEY}"}
)
print(f"Current URL: {response.json()['data']['url']}")POST
/api/browsers/{uuid}/backNavigate the browser back in history.
Parameters
uuid(string)required— Browser UUID (path parameter)POST
/api/browsers/{uuid}/forwardNavigate the browser forward in history.
Parameters
uuid(string)required— Browser UUID (path parameter)POST
/api/browsers/{uuid}/reloadReload the current page.
Parameters
uuid(string)required— Browser UUID (path parameter)POST
/api/browsers/{uuid}/stopStop loading the current page.
Parameters
uuid(string)required— Browser UUID (path parameter)POST
/api/browsers/navigate-allNavigate all browsers to the same URL.
Parameters
url(string)required— URL to navigate all browsers toPOST
/api/browsers/reload-allReload all browsers.
Browser Information
Get information about browsers — URLs, titles, page source, state.
GET
/api/browsersGet a list of all active browsers.
Returns
Array of browser objects with uuid, url, title
response = requests.get(
"http://127.0.0.1:8080/api/browsers",
headers={"Authorization": f"Bearer {API_KEY}"}
)
browsers = response.json()["data"]["browsers"]
for browser in browsers:
print(f"{browser['uuid']}: {browser['title']} - {browser['url']}")GET
/api/browsers/{uuid}/titleGet the page title of a browser.
Parameters
uuid(string)required— Browser UUID (path parameter)Returns
{ title: string }
GET
/api/browsers/{uuid}/sourceGet the HTML source of the current page. Returns a UUID for async retrieval.
Parameters
uuid(string)required— Browser UUID (path parameter)Returns
{ source_uuid: string, source_url: string }
# Request page source
response = requests.get(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/source",
headers={"Authorization": f"Bearer {API_KEY}"}
)
source_uuid = response.json()["data"]["source_uuid"]
# Retrieve the source
source_response = requests.get(
f"http://127.0.0.1:8080/api/sources/{source_uuid}",
headers={"Authorization": f"Bearer {API_KEY}"}
)
html = source_response.textGET
/api/browsers/{uuid}/stateGet comprehensive state information for a browser.
Parameters
uuid(string)required— Browser UUID (path parameter)Returns
{ url, title, canGoBack, canGoForward, isLoading, zoom }
response = requests.get(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/state",
headers={"Authorization": f"Bearer {API_KEY}"}
)
state = response.json()["data"]
print(f"URL: {state['url']}")
print(f"Title: {state['title']}")
print(f"Loading: {state['isLoading']}")
print(f"Zoom: {state['zoom']}%")Browser Management
Close browsers individually or in bulk.
POST
/api/browsers/{uuid}/closeClose a specific browser.
Parameters
uuid(string)required— Browser UUID (path parameter)POST
/api/browsers/close-allClose all browsers.
POST
/api/browsers/close-othersClose all browsers except one.
Parameters
keepBrowserUuid(string)required— UUID of browser to keep openPOST
/api/browsers/close-others-in-layoutClose all browsers in a layout except one.
Parameters
layout_uuid(string)required— Layout UUIDkeepBrowserUuid(string)required— UUID of browser to keep openJavaScript Execution
Execute JavaScript code in browser contexts.
POST
/api/browsers/{uuid}/executeExecute JavaScript code in a browser and return the result.
Parameters
uuid(string)required— Browser UUID (path parameter)script(string)required— JavaScript code to executeReturns
Result of the JavaScript execution
# Count all links on the page
response = requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/execute",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"script": "document.querySelectorAll('a').length"}
)
print(f"Found {response.json()['data']['result']} links")
# Get page title via JS
response = requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/execute",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"script": "document.title"}
)
# Extract text from an element
response = requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/execute",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"script": "document.querySelector('h1')?.textContent"}
)POST
/api/browsers/execute-allExecute JavaScript code on all browsers.
Parameters
script(string)required— JavaScript code to executeReturns
Results from all browsers
# Get titles from all browsers
response = requests.post(
"http://127.0.0.1:8080/api/browsers/execute-all",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"script": "document.title"}
)
for result in response.json()["data"]["results"]:
print(f"{result['uuid']}: {result['result']}")Page Interaction
Click elements, type text, submit forms, and scroll pages.
POST
/api/browsers/{uuid}/clickClick an element by CSS selector.
Parameters
uuid(string)required— Browser UUID (path parameter)selector(string)required— CSS selector of element to clicktimeout_ms(number)— Timeout in milliseconds (default: 5000)# Click a button by ID
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/click",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"selector": "#submit-button", "timeout_ms": 10000}
)
# Click a link by class
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/click",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"selector": ".nav-link.active"}
)
# Click the first result in a list
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/click",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"selector": ".search-results li:first-child a"}
)POST
/api/browsers/{uuid}/typeType text at the current cursor position or into a specified element.
Parameters
uuid(string)required— Browser UUID (path parameter)text(string)required— Text to typeselector(string)— CSS selector (optional, types at cursor if omitted)# Type into a search box
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/type",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"text": "metadock browser automation",
"selector": "input[name='q']"
}
)POST
/api/browsers/{uuid}/set-valueSet the value of an input element directly (faster than typing).
Parameters
uuid(string)required— Browser UUID (path parameter)selector(string)required— CSS selector of input elementvalue(string)required— Value to settimeout_ms(number)— Timeout in milliseconds (default: 5000)# Fill a form quickly
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/set-value",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"selector": "input[name='email']", "value": "[email protected]"}
)
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/set-value",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"selector": "input[name='password']", "value": "secretpassword"}
)POST
/api/browsers/{uuid}/clearClear an input field.
Parameters
uuid(string)required— Browser UUID (path parameter)selector(string)required— CSS selector of input elementtimeout_ms(number)— Timeout in milliseconds (default: 5000)POST
/api/browsers/{uuid}/submitSubmit a form.
Parameters
uuid(string)required— Browser UUID (path parameter)selector(string)required— CSS selector of form elementtimeout_ms(number)— Timeout in milliseconds (default: 5000)POST
/api/browsers/{uuid}/scroll-toScroll to absolute coordinates.
Parameters
uuid(string)required— Browser UUID (path parameter)x(number)required— X coordinatey(number)required— Y coordinate# Scroll to top
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/scroll-to",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"x": 0, "y": 0}
)
# Scroll down 500 pixels from top
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/scroll-to",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"x": 0, "y": 500}
)POST
/api/browsers/{uuid}/scroll-byScroll by relative offset.
Parameters
uuid(string)required— Browser UUID (path parameter)x(number)required— X offsety(number)required— Y offsetScreenshots & PDF
Capture page content as screenshots or PDF documents.
POST
/api/browsers/{uuid}/screenshotTake a screenshot of the browser viewport. Returns base64-encoded PNG.
Parameters
uuid(string)required— Browser UUID (path parameter)timeout_ms(number)— Timeout in milliseconds (default: 5000)Returns
{ screenshot: string (base64 PNG) }
import base64
response = requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/screenshot",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"timeout_ms": 10000}
)
screenshot_b64 = response.json()["data"]["screenshot"]
with open("screenshot.png", "wb") as f:
f.write(base64.b64decode(screenshot_b64))
print("Screenshot saved to screenshot.png")POST
/api/browsers/{uuid}/pdfPrint the current page to a PDF file.
Parameters
uuid(string)required— Browser UUID (path parameter)filePath(string)required— Absolute file path to save PDF (Windows path)requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/pdf",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"filePath": "C:/Users/me/Documents/page.pdf"}
)
print("PDF saved")GET
/api/screenshots/{uuid}Retrieve a previously taken screenshot by its UUID.
Parameters
uuid(string)required— Screenshot UUID (path parameter)Returns
PNG image binary
GET
/api/sources/{uuid}Retrieve page source HTML by its UUID.
Parameters
uuid(string)required— Source UUID (path parameter)Returns
HTML text
Cookie Management
Set, get, and clear cookies for browser sessions.
POST
/api/browsers/{uuid}/cookieSet a cookie for the browser.
Parameters
uuid(string)required— Browser UUID (path parameter)name(string)required— Cookie namevalue(string)required— Cookie valuedomain(string)— Cookie domain (optional)requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/cookie",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"name": "session_id",
"value": "abc123xyz",
"domain": ".example.com"
}
)GET
/api/browsers/{uuid}/cookieGet a cookie value by name.
Parameters
uuid(string)required— Browser UUID (path parameter)name(string)required— Cookie name (query parameter)Returns
{ name: string, value: string }
POST
/api/browsers/{uuid}/cookies/clearClear all cookies for the browser.
Parameters
uuid(string)required— Browser UUID (path parameter)Browser Settings
Configure browser settings like user agent, viewport, and zoom.
POST
/api/browsers/{uuid}/user-agentSet the User-Agent string for a browser.
Parameters
uuid(string)required— Browser UUID (path parameter)userAgent(string)required— User-Agent string# Emulate mobile browser
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/user-agent",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15"
}
)POST
/api/browsers/{uuid}/viewportSet the viewport size for a browser.
Parameters
uuid(string)required— Browser UUID (path parameter)width(number)required— Viewport width in pixelsheight(number)required— Viewport height in pixels# Set mobile viewport
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/viewport",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"width": 375, "height": 812} # iPhone X
)
# Set desktop viewport
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/viewport",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"width": 1920, "height": 1080}
)POST
/api/browsers/{uuid}/zoomSet the zoom level for a browser.
Parameters
uuid(string)required— Browser UUID (path parameter)zoom(number)required— Zoom factor (1.0 = 100%)GET
/api/browsers/{uuid}/zoomGet the current zoom level.
Parameters
uuid(string)required— Browser UUID (path parameter)Returns
{ zoom: number }
Developer Tools
Control DevTools and access console messages.
POST
/api/browsers/{uuid}/devtools/enableEnable or disable DevTools for a browser.
Parameters
uuid(string)required— Browser UUID (path parameter)enable(boolean)required— Enable (true) or disable (false)POST
/api/browsers/{uuid}/devtools/openOpen the DevTools panel.
Parameters
uuid(string)required— Browser UUID (path parameter)POST
/api/browsers/{uuid}/devtools/closeClose the DevTools panel.
Parameters
uuid(string)required— Browser UUID (path parameter)GET
/api/browsers/{uuid}/consoleGet console messages from the browser.
Parameters
uuid(string)required— Browser UUID (path parameter)Returns
Array of console message objects
POST
/api/browsers/{uuid}/console/clearClear console messages.
Parameters
uuid(string)required— Browser UUID (path parameter)Device Emulation
Emulate devices, geolocation, and network conditions.
POST
/api/browsers/{uuid}/geolocationSet geolocation coordinates for a browser.
Parameters
uuid(string)required— Browser UUID (path parameter)latitude(number)required— Latitude (-90 to 90)longitude(number)required— Longitude (-180 to 180)accuracy(number)— Accuracy in meters (optional)# Set location to New York
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/geolocation",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"latitude": 40.7128,
"longitude": -74.0060,
"accuracy": 100
}
)POST
/api/browsers/{uuid}/geolocation/clearClear geolocation override.
Parameters
uuid(string)required— Browser UUID (path parameter)POST
/api/browsers/{uuid}/deviceEmulate a specific device.
Parameters
uuid(string)required— Browser UUID (path parameter)device(string)required— Device name (e.g., 'iPhone 12', 'Pixel 5')POST
/api/browsers/{uuid}/device/clearClear device emulation.
Parameters
uuid(string)required— Browser UUID (path parameter)POST
/api/browsers/{uuid}/offlineSet offline mode for a browser.
Parameters
uuid(string)required— Browser UUID (path parameter)offline(boolean)required— Enable (true) or disable (false) offline modeAdvanced Features
Wait for elements, inject scripts, and other advanced operations.
POST
/api/browsers/{uuid}/wait/elementWait for an element to appear on the page.
Parameters
uuid(string)required— Browser UUID (path parameter)selector(string)required— CSS selector to wait fortimeout(number)required— Timeout in milliseconds# Wait for search results to load
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/wait/element",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"selector": ".search-results",
"timeout": 10000
}
)POST
/api/browsers/{uuid}/wait/loadWait for the page to finish loading.
Parameters
uuid(string)required— Browser UUID (path parameter)timeout(number)— Timeout in milliseconds (default: 30000)POST
/api/browsers/{uuid}/inject/styleInject CSS styles into the page.
Parameters
uuid(string)required— Browser UUID (path parameter)css(string)required— CSS code to inject# Hide ads
requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/inject/style",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"css": ".ad-banner, .sponsored { display: none !important; }"}
)POST
/api/browsers/{uuid}/inject/scriptInject a JavaScript file into the page.
Parameters
uuid(string)required— Browser UUID (path parameter)script(string)required— URL of script to injectBatch Operations
Execute multiple operations in a single request to reduce latency.
POST
/api/browsers/{uuid}/batchExecute a sequence of actions on a browser in a single request.
Parameters
uuid(string)required— Browser UUID (path parameter)actions(array)required— Array of action objectsReturns
Array of results for each action
# Login flow in a single request
response = requests.post(
f"http://127.0.0.1:8080/api/browsers/{browser_uuid}/batch",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"actions": [
{"type": "navigate", "params": {"url": "https://example.com/login"}},
{"type": "click", "params": {"selector": "#email"}},
{"type": "type", "params": {"text": "[email protected]"}},
{"type": "click", "params": {"selector": "#password"}},
{"type": "type", "params": {"text": "mypassword"}},
{"type": "click", "params": {"selector": "#submit"}},
{"type": "take_screenshot", "params": {}}
]
}
)
results = response.json()["data"]["results"]
for i, result in enumerate(results):
print(f"Action {i+1}: {'Success' if result['success'] else result['error']}")Available Batch Action Types
navigate — params: urlclick — params: selector, timeout_mstype — params: text, selectorscroll_to — params: x, yscroll_by — params: x, yreload — no paramsgo_back — no paramsgo_forward — no paramstake_screenshot — no paramsexecute_javascript — params: scriptWorkspaces
Workspaces organize your layouts. Each workspace can contain multiple layouts.
GET
/api/workspacesList all workspaces.
Returns
Array of workspace objects
POST
/api/workspaceCreate a new workspace.
Parameters
name(string)required— Workspace nameDELETE
/api/workspace/{id}Delete a workspace.
Parameters
id(number)required— Workspace IDPUT
/api/workspace/{id}Rename a workspace.
Parameters
id(number)required— Workspace IDname(string)required— New namePOST
/api/workspace/{id}/homepageSet workspace homepage URL.
Parameters
id(number)required— Workspace IDurl(string)required— Homepage URLPOST
/api/workspace/{id}/startupSet workspace as startup workspace.
Parameters
id(number)required— Workspace IDGET
/api/workspace/currentGet the current active workspace.
GET
/api/workspace/startupGet the startup workspace.
POST
/api/workspace/{id}/switchSwitch to a workspace.
Parameters
id(number)required— Workspace IDGET
/api/workspace/{id}Get workspace info.
Parameters
id(number)required— Workspace IDGET
/api/workspace/{id}/layoutsGet layouts in a workspace.
Parameters
id(number)required— Workspace IDLayouts
Layouts are containers for browsers within a workspace. Each layout appears as a tab.
GET
/api/layoutsList all layouts.
Returns
Array of layout objects with uuid, name
POST
/api/layoutCreate a new layout.
Returns
Created layout object with uuid
DELETE
/api/layout/{uuid}Delete a layout.
Parameters
uuid(string)required— Layout UUIDPUT
/api/layout/{uuid}Rename a layout.
Parameters
uuid(string)required— Layout UUIDname(string)required— New nameGET
/api/layout/{uuid}Get layout info.
Parameters
uuid(string)required— Layout UUIDGET
/api/layout/{uuid}/browsersGet browsers in a layout.
Parameters
uuid(string)required— Layout UUIDProfiles
Browser profiles provide isolated sessions with separate cookies, cache, and storage.
GET
/api/profilesList all browser profiles.
Returns
Array of profile objects
GET
/api/profile/defaultGet the default browser profile.
POST
/api/profileCreate a new profile.
Parameters
name(string)required— Profile namePOST
/api/profile/temporaryCreate a temporary profile (deleted on app close).
PUT
/api/profile/{name}Rename a profile.
Parameters
name(string)required— Current profile namenewName(string)required— New profile namePUT
/api/profile/{name}/temporaryRename a temporary profile.
Parameters
name(string)required— Current temp profile namenewName(string)required— New profile nameDELETE
/api/profile/{name}Delete a profile.
Parameters
name(string)required— Profile namePOST
/api/profile/{name}/defaultSet profile as default.
Parameters
name(string)required— Profile name