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