API reference

This is the complete reference for the Santiago automation API: the set of endpoints the local daemon exposes for controlling a running browser profile. Every endpoint drives a real Playwright-backed page inside the anti-detect browser, so the same fingerprint and proxy you configured for the profile apply to every action.

For setup and high-level usage, see HTTP API basics and Best practices. For worked end-to-end flows, see the automation guides.

Base URL and conventions

All automation endpoints live under the local daemon and target one running profile by id:

http://localhost:7891/api/automation/:profileId/<action>

The daemon listens on http://localhost:7891 only. Replace :profileId with the id of a running profile — launch it first (see Launch profiles for automation). Calls to a profile that is not running return 404 PROFILE_NOT_RUNNING.

Element targeting

Most interaction endpoints accept either ref (an element id from a snapshot) or selector (a CSS selector). At least one is required. The ref workflow is the most reliable: take a snapshot, read the [ref=eN] ids, then act on them.

Response format

Every endpoint returns the same envelope.

Success

{ "ok": true, "data": { ... } }

Error

{ "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }

Actions that only succeed or fail (click, hover, type, mouse moves, etc.) return { "ok": true } with no data. Endpoints that produce a value (snapshot, screenshot, navigate, tabs, evaluate, dialog) populate data.

Timeouts

Constant	Value	Applies to
Navigation timeout	30s	navigate, back, forward, reload, opening a tab with a URL
Action timeout	2s	Interaction endpoints (click, hover, type, select-option, scroll-to, screenshots of an element)
Wait timeout	15s (default)	wait endpoint; override with the timeout field

Why interactions fail fast

The action timeout is deliberately short (2s). On animated or unstable pages, a long wait on scroll-into-view is wasted time. If a locator-based action times out, fall back to coordinate-based mouse actions or fill-page.

Navigation

Method	Path	Key params	Purpose
POST	/:profileId/navigate	url (required)	Navigate to a URL.
POST	/:profileId/back	none	Go back in history.
POST	/:profileId/forward	none	Go forward in history.
POST	/:profileId/reload	none	Reload the current page.

All four return { ok, data: { url, title } } with the resulting page URL and title.

Navigate to a URL

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/navigate \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'

Response

{ "ok": true, "data": { "url": "https://example.com/", "title": "Example Domain" } }

Snapshot and screenshot

Method	Path	Key params	Purpose
POST	/:profileId/snapshot	selector, depth	Capture the accessibility tree of the page and get element refs.
POST	/:profileId/screenshot	fullPage, ref, selector	Take a base64-encoded PNG screenshot.

POST /:profileId/snapshot

Capture the accessibility tree of the current page. This is the primary way to “see” page structure and obtain [ref=eN] ids for later actions.

Field	Type	Default	Description
selector	string	—	CSS selector to scope the snapshot to one element subtree
depth	number	—	Limit tree depth

Snapshot the page

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/snapshot \
  -H 'Content-Type: application/json' \
  -d '{}'

Response

{ "ok": true, "data": { "snapshot": "- heading \"Example\" [ref=e1]\n- textbox \"Email\" [ref=e2]\n..." } }

POST /:profileId/screenshot

Take a screenshot. Returns a base64-encoded PNG string. Provide ref or selector to capture a single element; otherwise the viewport (or full page) is captured.

Field	Type	Default	Description
fullPage	boolean	false	Capture the full scrollable page (ignored when ref/selector is set)
ref	string	—	Screenshot a specific element by ref
selector	string	—	Screenshot a specific element by CSS selector

Response

{ "ok": true, "data": { "screenshot": "iVBORw0KGgo..." } }

Click and interaction

All interaction endpoints below accept either ref (from snapshot) or selector (CSS); at least one is required.

Method	Path	Key params	Purpose
POST	/:profileId/click	ref/selector, button, doubleClick, modifiers	Click an element.
POST	/:profileId/hover	ref/selector	Hover over an element.
POST	/:profileId/drag	startRef/startSelector, endRef/endSelector	Drag and drop between two elements.
POST	/:profileId/scroll-to	ref/selector	Scroll an element into view.

POST /:profileId/click

Field	Type	Default	Description
ref	string	—	Element ref from snapshot
selector	string	—	CSS selector
button	"left" | "right" | "middle"	"left"	Mouse button
doubleClick	boolean	false	Double click
modifiers	string[]	—	"Alt", "Control", "ControlOrMeta", "Meta", "Shift"

Click by ref

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/click \
  -H 'Content-Type: application/json' \
  -d '{"ref": "e20"}'

POST /:profileId/hover

Field	Type	Description
ref	string	Element ref
selector	string	CSS selector

POST /:profileId/drag

Drag from a source element to a target element. Each side accepts a ref or a selector.

Field	Type	Description
startRef	string	Source element ref
startSelector	string	Source CSS selector
endRef	string	Target element ref
endSelector	string	Target CSS selector

POST /:profileId/scroll-to

Scroll an element into view.

Field	Type	Description
ref	string	Element ref
selector	string	CSS selector

Dropdowns

Two endpoints cover the two kinds of dropdowns you meet on the web: native <select> elements and custom ARIA combobox widgets.

Method	Path	Key params	Purpose
POST	/:profileId/select-option	ref/selector, values (required)	Select option(s) in a native <select>.
POST	/:profileId/select-combobox	ref/selector, value (required), optionSelector	Smart selection for custom ARIA combobox dropdowns.

POST /:profileId/select-option

Select option(s) in a native <select> element.

Field	Type	Required	Description
ref / selector	string	yes	Target <select> element
values	string[]	yes	Values to select

Response

{ "ok": true, "data": { "selected": ["value1"] } }

POST /:profileId/select-combobox

Smart selection for ARIA combobox dropdowns — the custom <div role="combobox"> widgets used by many modern web apps. It performs the whole sequence: click to open, read aria-controls to find the listbox, wait for the listbox to become visible (5s), find the [role="option"] matching value (or your optionSelector), and click it.

Field	Type	Required	Description
ref / selector	string	yes	Target combobox element
value	string	yes	Option text to select
optionSelector	string	—	Custom CSS selector for the option (overrides text matching)

Select a custom-dropdown option

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/select-combobox \
  -H 'Content-Type: application/json' \
  -d '{"ref": "e5", "value": "March"}'

Response

{ "ok": true, "data": { "selected": "March" } }

Text input and keyboard

Method	Path	Key params	Purpose
POST	/:profileId/type	ref/selector, text (required)	Clear a field and type a value (human-like per-key delay).
POST	/:profileId/press-sequentially	ref/selector, text (required), delay	Type text key by key without clearing first.
POST	/:profileId/press-key	key (required), modifiers	Press a key or key combination.
POST	/:profileId/fill-form	fields (required)	Fill multiple fields at once (ref/selector based).
POST	/:profileId/fill-page	fields, submit, waitAfterSubmit	High-level coordinate-based form fill + optional submit.

POST /:profileId/type

Focus a field, clear its existing value, then type the new value with a human-like per-key delay.

Field	Type	Required	Description
ref / selector	string	yes	Target input element
text	string	yes	Text to type

Type into a field

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/type \
  -H 'Content-Type: application/json' \
  -d '{"ref": "e2", "text": "jane.doe@example.com"}'

POST /:profileId/press-sequentially

Type text key by key into the targeted element (does not clear first). Useful for inputs that react to each keystroke.

Field	Type	Default	Description
ref / selector	string	required	Target element
text	string	required	Text to type
delay	number	50	Delay between keys in ms

POST /:profileId/press-key

Press a single keyboard key or a combination. With modifiers, the daemon joins them into a chord (for example Control+a).

Field	Type	Description
key	string	Key name: "Enter", "Tab", "Escape", "a", "F1", etc.
modifiers	string[]	"Alt", "Control", "ControlOrMeta", "Meta", "Shift"

Submit a form with Enter

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/press-key \
  -H 'Content-Type: application/json' \
  -d '{"key": "Enter"}'

POST /:profileId/fill-form

Fill multiple form fields in one call. Each field is filled via a Playwright locator (click, clear, type); if that fails, the daemon falls back to a coordinate-based strategy (resolve bounding box, click center, select-all, delete, type). Each field result reports the strategy used (locator or coords).

Field	Type	Required	Description
fields	array	yes	[{ ref?, selector?, value }]

Fill several fields

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/fill-form \
  -H 'Content-Type: application/json' \
  -d '{
    "fields": [
      {"ref": "e2", "value": "Jane Doe"},
      {"selector": "#email", "value": "jane@example.com"}
    ]
  }'

