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}/tabsReturns 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_idon drive calls. - urlstring
The address the tab is on.
- titlestring
The title of that page.
curl -s "$SPHYNX_URL/v1/sessions/$SESSION/tabs" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{
"data": [
{
"tab_id": "8B1F6C0A2D3E4F5A9B7C1D0E2F3A4B5C",
"url": "https://example.com/",
"title": "Example Domain"
}
]
}Open a tab
POST/v1/sessions/{id}/tabsReturns 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 -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"}'{
"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 -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.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | Malformed JSON or unknown field when opening a tab |
| 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 | last_tab | Tried to close the only 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 |
| 422 | unsafe_url | The 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 |
| 500 | internal | Our fault. Send us the request_id |
| 502 | navigation_failed | The 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) |
| 504 | navigation_timeout | The url of a new tab did not load in time |