SPHYNX
esc
  • Loading
Open console

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}/actions

Returns 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 type and the fields for that type, listed under Step types.

  • tab_idstringdefaultthe active tab

    The tab every step runs in.

Response

  • okbool

    true when 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: code and message.

  • 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": "me@example.com"},
      {"type": "fill", "xpath": "//input[@name=\"password\"]",
       "value": "hunter2"},
      {"type": "click", "text": "Sign in"},
      {"type": "wait", "selector": ".dashboard",
       "timeout_ms": 10000}
    ]
  }'
200 · every step succeeded
{
  "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": 2140 },
    { "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 httpsrequired
    • wait_untilload or domcontentloadeddefaultload
    • timeout_msint, ≤60000default30000
  • click

    Moves the pointer to the element and clicks.

    • selector, xpath or textlocatorrequired
  • fill

    Focuses the field, clears it and sets the value.

    • 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.

    • selector, xpath or textlocator

      Scroll this element into view instead.

  • hover

    Moves the pointer over the element.

    • 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_msintdefault10000

      How long to wait for the element.

    • msint, ≤10000

      With no locator: sleep this long.

One step of each type
{
  "actions": [
    { "type": "navigate", "url": "https://example.com/login" },
    { "type": "click", "text": "Sign in" },
    { "type": "fill", "selector": "#email",
      "value": "me@example.com" },
    { "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.

StepTime
click, hoverAbout 1.5 to 4 s each. The pointer moves to the element along a human-like path
typeAbout 0.1 s per character
scroll by delta_yThe 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, pressMilliseconds

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, 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.

200 · the second step failed
{
  "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.

CodeWhen
element_not_foundNo element matched the locator
wait_timeoutA wait step timed out
navigation_timeoutThe page did not reach wait_until in timeout_ms
navigation_failedDNS failure, connection refused, TLS error
unsafe_urlNot http/https, or a private, loopback or link-local address
no_page_loadedThe tab is blank
invalid_requestA selector or XPath the page cannot parse
internalOur fault

Request errors fail the whole call. The shape is the same as everywhere else: see Errors.

HTTPCodeWhen
400invalid_requestMalformed JSON, unknown field, unknown type, missing field, two locators on one step, more than 50 steps
401unauthorizedMissing or invalid API key
404session_not_foundNo such session for this key
404tab_not_foundNo such tab
409session_in_useAnother drive call has been running on this session for more than 3 s
410session_closedThe session has ended
500internalOur fault. Send us the request_id