Response

{
  "ok": true,
  "data": {
    "results": [
      { "ref": "e1", "ok": true },
      { "selector": "#email", "ok": true },
      { "ref": "e3", "ok": false, "error": "Element not found" }
    ]
  }
}

POST /:profileId/fill-page

A high-level, coordinate-based fill that bypasses Playwright locators entirely (evaluate to find centers, then mouse + keyboard). One call can fill a whole form, select comboboxes, and click submit — replacing many round-trips. Comboboxes are opened, the matching option is clicked, and the selection is verified (with one automatic retry).

Field	Type	Default	Description
fields	array	—	Array of field objects (see below)
submit	object	—	{ selector?, text? } submit button (selector first, then text fallback)
waitAfterSubmit	number	2000	Milliseconds to wait after clicking submit

Each entry in fields:

Field	Type	Default	Description
selector	string	required	CSS selector for the element
value	string	required	Value to type, or the option text to select
type	"text" | "combobox"	"text"	Field kind
nth	number	0	0-based index when the selector matches multiple elements
optionSelector	string	li[role=option]	CSS for option elements (combobox only)

At least one of fields or submit is required (otherwise 400 BAD_REQUEST).

Fill and submit a form in one call

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/fill-page \
  -H 'Content-Type: application/json' \
  -d '{
    "fields": [
      {"selector": "#firstName", "value": "Jane"},
      {"selector": "#month", "value": "March", "type": "combobox"}
    ],
    "submit": {"text": "Submit"},
    "waitAfterSubmit": 3000
  }'

