Skip to main content
POST
/
v1
/
sessions
Start Session
curl --request POST \
  --url https://api.bctrl.ai/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "options": {
    "hostId": "<string>",
    "storage": "<string>"
  }
}
'
{
  "id": "<string>",
  "hostId": "<string>",
  "status": "<string>",
  "storageWorkspace": "<string>"
}
​
options
object
Session configuration.
The session starts with no driver attached. Use the Connect endpoint or the high-level bctrl.session.* helpers.

​
Examples

import { Bctrl } from '@bctrl/sdk';
const bctrl = new Bctrl({ apiKey: process.env.BCTRL_API_KEY! });

const started = await bctrl.sessions.start();
console.log(started.id, started.hostId);

// Raw sessions API
const connected = await bctrl.sessions.connect(started.id, { driver: 'playwright' });
console.log(connected.currentDriver);

// High-level convenience
const session = await bctrl.session.playwright();
await session.page.goto('https://example.com');

​
Response

​
id
string
required
Session ID.
​
hostId
string
required
Host the session is running on.
​
status
string
required
Session status (active).
​
storageWorkspace
string
Storage workspace name.
Response Example
{
  "id": "sess_abc123",
  "hostId": "host_1",
  "status": "active"
}