Automation API

Returns server status, browser version, uptime, and current window/tab counts.

Returns a built-in HTML documentation page. No API key required.

Returns all open tabs across all windows. Optionally filter by window ID.

Returns full details for a specific tab by ID.

Opens a new tab. Optionally specify URL, target window, profile, or private mode.

Closes the specified tab.

Navigates the tab to a new URL.

Reloads the current page in the tab.

Navigate back in history.

Navigate forward in history.

Stops the current page from loading.

Makes this tab the active/selected tab in its window.

Creates a copy of the tab with the same URL.

Toggles the pinned state of the tab.

Toggles the muted state of the tab.

Returns the full HTML source of the current page.

Runs arbitrary JavaScript in the page context and returns the result.

Clicks the first element matching the CSS selector.

Sets the value of an input field using native value setter (compatible with React, Angular, Vue).

Selects an option in a <select> element by value.

Sets the checked state of a checkbox or radio input.

Types text into the focused element with optional per-keystroke delay (simulates real typing).

Waits until an element matching the selector appears in the DOM (uses MutationObserver).

Extracts text content or attribute values from one or more elements.

Scrolls to absolute coordinates or to a specific element.

Looks up saved credentials for the domain and auto-fills the login form.

Captures a screenshot of the visible page and returns it as base64-encoded PNG.

Exports the current page as a PDF document returned as base64.

Returns all cookies for the tab's data store.

Sets one or more cookies in the tab's data store.

Removes all cookies from the tab's data store.

Returns the visible text content of the page (innerText of body).

Programmatically sets files on a <input type="file"> element. Files are provided as base64-encoded data. This triggers the change event as if the user selected files via the native file picker.

Returns all open browser windows.

Returns details for a specific window.

Opens a new browser window, optionally with a specific profile or in private mode. Returns the new window ID and active tab ID.

Brings the window to the foreground and activates the Vela app. In headed mode, makes the window the key window and calls NSApplication.activate(ignoringOtherApps: true). In hidden/headless mode this is a no-op.

Closes the specified browser window and all its tabs. Uses a direct NSWindow reference for reliable closing, and always deregisters the window from the API even if the physical close fails.

Navigate the window's active tab to a URL. Body: { "url": "https://..." }

Reload the current page on the window's active tab.

Navigate back in the active tab's history.

Navigate forward in the active tab's history.

Stop loading the page on the active tab.

Execute JavaScript on the active tab. Body: { "script": "document.title" }

Click an element. Body: { "selector": "button.submit" }

Fill an input field. Body: { "selector": "input[name='email']", "value": "[email protected]" }

Select a dropdown option. Body: { "selector": "select#country", "value": "US" }

Set checkbox state. Body: { "selector": "#agree", "checked": true }

Type text character by character. Body: { "selector": "#search", "text": "hello", "delay": 50 }

Wait for an element to appear. Body: { "selector": ".loaded", "timeout": 10000 }

Extract text or attributes. Body: { "selector": "h1", "attribute": "textContent", "multiple": false }

Scroll by offset or to element. Body: { "y": 500 } or { "selector": "#footer" }

Fill saved credentials. Body: { "domain": "example.com" }

Capture a screenshot of the active tab as base64 PNG.

Export the active tab as a base64-encoded PDF.

Get cookies for the active tab's current domain.

Set cookies. Body: { "cookies": [{ "name": "...", "value": "...", "domain": "..." }] }

Clear all cookies for the active tab's current domain.

Get all visible text content from the active tab.

Upload files to a file input. Body: { "selector": "input[type=file]", "files": [{ "name": "doc.pdf", "data": "base64...", "type": "application/pdf" }] }

Move mouse cursor with easing on the active tab. Body: { "x": 500, "y": 300 } or { "selector": "#btn" } + optional "duration", "steps", "easing" (ease|linear|human).

Full click sequence on active tab. Body: { "selector": "#btn" } + optional "button" (left|right|middle), "doubleClick".

Dispatches pointerdown + mousedown on the active tab.

Dispatches pointerup + mouseup on the active tab.

Human-like random mouse movement on the active tab. Body: { "duration": 3000 } + optional "area", "speed".

