Skip to main content

​
POST /tabs

Creates a new browser tab within a user’s session. Tabs are organized by sessionKey (also called listItemId for backward compatibility) to group related browsing tasks.

​
Authentication

All tab operations require a userId in the request body to identify which user session owns the tab.

​
Request

​
Body parameters

​
userId
string
required
User identifier for session isolation. Sessions maintain separate cookies, storage, and browser contexts.
​
sessionKey
string
required
Session key to group related tabs together (e.g., by conversation or task). Legacy name: listItemId.
​
listItemId
string
Deprecated. Use sessionKey instead. Accepted for backward compatibility.
​
url
string
Initial URL to navigate to after creating the tab. Must use http: or https: protocol. If omitted, tab opens to about:blank.

​
Response

​
tabId
string
UUID identifier for the newly created tab. Use this in all subsequent tab operations.
​
url
string
Current URL of the tab after creation.

​
Example

curl -X POST http://localhost:9377/tabs \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "sessionKey": "task123",
    "url": "https://example.com"
  }'
Response: 
{
  "tabId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "url": "https://example.com"
}

​
Error responses

StatusErrorCause
400userId and sessionKey requiredMissing required fields
400Invalid URL: <url>Malformed URL
400Blocked URL scheme: <scheme>Non-HTTP/HTTPS protocol
429Maximum tabs per session reachedSession has 10+ tabs (configurable via MAX_TABS_PER_SESSION)
500Internal server errorBrowser launch failure or unexpected error

​
Notes

  • Maximum tabs per session is configurable (default: 10 via MAX_TABS_PER_SESSION)
  • Global tab limit across all users is 100 (configurable via MAX_TABS_GLOBAL)
  • Each userId gets an isolated browser context with separate cookies and storage
  • Tabs within the same sessionKey can be closed together using DELETE /tabs/group/:groupId
  • URL navigation timeout is 30 seconds
  • Sessions auto-expire after 30 minutes of inactivity (configurable via SESSION_TIMEOUT_MS)

Build docs developers (and LLMs) love

Get started for freeTalk to us