Skip to Content
Passage PlatformQuickstart

Platform Quickstart

Get up and running with Passage Platform — create a session, connect via WebSocket, and send your first command.

Prerequisites

  • A Passage API key
  • A backend server that can open WebSocket connections

Step 1: Create a session

curl -X POST https://platform.services.getpassage.ai/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"user_id": "user_123"}}'

The response includes the session ID and tokens for both the worker and client connections:

{
  "id": "session_abc123",
  "worker_token": "wt_...",
  "client_token": "ct_...",
  "status": "created"
}

Step 2: Connect via WebSocket

Open a WebSocket connection as the worker:

wss://sessions.services.getpassage.ai/sessions/session_abc123/ws?role=worker&token=wt_...

Send a worker.hello message to complete the handshake:

{ "type": "worker.hello" }

Step 3: Send a command

Once the client SDK connects (the session moves to active), send a navigate command:

{
  "type": "worker.command",
  "command": {
    "type": "navigate",
    "url": "https://example.com/login"
  }
}

The client executes the command and the session actor relays the result back to you as a server.command_result.

Step 4: Yield to user

When the user needs to interact (e.g., enter credentials), yield control:

{
  "type": "worker.yield_to_user",
  "conditions": [
    {
      "type": "url",
      "pattern": "https://example\\.com/dashboard.*"
    }
  ]
}

The webview becomes visible. When the user finishes and the URL matches your condition, you get the result and can continue sending commands.

Step 5: Complete the session

When your automation is done:

{
  "type": "worker.complete",
  "result": { "account_id": "12345" }
}

Next steps

Last updated on
OverviewSessions