SPHYNX
esc
  • Loading
Open console

API reference

Tabs

List, open and close the tabs of a session.

Every drive call takes an optional tab_id. Calls without one use the active tab: the most recently opened tab, or the first tab (the one the session started with) if none was opened through the API. Every drive call brings its tab to the front first.

List tabs

GET/v1/sessions/{id}/tabs

Returns the open tabs of the session, in the order they were opened. The order is the same on every call.

Tabs that a page or a CDP client opened since the last API call come after the ones listed before, in no set order among themselves. From then on they keep their place.

After a navigation that failed the tab is on the browser's error page, and url is the address that failed.

Path

  • idstringrequired

    The session ID.

Response

  • datalist

    One entry per open tab.

    • tab_idstring

      The value to pass as tab_id on drive calls.

    • urlstring

      The address the tab is on.

    • titlestring

      The title of that page.

curl
curl -s "$SPHYNX_URL/v1/sessions/$SESSION/tabs" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200
{
  "data": [
    {
      "tab_id": "8B1F6C0A2D3E4F5A9B7C1D0E2F3A4B5C",
      "url": "https://example.com/",
      "title": "Example Domain"
    }
  ]
}

Open a tab

POST/v1/sessions/{id}/tabs

Returns 201 with the new tab. The new tab becomes the active tab. A tab the page opens itself, with target="_blank" or window.open, does not.

Path

  • idstringrequired

    The session ID.

Body

  • urlstring, ≤2048

    The address to load in the new tab. Leave it out to open a blank tab.

Response

  • tab_idstring

    The ID of the new tab.

  • urlstring

    The address the tab is on.

  • titlestring

    The title of that page.

curl
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/tabs" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
201
{
  "tab_id": "3E9A7D15C0B24F68A1D5E7F90B2C4D6E",
  "url": "https://example.com/",
  "title": "Example Domain"
}

Close a tab

DELETE/v1/sessions/{id}/tabs/{tab_id}

Returns 204 with no body. The only tab of a session cannot be closed: that call fails with 409 last_tab. To end the session, delete it.

Path

  • idstringrequired

    The session ID.

  • tab_idstringrequired

    The tab to close.

curl
curl -s -X DELETE \
  "$SPHYNX_URL/v1/sessions/$SESSION/tabs/$TAB" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"

Errors

The shape is the same as everywhere else: see Errors.

HTTPCodeWhen
400invalid_requestMalformed JSON or unknown field when opening a tab
401unauthorizedMissing or invalid API key
404session_not_foundNo such session for this key
404tab_not_foundNo such tab
409last_tabTried to close the only tab
409session_in_useAnother drive call has been running on this session for more than 3 s
410session_closedThe session has ended
422unsafe_urlThe url of a new tab is not http/https, is longer than 2048 characters, or has a private, loopback or link-local address in it
500internalOur fault. Send us the request_id
502navigation_failedThe url of a new tab 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)
504navigation_timeoutThe url of a new tab did not load in time