Move along waypoints on the active tab. Body: { "points": [{"x":100,"y":100}, ...], "duration": 1000 }

Returns all browser profiles with their configuration.

Returns full details for a specific profile.

Creates a new browser profile with isolated cookies, storage, and fingerprint. Accepts ALL profile settings on creation.

Partially update any profile field (name, icon, color, UA, fingerprint, proxy, DNS, privacy settings).

Deletes a profile. Cannot delete the default profile.

Switches a window to use this profile.

Creates a copy of the profile with a new fingerprint seed.

Generates a new random fingerprint seed for the profile.

Returns all available user agent presets organized by category (Desktop, Mobile, Bots, etc.).

Returns the currently active global user agent.

Returns the fingerprint configuration for a specific profile.

Generates a new random fingerprint seed for the profile.

Returns all vela_* UserDefaults settings as key-value pairs.

Returns the value for a single setting key.

Returns all bookmarks. Optionally filter by folder.

Update a bookmark's title, URL, or folder.

Removes a bookmark.

Returns all bookmark folders.

Removes a bookmark folder.

Returns the most frequently visited sites.

Permanently deletes all browsing history.

Removes a single history entry by ID.

Returns details for a single download including progress, state, and byte counts.

Starts downloading a file from the given URL.

Pauses an in-progress download. The download can be resumed later with the resume endpoint.

Resumes a paused download from where it left off.

Cancels an in-progress download or removes a completed one.

Lists all saved credentials. Passwords are not included in the response for security.

Returns the full credential including password. Requires the X-Password-Access: true header for additional security.

Returns autofill and save-password settings for a specific profile. null values mean the profile uses the global setting.

Enable or disable autofill and save-password prompts for a specific profile. Pass resetToGlobal: true to clear overrides and inherit global settings.

Note: extraBlockTrackers enables 80+ additional tracker domains. extraBlockAds enables 60+ additional ad networks. Both are off by default. automaticCookieConsent handles cookie consent dialogs on supported sites.

Returns all session cookies stored in the profile configuration.

Replaces all stored session cookies for the profile.

Removes all stored session cookies from the profile.

Takes the profile's stored session cookies and injects them into the live WKWebsiteDataStore, making them immediately available to web pages.

Returns all cookies currently in the profile's live data store (not just stored ones). Optionally filter by domain.

Exports a complete profile including all settings, proxy config, DNS, privacy flags, session cookies, and ALL live cookies from the data store. The output can be fed directly into the import endpoint.

Creates a new profile from JSON data (same format as export). Live cookies are injected into the new profile's data store.

Downloads a profile ZIP from a remote URL (Dropbox, Google Drive, direct links) and imports it.

Returns the number of data records, cookies, and data type breakdown for a profile's storage.

Removes ALL browsing data for the profile (cookies, cache, local storage, indexed databases, etc.).

Returns all privacy/permission settings for the profile. null values mean the profile inherits the global setting.

Update privacy/permission settings for the profile. Pass "resetToGlobal": true to clear all overrides and use global settings.

Returns the global proxy configuration (applies to profiles without their own proxy).

Update the global proxy configuration. All fields are optional (partial update).

Returns the current DNS provider and lists all available providers with details.

Changes the global DNS provider.

Measures the latency to a specific DNS provider in milliseconds.

Tests latency for all DNS providers, sorted by fastest first.

Returns comprehensive Tor status including connection state, SOCKS proxy details, and circuit info.

Requests a new Tor circuit (new exit IP). Tor must be connected. Sends SIGNAL NEWNYM to the Tor control port.

Smoothly moves the simulated mouse cursor to a target position or CSS selector. Dispatches pointermove and mousemove events along the path. Supports multiple easing modes including human-like movement with random jitter.

Dispatches a complete click event sequence at the target: pointerdown → mousedown → pointerup → mouseup → click. Optionally fires dblclick for double-click.

Dispatches pointerdown and mousedown events at the target position. Use with /mouse/up for drag operations.

Dispatches pointerup and mouseup events at the target position. Use after /mouse/down to complete drag operations.

Generates random human-like mouse movements for a specified duration. Moves between random targets within a bounding area with ease-in-out curves and micro-jitter. Useful for anti-detection and making automated sessions appear natural.

