Quickstart

This page assumes you already have an invitation to a Ventus Sessions workspace. If you don't, ask the workspace owner to invite you, or contact support@ventus.ai.

1. Sign in

Go to dashboard.sessions.ventus.ai, enter your work email, and click Send sign-in link. Open the email ("Your sign-in link") and click through. You'll land at /onboarding the first time — name a workspace and pick a slug.

2. Mint an API key

From your workspace, open API keys → Create key. Give it a label ("local-dev", "ci-job", etc.) and copy the key — it's shown exactly once. Tokens are workspace-scoped; revoke them from the same screen.

export VENTUS_API_KEY=vs_01J…_<32 chars>

3. Start a session

The simplest possible call:

curl -X POST https://api.sessions.ventus.ai/v1/sessions \
  -H "Authorization: Bearer $VENTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime_kind": "chromium",
    "viewport":     { "width": 1280, "height": 720 },
    "region":       "us-east1"
  }'

Successful response (202 Accepted):

{
  "id": "01JC1AMQX4N3PWV9MR2BCKDH7E",
  "tenant_id": "01J…",
  "status": "QUEUED",
  "region": "us-east1",
  "runtime_kind": "chromium",
  "viewport": { "width": 1280, "height": 720, "device_scale_factor": 1.0 },
  "expires_at": "2026-05-18T01:30:00Z",
  "connect_url": null,
  "live_view_url": null
}

The session is created in QUEUED state. Poll GET /v1/sessions/{id} until status becomes RUNNING — that's when connect_url is populated. Typical transition takes 5–15 s.

States: QUEUED → PROVISIONING → RUNNING → COMPLETED (or ERRORED / EXPIRED).

4. Drive the browser

Use the Python SDK (TypeScript SDK is planned, not yet shipped — drive CDP directly with Playwright from Node in the meantime):

import asyncio
from ventus_sessions_sdk import Sessions

async def main():
    client = Sessions()  # reads VENTUS_API_KEY
    async with client.session() as session:
        await session.page.goto("https://example.com")
        title = await session.page.title()
        print(title)

asyncio.run(main())

# wscat -c "$connect_url" -x '{"id":1,"method":"Page.navigate","params":{"url":"https://example.com"}}'

5. Watch it run (coming in v0.2)

When live view ships, you'll open the live_view_url in another tab to watch the desktop in real time — useful for debugging CAPTCHA flows, human-handoff steps, or just convincing yourself the automation is doing the right thing.

Today the manager has no handler for that URL, so don't expose it to end users. Use Playwright's own tooling — page.screenshot(), page.video(), the Recorder — for visibility in the meantime.

6. Release

When you're done, release the session:

curl -X PATCH https://api.sessions.ventus.ai/v1/sessions/$SESSION_ID \
  -H "Authorization: Bearer $VENTUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "REQUEST_RELEASE"}'

The terminal status will be COMPLETED with release_reason: "client_release". The SDKs do this automatically via async with / await session.release().

---

Next steps