Response

{
  "ok": true,
  "data": {
    "results": [
      { "selector": "#firstName", "type": "text", "ok": true },
      { "selector": "#month", "type": "combobox", "ok": true, "selectedValue": "March" }
    ],
    "submit": { "ok": true, "url": "https://example.com/welcome" }
  }
}

Mouse (coordinate-based)

Low-level mouse control by viewport coordinates. Use these when locator-based interaction is blocked or unreliable.

Method	Path	Key params	Purpose
POST	/:profileId/mouse/move	x, y (required)	Move the cursor to a point.
POST	/:profileId/mouse/click	x, y (required), button	Click at a point.
POST	/:profileId/mouse/down	button	Press a mouse button down.
POST	/:profileId/mouse/up	button	Release a mouse button.
POST	/:profileId/mouse/wheel	deltaX, deltaY	Scroll the wheel.

POST /:profileId/mouse/move

Field	Type	Required
x	number	yes
y	number	yes

POST /:profileId/mouse/click

Field	Type	Default
x	number	required
y	number	required
button	"left" | "right" | "middle"	"left"

POST /:profileId/mouse/down and /:profileId/mouse/up

Field	Type	Default
button	"left" | "right" | "middle"	"left"

POST /:profileId/mouse/wheel

Field	Type	Default	Description
deltaX	number	0	Horizontal scroll
deltaY	number	0	Vertical scroll (positive = down)

Click at a coordinate

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/mouse/click \
  -H 'Content-Type: application/json' \
  -d '{"x": 480, "y": 320}'

Tabs

Method	Path	Key params	Purpose
GET	/:profileId/tabs	none	List open tabs.
POST	/:profileId/tabs/new	url	Open a new tab (blank if url omitted).
POST	/:profileId/tabs/select	index (required)	Switch to a tab by index.
POST	/:profileId/tabs/close	index	Close a tab (defaults to the last; cannot close the last remaining tab).

GET /:profileId/tabs

List tabs

curl http://localhost:7891/api/automation/$PROFILE_ID/tabs

Response

{ "ok": true, "data": { "tabs": [{ "index": 0, "url": "https://...", "title": "..." }] } }

POST /:profileId/tabs/new

Field	Type	Default	Description
url	string	—	URL to open (blank tab if omitted)

Returns { ok, data: { index, url, title } }.

POST /:profileId/tabs/select

Field	Type	Required
index	number	yes

Returns { ok, data: { index, url, title } }. Out-of-range index returns 400 BAD_REQUEST.

POST /:profileId/tabs/close

Field	Type	Default	Description
index	number	last tab	Tab index to close

Returns { ok, data: { closedIndex } }. Closing the only remaining tab returns 400 LAST_TAB — stop the profile instead.

Evaluate

Method	Path	Key params	Purpose
POST	/:profileId/evaluate	code (required)	Run JavaScript in the page context and return the result.

POST /:profileId/evaluate

Field	Type	Required
code	string	yes

Read the document title from the page

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/evaluate \
  -H 'Content-Type: application/json' \
  -d '{"code": "document.title"}'

Response

{ "ok": true, "data": { "result": "Example Domain" } }

Wait

