Create Session

Create a new session directly via the Platform Service.

Request


POST /v1/sessions

Headers

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`application/json`

Body

Field	Type	Required	Description
`metadata`	object	No	Arbitrary metadata to attach to the session
`config`	object	No	Session configuration options
`config.disconnectGracePeriodMs`	integer	No	Grace period in milliseconds before marking a disconnected session as expired
`config.commandTimeoutMs`	integer	No	Timeout in milliseconds for pending commands
`config.sessionDurationMs`	integer	No	Maximum session duration in milliseconds (max 3,600,000 = 1 hour)
`config.capture`	object	No	Capture configuration for page snapshots and screenshots
`config.capture.snapshots`	object	No	Snapshot capture settings
`config.capture.snapshots.enabled`	boolean	Yes*	Enable HTML snapshot capture after each command
`config.capture.snapshots.delayMs`	integer	No	Delay before capturing snapshot (ms)
`config.capture.screenshots`	object	No	Screenshot capture settings
`config.capture.screenshots.enabled`	boolean	Yes*	Enable periodic screenshot capture
`config.capture.screenshots.intervalMs`	integer	No	Interval between screenshots (ms)

* Required when the parent object is provided.

Response

201 Created


{
  "sessionId": "sess_xyz789",
  "clientToken": "ct_...",
  "workerToken": "wt_...",
  "websocketUrl": "wss://sessions.getpassage.ai/sessions/sess_xyz789/ws",
  "expiresAt": 1704081600000
}

400 Bad Request

Invalid request body — wrong types for config fields (must be positive integers), or malformed JSON.

Notes

Proxied to the Session Service via service binding
Session ownership is tracked in D1 for access control
Use the returned tokens to connect via WebSocket