Skip to main content
POST
https://api.usedari.com
/
public
/
sessions
from dari import Dari

client = Dari(api_key="YOUR_API_KEY")

# Create a session with custom configuration
session = client.create_session(
    screen_config={"width": 1920, "height": 1080},
    ttl=3600,  # 1 hour
    metadata={"purpose": "workflow-automation", "user": "john"}
)

print(f"Session ID: {session['session_id']}")
print(f"Expires at: {session['expires_at']}")

# Create a session with a browser profile (with persistence)
session = client.create_session(
    profile_id="550e8400-e29b-41d4-a716-446655440000",
    persist_changes=True,
    ttl=3600
)

print(f"Session ID: {session['session_id']}")
print(f"Live URL: {session['metadata']['live_url']}")

# Create a session with a browser profile (without persistence)
session = client.create_session(
    profile_id="550e8400-e29b-41d4-a716-446655440000",
    persist_changes=False,
    ttl=3600
)

{
  "session_id": "sess_a1b2c3d4e5f6",
  "cdp_url": "ws://browser-proxy.usedari.com/devtools/browser/a1b2c3d4",
  "screen_config": {
    "width": 1920,
    "height": 1080
  },
  "status": "active",
  "expires_at": "2024-11-26T10:34:00Z",
  "metadata": {
    "purpose": "workflow-automation",
    "user": "john"
  },
  "created_at": "2024-11-26T09:34:00Z",
  "updated_at": "2024-11-26T09:34:00Z"
}
Create a managed browser session that can be reused across multiple browser actions. Sessions have a configurable TTL (time-to-live) up to 24 hours and are automatically cleaned up when they expire.

​
Headers

​
X-API-Key
string
required
Your API key for authentication
​
Content-Type
string
required
Must be application/json

​
Request Body

​
profile_id
string
UUID of a browser profile to use for this session. When provided, the session will load the profile’s saved cookies, login sessions, and browser state.
​
persist_changes
boolean
default:true
Whether to save cookies and browser state changes back to the profile. Only applicable when profile_id is provided.
  • true (default): Changes ARE saved to the profile
  • false: Use profile’s current state but don’t save changes
​
cdp_url
string
Optional external Chrome DevTools Protocol WebSocket URL to bring your own browser. If not provided, a managed browser instance is created automatically.
​
screen_config
object
Optional window configuration with width and height keys; defaults to {"width": 1280, "height": 720}
​
ttl
integer
Time-to-live in seconds. Maximum 86400 (24 hours). Defaults to 600 (10 minutes).
​
metadata
object
Optional custom metadata to attach to the session for tracking purposes

​
Response Fields

​
session_id
string
Unique identifier for the created session
​
cdp_url
string
Chrome DevTools Protocol WebSocket URL for the browser session (if managed)
​
screen_config
object
The configured screen dimensions
​
status
string
Session status: active, terminated, or expired
​
expires_at
string
ISO 8601 timestamp when the session will expire
​
metadata
object
Custom metadata attached to the session
​
created_at
string
ISO 8601 timestamp when the session was created
​
updated_at
string
ISO 8601 timestamp when the session was last updated
from dari import Dari

client = Dari(api_key="YOUR_API_KEY")

# Create a session with custom configuration
session = client.create_session(
    screen_config={"width": 1920, "height": 1080},
    ttl=3600,  # 1 hour
    metadata={"purpose": "workflow-automation", "user": "john"}
)

print(f"Session ID: {session['session_id']}")
print(f"Expires at: {session['expires_at']}")

# Create a session with a browser profile (with persistence)
session = client.create_session(
    profile_id="550e8400-e29b-41d4-a716-446655440000",
    persist_changes=True,
    ttl=3600
)

print(f"Session ID: {session['session_id']}")
print(f"Live URL: {session['metadata']['live_url']}")

# Create a session with a browser profile (without persistence)
session = client.create_session(
    profile_id="550e8400-e29b-41d4-a716-446655440000",
    persist_changes=False,
    ttl=3600
)

{
  "session_id": "sess_a1b2c3d4e5f6",
  "cdp_url": "ws://browser-proxy.usedari.com/devtools/browser/a1b2c3d4",
  "screen_config": {
    "width": 1920,
    "height": 1080
  },
  "status": "active",
  "expires_at": "2024-11-26T10:34:00Z",
  "metadata": {
    "purpose": "workflow-automation",
    "user": "john"
  },
  "created_at": "2024-11-26T09:34:00Z",
  "updated_at": "2024-11-26T09:34:00Z"
}

​
Usage Notes

  • Sessions are automatically cleaned up when they expire
  • Use the returned session_id with Run Single Action to execute actions in this session
  • Maximum TTL is 24 hours (86400 seconds)
  • Bring your own browser by providing a cdp_url parameter
  • Create sessions with sufficient TTL for your workflow - sessions cannot be extended after creation

​
Browser Profiles

  • When using profile_id, the session loads saved cookies, login sessions, and browser state from the profile
  • Set persist_changes: true (default) to save any changes made during the session back to the profile
  • Set persist_changes: false to use the profile’s state without modifying it (useful for testing or read-only operations)
  • Use the metadata.live_url to open the browser in your own browser for manual interaction (e.g., logging into websites)
  • After manually logging in, terminate the session to save the authentication state to the profile
  • See Create Browser Profile and List Browser Profiles for profile management

​
Error Responses

{
  "detail": "Invalid API key"
}

{
  "detail": "TTL cannot exceed 86400 seconds (24 hours)"
}