Method	Path	Key params	Purpose
POST	/:profileId/wait	text, selector, state, timeout	Wait for an element/text state, or a fixed time.

POST /:profileId/wait

If you pass selector or text, the call waits for that element to reach state. If you pass neither, it just waits for timeout milliseconds.

Field	Type	Default	Description
text	string	—	Wait for this text to appear
selector	string	—	Wait for this CSS selector
state	"visible" | "hidden" | "attached" | "detached"	"visible"	Target state
timeout	number	15000	Timeout in ms. With no text/selector, waits this long unconditionally

Wait for an element to appear

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/wait \
  -H 'Content-Type: application/json' \
  -d '{"selector": "#dashboard", "state": "visible", "timeout": 20000}'

Dialog

Method	Path	Key params	Purpose
POST	/:profileId/dialog	action (required), promptText	Accept or dismiss a pending alert/confirm/prompt.

POST /:profileId/dialog

The daemon tracks native dialogs (alert, confirm, prompt) per profile as they open. Call this endpoint to handle the oldest pending one.

Field	Type	Required	Description
action	"accept" | "dismiss"	yes	Accept or dismiss the dialog
promptText	string	—	Text to enter for prompt dialogs (used on accept)

Response

{ "ok": true, "data": { "type": "confirm", "message": "Are you sure?", "defaultValue": "" } }

If there is no pending dialog, the call returns 404 NO_DIALOG.

Batch execution

Method	Path	Key params	Purpose
POST	/:profileId/batch	actions (required)	Run multiple actions in one HTTP call, with human-like pacing.

POST /:profileId/batch

Execute several actions sequentially in a single request. The daemon inserts a random 80–250ms delay between actions for human-like pacing. It stops on the first error — remaining actions are skipped (so they never run on stale state).

Type, select, then click in one call

curl -X POST http://localhost:7891/api/automation/$PROFILE_ID/batch \
  -H 'Content-Type: application/json' \
  -d '{
    "actions": [
      {"action": "type", "ref": "e1", "text": "Jane Doe"},
      {"action": "select-combobox", "ref": "e5", "value": "March"},
      {"action": "click", "ref": "e20"}
    ]
  }'

Available actions and the fields each one uses (same as the matching individual endpoint):

Action	Fields
click	ref/selector, button, doubleClick, modifiers
type	ref/selector, text
press-sequentially	ref/selector, text, delay
press-key	key, modifiers
select-option	ref/selector, values
select-combobox	ref/selector, value, optionSelector
hover	ref/selector
scroll-to	ref/selector
wait	text, selector, state, timeout
navigate	url
snapshot	selector, depth
screenshot	ref, selector, fullPage
evaluate	code

Response

{
  "ok": true,
  "data": {
    "results": [
      { "index": 0, "action": "type", "ok": true },
      { "index": 1, "action": "select-combobox", "ok": true, "data": { "selected": "March" } },
      { "index": 2, "action": "click", "ok": true }
    ]
  }
}

An empty actions array returns 400 BAD_REQUEST.

Error codes

Code	When
PROFILE_NOT_RUNNING	The profile id is not a running profile (HTTP 404).
BAD_REQUEST	Missing required body fields, or an out-of-range tab index (HTTP 400).
LAST_TAB	Attempt to close the only remaining tab (HTTP 400).
NO_DIALOG	dialog called with no pending dialog (HTTP 404).
NAVIGATE_FAILED	navigate / back / forward / reload failed.
SNAPSHOT_FAILED / SCREENSHOT_FAILED	Snapshot or screenshot failed.
CLICK_FAILED / HOVER_FAILED / DRAG_FAILED / SCROLL_FAILED	The corresponding interaction failed (often a 2s action timeout).
SELECT_FAILED / SELECT_COMBOBOX_FAILED	Dropdown selection failed.
TYPE_FAILED / PRESS_SEQ_FAILED / KEY_PRESS_FAILED / FILL_FORM_FAILED / FILL_PAGE_FAILED	Text input failed.
MOUSE_FAILED	A coordinate mouse action failed.
TABS_FAILED / TAB_NEW_FAILED / TAB_SELECT_FAILED / TAB_CLOSE_FAILED	A tab action failed.
EVALUATE_FAILED	The page script threw.
WAIT_FAILED	The wait condition timed out.
DIALOG_FAILED	Handling the dialog failed.
BATCH_FAILED	The batch request could not run (e.g. profile not running).

Next steps

See Best practices for resilient sequencing, and the automation guides for full end-to-end flows that combine these endpoints.