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

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

    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_urlurl is not http/https, or is a private, loopback or link-local address
500internalOur fault. Send us the request_id
502navigation_failedThe url of a new tab could not be loaded: DNS failure, connection refused, TLS error
504navigation_timeoutThe url of a new tab did not load in time