Guides
Fill a form
Find the fields on a page, fill them and submit, in one request.
This guide logs in to a site over HTTP: one call to see what is on the page, one call to fill the form and submit it. No browser library is needed.
Before you start
You need an API key and a running session. The snippets read the base URL and the key from the environment and keep the session ID in SESSION.
export SPHYNX_URL=http://localhost:8080 # your deployment's base URL
export SPHYNX_API_KEY=sx_live_...
SESSION=$(curl -s -X POST "$SPHYNX_URL/v1/sessions" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"start_url": "https://example.com/login"}' | jq -r .id)start_url is loaded before the call returns, so the session starts on the login page. If it does not load, the call fails with navigation_failed or navigation_timeout and no session is returned.
https://example.com/login stands in for the login page of your site: a form with an email field, a password field and a Sign in button.
Find the fields
POST/v1/sessions/{id}/elements with an empty body lists what a person could interact with: links, buttons, inputs, selects, textareas and elements with a click handler or button role.
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/elements" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Every element comes back with a unique selector and an absolute xpath. Either can be passed straight back as a locator.
{
"count": 3,
"truncated": false,
"elements": [
{
"selector": "#email",
"xpath": "/html/body/form[1]/input[1]",
"tag": "input",
"name": "email",
"type": "email",
"placeholder": "Email",
"visible": true
},
{
"selector": "#login > input:nth-of-type(2)",
"xpath": "/html/body/form[1]/input[2]",
"tag": "input",
"name": "password",
"type": "password",
"placeholder": "Password",
"visible": true
},
{
"selector": "#login > button",
"xpath": "/html/body/form[1]/button[1]",
"tag": "button",
"text": "Sign in",
"type": "submit",
"visible": true
}
]
}Fill and submit
POST/v1/sessions/{id}/actions runs a list of steps in order. Fill both fields, click the button and wait for the page that follows.
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/actions" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"actions": [
{"type": "fill", "selector": "#email", "value": "me@example.com"},
{"type": "fill", "xpath": "//input[@name=\"password\"]", "value": "hunter2"},
{"type": "click", "text": "Sign in"},
{"type": "wait", "selector": ".dashboard", "timeout_ms": 10000}
]
}'const res = await fetch(`${process.env.SPHYNX_URL}/v1/sessions/${sessionId}/actions`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
actions: [
{ type: "fill", selector: "#email", value: "me@example.com" },
{ 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
res = requests.post(
f"{os.environ['SPHYNX_URL']}/v1/sessions/{session_id}/actions",
headers={"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"},
json={
"actions": [
{"type": "fill", "selector": "#email", "value": "me@example.com"},
{"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()The three locators are interchangeable. Use whichever is shortest for the element: a CSS selector, an xpath, or the visible text.
Check the result
The response lists every step that ran, then the page the session ended on. ok is true only when every step succeeded.
{
"ok": true,
"completed": 4,
"results": [
{ "type": "fill", "ok": true, "duration_ms": 96 },
{ "type": "fill", "ok": true, "duration_ms": 88 },
{ "type": "click", "ok": true, "duration_ms": 2140 },
{ "type": "wait", "ok": true, "duration_ms": 640 }
],
"url": "https://example.com/dashboard",
"title": "Dashboard"
}The click took about 2 s: the pointer moves to the element along a human-like path, which takes about 1.5 to 4 s. A fill on a field in view takes milliseconds. Set your client's timeout for the whole list. Timings for every step are under Actions.
When a step fails
Steps stop at the first failure. The call still returns 200, with ok: false, and the failed step carries the error. Later steps do not run.
{
"ok": false,
"completed": 2,
"results": [
{ "type": "fill", "ok": true, "duration_ms": 96 },
{ "type": "fill", "ok": true, "duration_ms": 88 },
{ "type": "click", "ok": false, "duration_ms": 31,
"error": { "code": "element_not_found", "message": "no element matched" } }
],
"url": "https://example.com/login",
"title": "Log in"
}What can go wrong
These codes appear on the failed step, inside a 200 response:
| Code | When |
|---|---|
element_not_found | No element matched the locator |
wait_timeout | A wait step timed out |
no_page_loaded | The tab is blank. Start with a navigate step or a start_url |
invalid_request | A selector or XPath the page cannot parse. The steps before it have run |
These fail the whole call:
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | An unknown type, a missing field or two locators on one step. Nothing runs. details.index names the step |
| 409 | session_in_use | Another drive call has been running on this session for more than 3 s. Retry |
| 410 | session_closed | The session has ended |
Fill or type
fill sets the whole value at once. type types key by key with human timing, about 0.1 s per character. press sends one key, such as Enter to submit.
{
"actions": [
{ "type": "type", "selector": "#search", "value": "27-inch monitor" },
{ "type": "press", "key": "Enter" }
]
}Close the session
A session keeps running until it is deleted, times out or sits idle for idle_timeout_seconds. Delete it when you are done.
curl -s -X DELETE "$SPHYNX_URL/v1/sessions/$SESSION" \
-H "Authorization: Bearer $SPHYNX_API_KEY"Next
- Actions: every step type and its fields.
- Elements: find elements by selector, XPath or text.
- Extract data: read values out of the page you landed on.