API reference
Actions
Run a list of steps in order, in one request.
A whole form flow is one round trip; a single click is a list of one. Steps run in the order given and stop at the first failure.
Run actions
POST/v1/sessions/{id}/actionsReturns 200 whether or not a step failed. Check ok in the response.
Path
- idstringrequired
The session to drive.
Body
- actionslist of steps, ≤50required
The steps to run. Each step has a
typeand the fields for that type, listed under Step types. - tab_idstringdefaultthe active tab
The tab every step runs in.
Response
- okbool
truewhen every step succeeded. - completedint
The number of steps that succeeded.
- resultslist
One entry per step that ran, in order.
- typestring
The step's
type. - okbool
Whether this step succeeded.
- duration_msint
How long the step took.
- errorobject
Only on a failed step:
codeandmessage.
- urlstring
The address of the page after the steps ran.
- titlestring
The title of that page.
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/actions" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"actions": [
{"type": "navigate", "url": "https://example.com/login"},
{"type": "fill", "selector": "#email",
"value": "[email protected]"},
{"type": "fill", "xpath": "//input[@name=\"password\"]",
"value": "hunter2"},
{"type": "click", "text": "Sign in"},
{"type": "wait", "selector": ".dashboard",
"timeout_ms": 10000}
]
}'const base = process.env.SPHYNX_URL;
const endpoint = `${base}/v1/sessions/${sessionId}/actions`;
const res = await fetch(endpoint, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
actions: [
{ type: "navigate", url: "https://example.com/login" },
{
type: "fill",
selector: "#email",
value: "[email protected]",
},
{
type: "fill",
xpath: '//input[@name="password"]',
value: "hunter2",
},
{ type: "click", text: "Sign in" },
{
type: "wait",
selector: ".dashboard",
timeout_ms: 10000,
},
],
}),
});
const result = await res.json();import os
import requests
base = os.environ["SPHYNX_URL"]
headers = {
"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}",
}
res = requests.post(
f"{base}/v1/sessions/{session_id}/actions",
headers=headers,
json={
"actions": [
{
"type": "navigate",
"url": "https://example.com/login",
},
{
"type": "fill",
"selector": "#email",
"value": "[email protected]",
},
{
"type": "fill",
"xpath": '//input[@name="password"]',
"value": "hunter2",
},
{"type": "click", "text": "Sign in"},
{
"type": "wait",
"selector": ".dashboard",
"timeout_ms": 10000,
},
]
},
timeout=60,
)
result = res.json(){
"ok": true,
"completed": 5,
"results": [
{ "type": "navigate", "ok": true, "duration_ms": 812 },
{ "type": "fill", "ok": true, "duration_ms": 96 },
{ "type": "fill", "ok": true, "duration_ms": 88 },
{ "type": "click", "ok": true, "duration_ms": 780 },
{ "type": "wait", "ok": true, "duration_ms": 640 }
],
"url": "https://example.com/dashboard",
"title": "Dashboard"
}Step types
Where a step targets an element it takes a locator: exactly one of selector (CSS), xpath or text (visible text, case-insensitive substring). The first match is used. See Concepts.
Steps
- navigate
Loads a page. Same as Navigate.
- urlstring, http or https, ≤2048required
- wait_untilload or domcontentloadeddefaultload
- timeout_msint, ≤60000default30000
- click
Moves the pointer to a point of the element that a click would reach, and clicks. When something lies over the middle of the element, a point near one of its edges is used. When every point tried is covered, nothing is clicked and the step fails with
element_covered.- selector, xpath or textlocatorrequired
- fill
Focuses the field, clears it and sets the value. A
selecttakes the value of one of its options, which is the option's text when it has novalueattribute. A checkbox, a radio button, a file input given a file, or aselectwithout that option is left as it is and the step fails withinvalid_request.- selector, xpath or textlocatorrequired
- valuestringrequired
- type
Types key by key with human timing. With a locator it clicks the element first; without one it types into whatever has focus.
- valuestringrequired
- selector, xpath or textlocator
- press
Presses one key.
- keystringrequired
Enter,Tab,Escape,ArrowDown,Backspace, or a single character.
- scroll
Scrolls by pixels, or scrolls an element into view.
- delta_yintdefault800
Pixels to scroll. Negative is up.
0is the default, not a no-op. - selector, xpath or textlocator
Scroll this element into view instead.
- hover
Moves the pointer over the element, to a point picked as for
click.- selector, xpath or textlocatorrequired
- wait
Waits for an element to be visible, or sleeps.
- selector, xpath or textlocator
Wait until this element is visible.
- timeout_msint, ≤60000default10000
How long to wait for the element.
- msint, 1–10000
With no locator: sleep this long.
{
"actions": [
{ "type": "navigate", "url": "https://example.com/login" },
{ "type": "click", "text": "Sign in" },
{ "type": "fill", "selector": "#email",
"value": "[email protected]" },
{ "type": "type", "value": "hello" },
{ "type": "press", "key": "Enter" },
{ "type": "scroll", "delta_y": 800 },
{ "type": "hover", "xpath": "//nav//a[1]" },
{ "type": "wait", "selector": ".dashboard",
"timeout_ms": 10000 }
]
}How long steps take
Steps act the way a person would, so some take seconds. Set your client's timeout for the whole list.
| Step | Time |
|---|---|
click, hover | About 0.5 to 1 s each. The pointer moves to the element along a human-like path |
type | About 0.1 s per character |
scroll by delta_y | The wheel turns at about 1000 px per second: the default 800 px takes about 0.8 s. A delta_y beyond roughly 25,000 px does not finish inside the 30 s a step gets |
fill on an element in view, press | Milliseconds |
click, hover, type, fill and scroll with a locator first wheel an element that is outside the viewport into view at the same rate, for at most 8000 px (about 8 s). Further away than that the page jumps to it.
When a step fails
The response is still 200, with ok: false. The failed step carries the error. Later steps do not run and are not listed.
A malformed request is rejected with 400 invalid_request before anything runs: an unknown type, a missing field, two locators on one step, an empty list, or more than 50 steps. details.index names the bad step.
Only the shape of the request is checked up front. A selector or XPath the page cannot parse fails its own step with invalid_request, after the steps before it have run.
{
"ok": false,
"completed": 1,
"results": [
{ "type": "navigate", "ok": true, "duration_ms": 790 },
{
"type": "click", "ok": false, "duration_ms": 31,
"error": {
"code": "element_not_found",
"message": "no element matched"
}
}
],
"url": "https://example.com/login",
"title": "Log in"
}Errors
Step errors are reported inside results, on the step that failed.
| Code | When |
|---|---|
element_not_found | No element matched the locator |
element_covered | Another element lies over the target wherever a click was tried. A step error of click and hover, and of type with a locator, which clicks first. The message ends with a CSS selector of the element on top |
wait_timeout | A wait step timed out: nothing matched the locator, or the match never became visible. The message says which |
navigation_timeout | The page did not reach wait_until in timeout_ms |
navigation_failed | The page did not load: DNS failure, connection refused or reset, TLS error, an address the session may not reach, a redirect from the page to a URL that does not load, or a response with nothing to show (204, download) |
unsafe_url | Not http/https, longer than 2048 characters, or a private, loopback or link-local address in the URL |
no_page_loaded | The tab is blank |
invalid_request | A selector or XPath the page cannot parse, or a value the control does not take |
internal | Our fault |
Request errors fail the whole call. The shape is the same as everywhere else: see Errors.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | Malformed JSON, unknown field, unknown type, missing field, a number outside its range, two locators on one step, an empty list or more than 50 steps |
| 401 | unauthorized | Missing or invalid API key |
| 404 | session_not_found | No such session for this key |
| 404 | tab_not_found | No such tab |
| 409 | session_in_use | Another drive call has been running on this session for more than 3 s |
| 410 | session_closed | The session has ended |
| 500 | internal | Our fault. Send us the request_id |