Moves the mouse cursor along a sequence of waypoints with proportional timing based on segment distances. Each segment uses the specified easing function.

Check if an element is visible (has dimensions, not hidden/display:none).

Check if an element is not disabled.

Check the checked state of an input element.

Inverse of visible — returns true if element has no dimensions or is hidden.

Count elements matching the selector.

Returns x, y, width, height, top, right, bottom, left.

Returns the innerHTML of the first matching element.

Returns the rendered innerText of the element.

Returns the raw textContent of the element (includes hidden text).

Get a specific attribute value.

Take a screenshot of a specific element (base64 PNG). macOS only.

Dispatch pointerenter/mouseover/mouseenter events on element center.

Call el.focus() on the matched element.

Dispatch full mousedown/mouseup/click/dblclick sequence.

Dispatch keydown/keypress/keyup on element or active element.

Set checked=false and dispatch change event.

Returns document.documentElement.outerHTML.

Returns the current tab title.

Dispatch keydown/keypress/keyup on the active element.

Insert text using execCommand or value setter.

Dispatch keydown only.

Dispatch keyup only.

Dispatch WheelEvent.

Click an element or coordinates using real OS input events. The element is scrolled into view first. In headed mode, the window is activated and a CGEvent mouse click is posted at screen coordinates. In hidden/headless mode, an NSEvent is injected directly into the WKWebView (still isTrusted:true). Both modes work reliably for concurrent instances.

Type text character by character using real OS keyboard events. Each keystroke produces isTrusted: true. Optional selector focuses the element first. Delay controls milliseconds between keystrokes.

Press a key with optional modifiers using real OS keyboard events. Supports: Enter, Tab, Escape, Backspace, Space, Arrow keys, F1-F12, Home, End, PageUp, PageDown, all letters and digits. Modifiers: Command, Control, Shift, Alt/Option.

Sets the system clipboard with text (and optionally HTML), then sends a real Cmd+V keystroke. In headed mode, activates the window and uses CGEvent. In hidden/headless mode, injects NSEvent Cmd+V directly into the WKWebView (still isTrusted:true). Pasteboard access is serialized for safe use with 20+ concurrent hidden instances.

Move the mouse cursor using OS events with smooth interpolation (ease-in-out). Steps controls intermediate points, duration is total time in ms.

Get a value from localStorage.

Remove a key from localStorage.

Clear all localStorage entries.

Get a value from sessionStorage.

Set a value in sessionStorage.

Remove a key from sessionStorage.

Clear all sessionStorage entries.

Polls a JS expression until it returns a truthy value. Max timeout: 300s.

Simple sleep/delay. Max: 300s.

Polls until the tab URL changes and loading completes.

Wait for "load", "domcontentloaded", or "networkidle" state.

Polls until the tab URL contains the given pattern.

Enumerate all frames with index, name, and URL. Cross-origin frames show "(cross-origin)".

Run JavaScript in a specific same-origin frame by index. Returns 403 for cross-origin frames.

Click an element within a same-origin child frame. Returns 403 for cross-origin frames.

Walk the DOM tree and return roles, aria labels, text content, IDs, and class names as a nested JSON tree.

Override navigator.geolocation for the tab.

Override Intl.DateTimeFormat timezone.

Override navigator.language and navigator.languages.

Force light or dark mode for the page.

Set how alerts/confirms/prompts are handled.

Check if there is a dialog waiting for resolution.

Accept the pending dialog (OK/Yes). Optionally provide promptText for prompt dialogs.

Dismiss the pending dialog (Cancel/No).

Monkey-patches fetch() and XMLHttpRequest to log all requests with URL, method, status, and timing.

Returns logged requests. Use ?clear=true to clear the log after reading.

Clear network log and disable monitoring.

Intercepts console.log, warn, error, and info. Also captures uncaught JS errors.

Returns captured console entries. Filter with ?level=error or clear with ?clear=true.

Clear console log and stop capturing.

Start a trace session. Returns a traceId to use with stop.

Stop the trace and return all recorded actions with timestamps.

Connect via WebSocket to receive real-time browser events. API key is passed as a query parameter.